@vauban-org/agent-sdk 0.16.0

package/src/compute/verifier.ts

@@ -0,0 +1,84 @@
+/**
+ * Verifier — caller-provided domain-specific evaluation interface.
+ *
+ * Design intent:
+ * - No built-in verifier pool or registry. Each caller constructs their own
+ *   verifier that encodes domain knowledge (math, code correctness, policy, …).
+ * - `evaluate` may be sync or async to accommodate both lightweight heuristics
+ *   and LLM-backed judges without forcing unnecessary Promise overhead.
+ * - `name` is mandatory for telemetry correlation (spans, metrics, logs).
+ */
+
+// ─── Result ──────────────────────────────────────────────────────────────────
+
+/** Output of a single verifier evaluation. */
+export interface VerifierResult {
+  /**
+   * Continuous score in [0, 1] inclusive.
+   * 0 = reject (completely wrong), 1 = accept (fully correct).
+   * Intermediate values signal partial quality (e.g. 0.75 = mostly correct).
+   */
+  score: number;
+  /** Human-readable explanation of the score for debugging and audit. */
+  rationale: string;
+}
+
+// ─── Interface ───────────────────────────────────────────────────────────────
+
+/**
+ * Domain-specific verifier supplied by the caller.
+ *
+ * @typeParam TOutput - Shape of the agent output being evaluated.
+ *   Defaults to `unknown` so callers can start untyped and tighten later.
+ */
+export interface Verifier<TOutput = unknown> {
+  /**
+   * Stable identifier used in telemetry (spans, metrics, audit logs).
+   * Recommended format: kebab-case, e.g. "math-correctness", "policy-guard".
+   */
+  readonly name: string;
+
+  /**
+   * Evaluate the agent output and return a quality score with rationale.
+   *
+   * Returning a plain `VerifierResult` (no Promise) is allowed for sync
+   * verifiers to avoid unnecessary microtask overhead. Callers that `await`
+   * the result handle both cases transparently.
+   */
+  evaluate(output: TOutput): Promise<VerifierResult> | VerifierResult;
+}
+
+// ─── Runtime guard ───────────────────────────────────────────────────────────
+
+/**
+ * Assert that `r` is a valid {@link VerifierResult} at runtime.
+ *
+ * Throws a `TypeError` with a descriptive message when:
+ * - `r` is null or not an object
+ * - `score` is not a finite number in [0, 1]
+ * - `rationale` is not a string
+ *
+ * Use this after `await verifier.evaluate(output)` when the verifier is
+ * provided by untrusted third-party code.
+ */
+export function assertVerifierResult(r: VerifierResult): void {
+  if (r === null || r === undefined || typeof r !== "object") {
+    throw new TypeError(
+      `assertVerifierResult: expected an object, got ${r === null ? "null" : typeof r}`,
+    );
+  }
+
+  const { score, rationale } = r as unknown as Record<string, unknown>;
+
+  if (typeof score !== "number" || !Number.isFinite(score) || score < 0 || score > 1) {
+    throw new TypeError(
+      `assertVerifierResult: score must be a finite number in [0,1], got ${String(score)}`,
+    );
+  }
+
+  if (typeof rationale !== "string") {
+    throw new TypeError(
+      `assertVerifierResult: rationale must be a string, got ${typeof rationale}`,
+    );
+  }
+}

package/src/compute/with-compute.ts

@@ -0,0 +1,108 @@
+/**
+ * src/compute/with-compute.ts
+ *
+ * Public `withCompute()` API — caller-explicit strategy entry point.
+ *
+ * Contract (Sprint A):
+ * - Strategy is REQUIRED and explicit (no auto-routing).
+ * - Returns `StrategyResult<O>` whose `metadata.strategy` equals the strategy's `name`.
+ * - Pre-flight guards run BEFORE invoking the generator:
+ *     1. `strategy` must be a non-null object with a usable `run` function.
+ *     2. `budget.maxCalls === 0` → throw `BudgetExhaustedError`.
+ *     3. `deadline` already past → throw `DeadlineExceededError`.
+ *     4. `signal` already aborted → throw the signal's `reason` (DOMException 'AbortError' by default).
+ * - Generator rejections bubble up unchanged.
+ */
+
+import type { ComputeContext, Strategy, StrategyResult } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+export class InvalidStrategyError extends Error {
+  override readonly name = "InvalidStrategyError";
+  constructor(message = "withCompute: `strategy` is required and must implement Strategy<I,O>") {
+    super(message);
+  }
+}
+
+export class BudgetExhaustedError extends Error {
+  override readonly name = "BudgetExhaustedError";
+  constructor(message = "withCompute: budget exhausted (maxCalls=0)") {
+    super(message);
+  }
+}
+
+export class DeadlineExceededError extends Error {
+  override readonly name = "DeadlineExceededError";
+  constructor(message = "withCompute: deadline exceeded before invocation") {
+    super(message);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface ComputeBudget {
+  /** Maximum number of generator calls allowed. `0` halts immediately. */
+  maxCalls?: number;
+}
+
+export interface WithComputeOptions<TInput, TOutput> {
+  /** Caller-explicit strategy. No auto-routing. */
+  strategy: Strategy<TInput, TOutput>;
+  /** Generator invoked by the strategy. */
+  generator: (input: TInput, ctx: ComputeContext) => Promise<TOutput>;
+  /** Optional cost cap. */
+  budget?: ComputeBudget;
+  /** Epoch milliseconds. If `Date.now() >= deadline` at entry, throws. */
+  deadline?: number;
+  /** Optional cancellation signal — wired into ComputeContext. */
+  signal?: AbortSignal;
+}
+
+export type WithComputeResult<TOutput> = StrategyResult<TOutput>;
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+function isStrategyLike<I, O>(value: unknown): value is Strategy<I, O> {
+  if (value === null || typeof value !== "object") return false;
+  const v = value as { name?: unknown; run?: unknown };
+  return typeof v.name === "string" && typeof v.run === "function";
+}
+
+/**
+ * Run a compute task under an explicit strategy with pre-flight budget/deadline/abort guards.
+ */
+export async function withCompute<TInput, TOutput>(
+  input: TInput,
+  options: WithComputeOptions<TInput, TOutput>,
+): Promise<WithComputeResult<TOutput>> {
+  // Guard 1: strategy must be valid (runtime guard for JS callers).
+  if (!options || !isStrategyLike<TInput, TOutput>(options.strategy)) {
+    throw new InvalidStrategyError();
+  }
+
+  // Guard 2: budget zero → halt before any work.
+  if (options.budget?.maxCalls === 0) {
+    throw new BudgetExhaustedError();
+  }
+
+  // Guard 3: deadline already past.
+  if (typeof options.deadline === "number" && Date.now() >= options.deadline) {
+    throw new DeadlineExceededError();
+  }
+
+  // Guard 4: abort signal already triggered.
+  if (options.signal?.aborted) {
+    throw options.signal.reason ?? new DOMException("Aborted", "AbortError");
+  }
+
+  const ctx: ComputeContext = options.signal ? { signal: options.signal } : {};
+
+  return options.strategy.run(input, options.generator, ctx);
+}