@vauban-org/agent-sdk 0.16.0

package/src/economy/router.ts

@@ -0,0 +1,246 @@
+/**
+ * economy/router — EconomyRouter dual-mode (Sprint D).
+ *
+ * Decides WHICH model tier to use for a given task category, based on
+ * observed cost-per-cycle data from OutcomeTracker. Sits ABOVE TierPolicy
+ * (which produces the candidate set) and is informed by FleetCircuitBreaker.
+ *
+ * NOT to be confused with the compute-strategy router (withCompute, Sprint A)
+ * or the legacy heuristic complexity router (src/router/llm-router.ts).
+ *
+ * Substrate-pure: no consumer-specific product references.
+ */
+
+import type { ModelTier, TierPolicy } from "./tier-policy.js";
+import type { OutcomeTracker, CycleCost } from "./outcome-tracker.js";
+import type { FleetCircuitBreaker } from "./circuit-breaker.js";
+
+// ─── Public types ─────────────────────────────────────────────────────────
+
+export type EconomyMode = "degraded" | "full";
+
+export interface EconomyRouterConfig {
+  mode: EconomyMode;
+  policy: TierPolicy;
+  tracker: OutcomeTracker;
+  breaker: FleetCircuitBreaker;
+  /** Fraction of budget to leave as buffer when filtering tiers by cost. Default 0.1 (10%). */
+  budgetBuffer?: number;
+}
+
+export interface RouteDecision {
+  tier: ModelTier;
+  mode: EconomyMode;
+  reason: string;
+  blockedByBreaker: boolean;
+}
+
+// ─── Internal constants ───────────────────────────────────────────────────
+
+/** Default rolling cost-window for tier-cost averaging. 1 hour. */
+const COST_WINDOW_MS = 3_600_000;
+
+/**
+ * Cost ceiling for "cheap-enough to upgrade" heuristic, in USD per cycle.
+ * Below this average cycle cost, the router will try a tier ABOVE the policy
+ * default (better quality at acceptable cost). Above it, downgrade.
+ */
+const UPGRADE_THRESHOLD_USD = 0.005;
+const DOWNGRADE_THRESHOLD_USD = 0.05;
+
+// ─── EconomyRouter ────────────────────────────────────────────────────────
+
+/**
+ * EconomyRouter — model tier selector informed by observed costs.
+ *
+ * Degraded mode: cost lookup is per task category.
+ * Full mode (Sprint C): cost lookup is per skillId. Falls back to degraded
+ *   when no skill data is available.
+ */
+export class EconomyRouter {
+  private readonly _mode: EconomyMode;
+  private readonly _policy: TierPolicy;
+  private readonly _tracker: OutcomeTracker;
+  private readonly _breaker: FleetCircuitBreaker;
+  private readonly _budgetBuffer: number;
+
+  /** Total `route()` calls. */
+  private _totalRouteCalls = 0;
+  /** Calls where `blockedByBreaker` was false. */
+  private _nonBlockedRouteCalls = 0;
+
+  constructor(config: EconomyRouterConfig) {
+    this._mode = config.mode;
+    this._policy = config.policy;
+    this._tracker = config.tracker;
+    this._breaker = config.breaker;
+    this._budgetBuffer = config.budgetBuffer ?? 0.1;
+  }
+
+  /**
+   * Decide which tier to use for a task.
+   *
+   * Caller is responsible for honouring `blockedByBreaker` — when true,
+   * the returned tier is informational and the caller should typically
+   * defer or run a degraded execution path.
+   */
+  route(
+    category: string,
+    opts?: { skillId?: string; budgetRemainingUsd?: number },
+  ): RouteDecision {
+    this._totalRouteCalls += 1;
+
+    const blockedByBreaker = !this._breaker.canProceed();
+    const candidates = this._policy.tiersFor(category, this._mode);
+    if (candidates.length === 0) {
+      // Defensive: empty candidate set should never happen with DefaultTierPolicy
+      // but custom policies might. Surface a clear error.
+      throw new Error(
+        `EconomyRouter: TierPolicy returned no candidates for category "${category}"`,
+      );
+    }
+
+    // Apply budget filter (if provided).
+    const budget = opts?.budgetRemainingUsd;
+    const affordable =
+      budget !== undefined
+        ? candidates.filter((t) => this._estimateCallCost(t) <= budget * (1 - this._budgetBuffer))
+        : candidates;
+
+    // If budget filtered everything, fall back to cheapest known tier.
+    let pool = affordable.length > 0 ? affordable : [this._cheapest(candidates)];
+
+    // Cost-history-driven tier selection.
+    const avgCost = this._observedAvgCostUsd(category, opts?.skillId);
+    let chosen: ModelTier;
+    let reason: string;
+
+    if (avgCost === undefined) {
+      // No history — use policy default (head of list, intersected with affordable pool).
+      chosen = pool[0]!;
+      reason = "default-tier-no-history";
+    } else if (avgCost < UPGRADE_THRESHOLD_USD) {
+      // Cheap-enough average → try to upgrade one tier.
+      chosen = pool.length >= 2 ? pool[1]! : pool[0]!;
+      reason = pool.length >= 2 ? "upgrade-cheap-history" : "default-no-upgrade-available";
+    } else if (avgCost > DOWNGRADE_THRESHOLD_USD) {
+      // Too expensive on average → downgrade to cheapest of pool.
+      chosen = this._cheapest(pool);
+      reason = "downgrade-expensive-history";
+    } else {
+      // Within band — keep policy default (head of pool).
+      chosen = pool[0]!;
+      reason = "default-tier-within-band";
+    }
+
+    if (!blockedByBreaker) {
+      this._nonBlockedRouteCalls += 1;
+    }
+
+    return {
+      tier: chosen,
+      mode: this._mode,
+      reason: blockedByBreaker ? `${reason}+breaker-open` : reason,
+      blockedByBreaker,
+    };
+  }
+
+  /**
+   * Record outcome of a completed cycle. Propagates to OutcomeTracker
+   * (which computes cost from pricing) AND to FleetCircuitBreaker.
+   *
+   * The model identifier sent to the tracker is `provider/model` per
+   * tracker convention.
+   */
+  recordOutcome(
+    runId: string,
+    tier: ModelTier,
+    inputTokens: number,
+    outputTokens: number,
+    durationMs: number,
+    opts?: {
+      skillId?: string;
+      outcomeValue?: number;
+      category?: string;
+    },
+  ): void {
+    const modelStr = `${tier.provider}/${tier.model}`;
+    const cost = this._tracker.record(
+      runId,
+      modelStr,
+      inputTokens,
+      outputTokens,
+      durationMs,
+      {
+        ...(opts?.skillId !== undefined ? { skillId: opts.skillId } : {}),
+        ...(opts?.outcomeValue !== undefined
+          ? { outcomeValue: opts.outcomeValue }
+          : {}),
+        ...(opts?.category !== undefined ? { category: opts.category } : {}),
+      },
+    );
+    this._breaker.recordCost(cost.costUsd);
+  }
+
+  /**
+   * Routing rate: fraction of `route()` calls that returned non-blocked.
+   * 0 when no calls have been made (cannot divide by zero).
+   */
+  get routingRate(): number {
+    if (this._totalRouteCalls === 0) return 0;
+    return this._nonBlockedRouteCalls / this._totalRouteCalls;
+  }
+
+  // ─── Private helpers ───────────────────────────────────────────────────
+
+  /**
+   * Compute average cost-per-cycle observed within the rolling window.
+   *
+   * In "full" mode with a skillId, we filter records by skillId.
+   * Falls back to category filtering when:
+   *   - mode is degraded, OR
+   *   - skillId is undefined, OR
+   *   - no records match the skillId.
+   *
+   * Returns undefined when no records match (caller treats as "no history").
+   */
+  private _observedAvgCostUsd(
+    category: string,
+    skillId: string | undefined,
+  ): number | undefined {
+    const all = this._tracker.getCosts(COST_WINDOW_MS);
+    if (all.length === 0) return undefined;
+
+    let pool: CycleCost[] = [];
+    if (this._mode === "full" && skillId !== undefined) {
+      pool = all.filter((r) => r.skillId === skillId);
+      if (pool.length === 0) {
+        // Fall back to category in full mode when no skill data yet.
+        pool = all.filter((r) => r.category === category);
+      }
+    } else {
+      pool = all.filter((r) => r.category === category);
+    }
+
+    if (pool.length === 0) return undefined;
+    const sum = pool.reduce((acc, r) => acc + r.costUsd, 0);
+    return sum / pool.length;
+  }
+
+  /**
+   * Estimate the cost (USD) of one tier call. Used for budget filtering.
+   * Heuristic: assume 1k output tokens per call (output dominates cost).
+   */
+  private _estimateCallCost(tier: ModelTier): number {
+    return (1_000 / 1_000_000) * tier.costPerMTokenOut;
+  }
+
+  /** Return the cheapest tier in a non-empty list (by output cost). */
+  private _cheapest(tiers: ModelTier[]): ModelTier {
+    let best = tiers[0]!;
+    for (const t of tiers) {
+      if (t.costPerMTokenOut < best.costPerMTokenOut) best = t;
+    }
+    return best;
+  }
+}

package/src/economy/tier-policy.ts

@@ -0,0 +1,116 @@
+/**
+ * economy/tier-policy — Model tier catalog and routing policy.
+ *
+ * Substrate-pure: no consumer-specific names anywhere.
+ * Consumers inject a custom TierPolicy implementation to override defaults.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface ModelTier {
+  /** Provider identifier: "litellm" | "groq" | "anthropic" | etc. */
+  provider: string;
+  /** Model alias as configured in the provider. e.g. "default-fast", "deepseek-v4-flash". */
+  model: string;
+  /** USD per 1M input tokens. 0 when unknown or local (free). */
+  costPerMTokenIn: number;
+  /** USD per 1M output tokens. */
+  costPerMTokenOut: number;
+  label: "free" | "cheap" | "mid" | "premium";
+}
+
+export interface TierPolicy {
+  /**
+   * Return an ordered list of tiers to try for a given task category.
+   * First element = preferred tier.
+   *
+   * @param category - Task category: "simple" | "standard" | "complex" | "reasoning" | string
+   * @param mode     - "degraded" uses cost-minimising static routing;
+   *                   "full" allows observed cost-per-outcome to influence order.
+   */
+  tiersFor(category: string, mode: "degraded" | "full"): ModelTier[];
+}
+
+// ─── Built-in tier catalog ────────────────────────────────────────────────
+
+/** Tier 0 — local Qwen3-8B via LiteLLM proxy. Free. */
+const TIER_FREE: ModelTier = {
+  provider: "litellm",
+  model: "default-fast",
+  costPerMTokenIn: 0,
+  costPerMTokenOut: 0,
+  label: "free",
+};
+
+/** Tier 1 — DeepSeek Flash via LiteLLM proxy. Low cost. */
+const TIER_CHEAP: ModelTier = {
+  provider: "litellm",
+  model: "deepseek-v4-flash",
+  costPerMTokenIn: 0.14,
+  costPerMTokenOut: 0.28,
+  label: "cheap",
+};
+
+/** Tier 2 — Groq free tier (llama-3.3-70b-versatile). Mid quality, near-zero cost. */
+const TIER_MID: ModelTier = {
+  provider: "groq",
+  model: "llama-3.3-70b-versatile",
+  costPerMTokenIn: 0.0,
+  costPerMTokenOut: 0.0,
+  label: "mid",
+};
+
+/** Tier 3 — DeepSeek Pro via LiteLLM proxy. Premium. */
+const TIER_PREMIUM: ModelTier = {
+  provider: "litellm",
+  model: "deepseek-v4-pro",
+  costPerMTokenIn: 0.27,
+  costPerMTokenOut: 1.1,
+  label: "premium",
+};
+
+// ─── Static category → tier index mapping ─────────────────────────────────
+
+const DEGRADED_ROUTING: Record<string, ModelTier[]> = {
+  simple: [TIER_FREE, TIER_CHEAP],
+  standard: [TIER_CHEAP, TIER_MID],
+  complex: [TIER_MID, TIER_PREMIUM],
+  reasoning: [TIER_PREMIUM],
+};
+
+const DEFAULT_DEGRADED: ModelTier[] = [TIER_CHEAP, TIER_MID];
+
+// ─── DefaultTierPolicy ────────────────────────────────────────────────────
+
+/**
+ * DefaultTierPolicy — static cost-minimising routing.
+ *
+ * "degraded" mode: purely static, category → ordered tier list.
+ * "full" mode: same tiers returned in same order; the *caller* (economy router)
+ *   is responsible for re-ordering by observed cost-per-outcome from OutcomeTracker.
+ *   This class only supplies the candidate set.
+ */
+export class DefaultTierPolicy implements TierPolicy {
+  tiersFor(category: string, _mode: "degraded" | "full"): ModelTier[] {
+    // Both modes return the same candidate set; re-ordering in "full" mode
+    // is the router's responsibility (Sprint D router.ts, not this class).
+    const tiers = DEGRADED_ROUTING[category] ?? DEFAULT_DEGRADED;
+    // Return a copy to prevent external mutation of the catalog.
+    return [...tiers];
+  }
+}
+
+// ─── Catalog helpers ──────────────────────────────────────────────────────
+
+/**
+ * Look up a ModelTier by provider+model from the built-in catalog.
+ * Returns undefined if the model is not in the default catalog
+ * (consumers may use custom tiers not registered here).
+ */
+export function lookupTier(
+  provider: string,
+  model: string,
+): ModelTier | undefined {
+  const catalog: ModelTier[] = [TIER_FREE, TIER_CHEAP, TIER_MID, TIER_PREMIUM];
+  return catalog.find((t) => t.provider === provider && t.model === model);
+}

package/src/errors.ts

@@ -0,0 +1,159 @@
+/**
+ * Typed port errors (Sprint-459).
+ *
+ * Agent handlers can pattern-match on concrete classes to implement
+ * intelligent retry, HITL escalation, or graceful degradation:
+ *
+ *   try {
+ *     await deps.brain.archiveKnowledge(entry);
+ *   } catch (err) {
+ *     if (err instanceof BrainRateLimit) {
+ *       await sleep(err.retryAfterMs);
+ *       return retry();
+ *     }
+ *     if (err instanceof BrainUnavailable) {
+ *       return { skipped: true, reason: "brain down" };
+ *     }
+ *     throw err;
+ *   }
+ *
+ * All port-error classes extend `PortError` for a single instanceof check
+ * when agents want to distinguish port failures from tool / LLM failures.
+ *
+ * Errors carry a `cause` field (native Error cause) so the underlying
+ * exception remains debuggable; and a `retryable` boolean so orchestrators
+ * can apply generic retry policies without class-specific knowledge.
+ */
+
+/** Base class for every port-layer error thrown by an SDK-injected port. */
+export abstract class PortError extends Error {
+  /** Port identifier that raised the error (e.g. "brain", "db"). */
+  abstract readonly port: string;
+  /** True if the caller MAY retry after some backoff. */
+  readonly retryable: boolean;
+
+  constructor(
+    message: string,
+    options: { cause?: unknown; retryable?: boolean } = {},
+  ) {
+    super(message);
+    this.name = new.target.name;
+    this.retryable = options.retryable ?? false;
+    // Ensure `.cause` is preserved across node versions.
+    if (options.cause !== undefined) {
+      (this as { cause?: unknown }).cause = options.cause;
+    }
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+// ─── Brain port errors ────────────────────────────────────────────────────
+
+export class BrainUnavailable extends PortError {
+  readonly port = "brain";
+  constructor(message = "Brain service unreachable", cause?: unknown) {
+    super(message, { cause, retryable: true });
+  }
+}
+
+export class BrainRateLimit extends PortError {
+  readonly port = "brain";
+  /** Server-advised wait before retry. Missing if unknown. */
+  readonly retryAfterMs?: number;
+  constructor(
+    opts: { message?: string; retryAfterMs?: number; cause?: unknown } = {},
+  ) {
+    super(opts.message ?? "Brain rate limit exceeded", {
+      cause: opts.cause,
+      retryable: true,
+    });
+    this.retryAfterMs = opts.retryAfterMs;
+  }
+}
+
+export class BrainValidationError extends PortError {
+  readonly port = "brain";
+  constructor(message: string, cause?: unknown) {
+    super(message, { cause, retryable: false });
+  }
+}
+
+export class BrainAuthError extends PortError {
+  readonly port = "brain";
+  constructor(message = "Brain auth rejected", cause?: unknown) {
+    super(message, { cause, retryable: false });
+  }
+}
+
+// ─── Db port errors ───────────────────────────────────────────────────────
+
+export class DbConnectionLost extends PortError {
+  readonly port = "db";
+  constructor(message = "Database connection lost", cause?: unknown) {
+    super(message, { cause, retryable: true });
+  }
+}
+
+export class DbQueryError extends PortError {
+  readonly port = "db";
+  /** The SQL fragment that failed (first 200 chars). */
+  readonly sqlPreview?: string;
+  constructor(opts: { message: string; cause?: unknown; sqlPreview?: string }) {
+    super(opts.message, { cause: opts.cause, retryable: false });
+    this.sqlPreview = opts.sqlPreview?.slice(0, 200);
+  }
+}
+
+// ─── Outcome port errors ──────────────────────────────────────────────────
+
+export class OutcomeAttributionFailed extends PortError {
+  readonly port = "outcome";
+  /** agent_run.id that failed to attribute. */
+  readonly runId: string;
+  constructor(runId: string, message: string, cause?: unknown) {
+    super(message, { cause, retryable: false });
+    this.runId = runId;
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+// ─── OODA audit errors ────────────────────────────────────────────────────
+
+/**
+ * Thrown by `triggerCycle()` when `opts.dryRun` is not explicitly set.
+ *
+ * Audit-ready agents must declare execution intent at every call site.
+ * Passing `{dryRun: true}` for non-destructive runs, `{dryRun: false}` for
+ * live execution, prevents accidental side-effect execution.
+ *
+ * @public
+ */
+export class MissingDryRunFlagError extends Error {
+  constructor() {
+    super(
+      "triggerCycle() requires explicit dryRun flag (true|false). Audit-ready agents must declare execution intent.",
+    );
+    this.name = "MissingDryRunFlagError";
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * True if the error is a PortError produced by the named port.
+ * Convenience for narrow error handling without leaking class imports.
+ */
+export function isPortError(err: unknown, port?: string): err is PortError {
+  if (!(err instanceof PortError)) return false;
+  if (port !== undefined && err.port !== port) return false;
+  return true;
+}
+
+/**
+ * True if the error is a PortError and the originating port marked it
+ * retryable. Returns false for unknown errors — caller should rethrow.
+ */
+export function isRetryablePortError(err: unknown): err is PortError {
+  return err instanceof PortError && err.retryable;
+}