pi-smart-router 0.1.0

package/src/infra/telemetry.ts

@@ -0,0 +1,169 @@
+/**
+ * Privacy-safe community telemetry export (SP-082).
+ *
+ * Maps routing telemetry rows to anonymized community export shapes and
+ * HyDRA calibration batches. Never exports prompt text, messages, request_id,
+ * or raw session_id — session identifiers are one-way hashed only.
+ */
+
+import { createHash } from 'node:crypto';
+
+import type {
+  RoutingFeatureSidecar,
+  RoutingTelemetry,
+} from '../domain/types/index.js';
+
+export const COMMUNITY_TELEMETRY_ENABLED_ENV = 'SMART_ROUTER_COMMUNITY_TELEMETRY';
+
+export const COMMUNITY_TELEMETRY_ENABLED_NOTIFY_MESSAGE =
+  'Smart Router community telemetry export is enabled. Only anonymized routing metadata is exported — no prompt text, messages, or raw session identifiers.';
+
+export const TELEMETRY_EXPORT_FORBIDDEN_KEYS = [
+  'session_id',
+  'request_id',
+  'prompt_text',
+  'messages',
+  'prompt',
+  'pepper',
+  'install_pepper',
+  'dataset_pepper',
+  'dataset_key',
+  'prompt_fingerprint',
+] as const;
+
+export const HYDRA_CALIBRATION_STAGE = 'hydra_match' as const;
+
+export function isCommunityTelemetryExportEnabled(): boolean {
+  return process.env[COMMUNITY_TELEMETRY_ENABLED_ENV] === '1';
+}
+
+/** One-way hash for session correlation without exporting raw session_id. */
+export function hashSessionIdForTelemetryExport(sessionId: string): string {
+  return createHash('sha256').update(sessionId).digest('hex');
+}
+
+export interface CommunityTelemetryRecord {
+  readonly timestamp: string;
+  readonly session_id_hash: string;
+  readonly turn_type: string;
+  readonly stage: string;
+  readonly reason_code: string;
+  readonly selected_model_id: string;
+  readonly estimated_cost_usd: number;
+  readonly routing_latency_ms: number;
+  readonly pin_reason: string | null;
+}
+
+/** HyDRA calibration row — routing signals only, no prompt content. */
+export interface HydraCalibrationRecord {
+  readonly timestamp: string;
+  readonly session_id_hash: string;
+  readonly turn_type: string;
+  readonly reason_code: string;
+  readonly selected_model_id: string;
+  readonly routing_latency_ms: number;
+  readonly requirement_reasoning: number | null;
+  readonly requirement_code_gen: number | null;
+  readonly requirement_tool_use: number | null;
+  readonly top_candidate_model_id: string | null;
+  readonly top_candidate_score: number | null;
+}
+
+export function isHydraMatchTelemetry(record: RoutingTelemetry): boolean {
+  return record.stage === HYDRA_CALIBRATION_STAGE;
+}
+
+export function selectHydraMatchTelemetry(
+  records: readonly RoutingTelemetry[],
+): readonly RoutingTelemetry[] {
+  return records.filter(isHydraMatchTelemetry);
+}
+
+/** Map a telemetry row to a privacy-safe community export object. */
+export function toCommunityTelemetryRecord(
+  record: RoutingTelemetry,
+): CommunityTelemetryRecord {
+  return {
+    timestamp: record.timestamp,
+    session_id_hash: hashSessionIdForTelemetryExport(record.session_id),
+    turn_type: record.turn_type,
+    stage: record.stage,
+    reason_code: record.reason_code,
+    selected_model_id: record.selected_model_id,
+    estimated_cost_usd: record.estimated_cost_usd,
+    routing_latency_ms: record.routing_latency_ms,
+    pin_reason: record.pin_reason,
+  };
+}
+
+function topViableCandidate(features: RoutingFeatureSidecar | undefined): {
+  readonly model_id: string | null;
+  readonly score: number | null;
+} {
+  const candidates = features?.candidates;
+  if (!candidates || candidates.length === 0) {
+    return { model_id: null, score: null };
+  }
+
+  const viable = candidates.filter((candidate) => candidate.rejected_reason === null);
+  const pool = viable.length > 0 ? viable : [...candidates];
+  const best = pool.reduce((leading, candidate) =>
+    candidate.score > leading.score ? candidate : leading,
+  );
+
+  return { model_id: best.model_id, score: best.score };
+}
+
+/** Map a hydra_match telemetry row to a collaborative calibration export row. */
+export function toHydraCalibrationRecord(
+  record: RoutingTelemetry,
+  features?: RoutingFeatureSidecar,
+): HydraCalibrationRecord {
+  const requirements = features?.requirements ?? null;
+  const top = topViableCandidate(features);
+
+  return {
+    timestamp: record.timestamp,
+    session_id_hash: hashSessionIdForTelemetryExport(record.session_id),
+    turn_type: record.turn_type,
+    reason_code: record.reason_code,
+    selected_model_id: record.selected_model_id,
+    routing_latency_ms: record.routing_latency_ms,
+    requirement_reasoning: requirements?.reasoning ?? null,
+    requirement_code_gen: requirements?.code_gen ?? null,
+    requirement_tool_use: requirements?.tool_use ?? null,
+    top_candidate_model_id: top.model_id,
+    top_candidate_score: top.score,
+  };
+}
+
+export function formatCommunityTelemetryJsonl(
+  records: readonly RoutingTelemetry[],
+): string {
+  return records
+    .map((record) => JSON.stringify(toCommunityTelemetryRecord(record)))
+    .join('\n');
+}
+
+export function formatHydraCalibrationJsonl(
+  records: readonly RoutingTelemetry[],
+  featuresByRequestId?: ReadonlyMap<string, RoutingFeatureSidecar>,
+): string {
+  return selectHydraMatchTelemetry(records)
+    .map((record) => {
+      const features = featuresByRequestId?.get(record.request_id);
+      return JSON.stringify(toHydraCalibrationRecord(record, features));
+    })
+    .join('\n');
+}
+
+/** Defense-in-depth scrub for loose export objects. */
+export function scrubTelemetryExportObject(
+  value: Record<string, unknown>,
+): Record<string, unknown> {
+  const scrubbed = { ...value };
+  for (const key of TELEMETRY_EXPORT_FORBIDDEN_KEYS) {
+    delete scrubbed[key];
+  }
+  return scrubbed;
+}

package/src/infrastructure/delegation/provider-error.ts

@@ -0,0 +1,251 @@
+/**
+ * Parse provider error payloads from pi-ai assistant errorMessage strings.
+ */
+
+import type { AssistantMessage } from '@earendil-works/pi-ai/compat';
+import { isContextOverflow } from '@earendil-works/pi-ai';
+
+import {
+  formatGeminiThoughtSignatureErrorMessage,
+  isGeminiThoughtSignatureAssistantError,
+  isGeminiThoughtSignatureError,
+} from '../../infra/gemini-provider.js';
+import { isInfraError } from '../gateway/circuit-breaker.js';
+
+export {
+  formatGeminiThoughtSignatureErrorMessage,
+  isGeminiThoughtSignatureAssistantError,
+  isGeminiThoughtSignatureError,
+};
+
+export interface ParsedProviderError {
+  readonly statusCode?: number;
+  readonly code?: string;
+  readonly message?: string;
+}
+
+function parseNumericCode(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === 'string' && /^\d+$/.test(value)) {
+    return Number.parseInt(value, 10);
+  }
+  return undefined;
+}
+
+/**
+ * Extract HTTP status / error code from JSON provider error blobs.
+ */
+export function parseProviderError(errorMessage: string): ParsedProviderError | undefined {
+  const trimmed = errorMessage.trim();
+  if (!trimmed.startsWith('{')) {
+    const statusMatch = trimmed.match(/\b(429|5\d{2})\b/);
+    if (statusMatch) {
+      return { statusCode: Number.parseInt(statusMatch[1]!, 10) };
+    }
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed) as {
+      error?: { code?: unknown; status?: unknown; message?: unknown };
+      code?: unknown;
+      status?: unknown;
+      message?: unknown;
+    };
+
+    const nested = parsed.error;
+    const statusCode =
+      parseNumericCode(nested?.code) ??
+      parseNumericCode(nested?.status) ??
+      parseNumericCode(parsed.code) ??
+      parseNumericCode(parsed.status);
+
+    const code =
+      typeof nested?.status === 'string'
+        ? nested.status
+        : typeof parsed.status === 'string'
+          ? parsed.status
+          : undefined;
+
+    let message =
+      typeof nested?.message === 'string'
+        ? nested.message
+        : typeof parsed.message === 'string'
+          ? parsed.message
+          : undefined;
+
+    if (message && message.trim().startsWith('{')) {
+      try {
+        const inner = JSON.parse(message) as { error?: { message?: unknown }; message?: unknown };
+        if (typeof inner.error?.message === 'string') {
+          message = inner.error.message;
+        } else if (typeof inner.message === 'string') {
+          message = inner.message;
+        }
+      } catch {
+        // Nested provider error payloads may be malformed JSON — keep outer message.
+      }
+    }
+
+    if (statusCode === undefined && code === undefined && message === undefined) {
+      return undefined;
+    }
+
+    return {
+      ...(statusCode !== undefined ? { statusCode } : {}),
+      ...(code ? { code } : {}),
+      ...(message ? { message } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function parseAssistantMessageError(
+  message: AssistantMessage,
+): ParsedProviderError | undefined {
+  if (message.stopReason !== 'error' || !message.errorMessage) {
+    return undefined;
+  }
+  return parseProviderError(message.errorMessage);
+}
+
+export function isInfraAssistantError(message: AssistantMessage): boolean {
+  const parsed = parseAssistantMessageError(message);
+  if (!parsed) {
+    return false;
+  }
+  return isInfraError(parsed);
+}
+
+const FORMATTED_ERROR_MAX_LENGTH = 200;
+
+/** Output tokens at or below this count are treated as no usable generation. */
+export const NEGLIGIBLE_OUTPUT_TOKEN_MAX = 4;
+
+/** Input ratio of context window that signals context pressure on length stops. */
+export const LENGTH_STOP_CONTEXT_PRESSURE_RATIO = 0.99;
+
+export type LengthStopKind = 'context_pressure' | 'output_truncation';
+
+export interface LengthStopHints {
+  readonly contextWindow?: number;
+}
+
+export function isNegligibleOutputTokens(outputTokens: number): boolean {
+  return outputTokens <= NEGLIGIBLE_OUTPUT_TOKEN_MAX;
+}
+
+function inputTokensUsed(message: AssistantMessage): number {
+  return message.usage.input + message.usage.cacheRead;
+}
+
+/**
+ * Classify a `stopReason: length` assistant message as context pressure vs output truncation.
+ */
+export function classifyLengthStop(
+  message: AssistantMessage,
+  hints?: LengthStopHints,
+): LengthStopKind | undefined {
+  if (message.stopReason !== 'length') {
+    return undefined;
+  }
+
+  if (!isNegligibleOutputTokens(message.usage.output)) {
+    return 'output_truncation';
+  }
+
+  const contextWindow = hints?.contextWindow;
+  if (contextWindow !== undefined) {
+    if (isContextOverflow(message, contextWindow)) {
+      return 'context_pressure';
+    }
+
+    const inputTokens = inputTokensUsed(message);
+    if (inputTokens >= contextWindow * LENGTH_STOP_CONTEXT_PRESSURE_RATIO) {
+      return 'context_pressure';
+    }
+  }
+
+  return 'output_truncation';
+}
+
+/**
+ * User-facing text for length stops — distinct wording for context pressure vs truncation.
+ */
+export function formatLengthStopMessage(
+  message: AssistantMessage,
+  hints?: LengthStopHints,
+): string {
+  const kind = classifyLengthStop(message, hints);
+  if (kind === 'context_pressure') {
+    const inputTokens = inputTokensUsed(message);
+    const limitSuffix =
+      hints?.contextWindow !== undefined
+        ? ` (context limit: ${hints.contextWindow.toLocaleString()} tokens)`
+        : '';
+    return (
+      `Context window exceeded: ${inputTokens.toLocaleString()} input tokens used${limitSuffix}, ` +
+      'leaving no room for output. Try compacting history or switching to a larger-context model.'
+    );
+  }
+
+  return (
+    'Model stopped because it reached the maximum output token limit. ' +
+    'The response may be incomplete.'
+  );
+}
+
+/**
+ * Rewrite context-pressure length stops as errors so pi surfaces the overflow message.
+ */
+export function sanitizeLengthStopMessage(
+  message: AssistantMessage,
+  hints?: LengthStopHints,
+): AssistantMessage {
+  if (classifyLengthStop(message, hints) !== 'context_pressure') {
+    return message;
+  }
+
+  return {
+    ...message,
+    stopReason: 'error',
+    errorMessage: formatLengthStopMessage(message, hints),
+  };
+}
+
+/**
+ * Format a provider error blob for user-facing display (terminal/session).
+ * Never returns raw nested JSON.
+ */
+export function formatProviderErrorMessage(errorMessage: string): string {
+  const parsed = parseProviderError(errorMessage);
+  if (parsed) {
+    const prefixParts: string[] = [];
+    if (parsed.statusCode !== undefined) {
+      prefixParts.push(String(parsed.statusCode));
+    }
+    if (parsed.code) {
+      prefixParts.push(parsed.code);
+    }
+    const prefix = prefixParts.length > 0 ? `${prefixParts.join(' ')}: ` : '';
+    if (parsed.message) {
+      return `${prefix}${parsed.message}`;
+    }
+    if (prefixParts.length > 0) {
+      return `Provider error (${prefixParts.join(' ')})`;
+    }
+  }
+
+  const trimmed = errorMessage.trim();
+  if (trimmed.startsWith('{')) {
+    return 'Provider error (unparseable response)';
+  }
+  if (trimmed.length > FORMATTED_ERROR_MAX_LENGTH) {
+    return `${trimmed.slice(0, FORMATTED_ERROR_MAX_LENGTH)}…`;
+  }
+  return trimmed;
+}
+

package/src/infrastructure/gateway/circuit-breaker.ts

@@ -0,0 +1,196 @@
+/**
+ * Circuit breaker for gateway dispatch — T055, FR-018, FR-022.
+ *
+ * Tracks consecutive infrastructure failures per model endpoint and trips
+ * the breaker when the threshold is exceeded. Only infra errors (timeouts,
+ * network failures, 5xx) count — policy/safety rejections (4xx content
+ * filtering, 403 auth) do NOT trigger the breaker (FR-018).
+ *
+ * States: CLOSED → OPEN → HALF_OPEN → CLOSED (on success) or OPEN (on fail).
+ */
+
+export type CircuitState = 'closed' | 'open' | 'half_open';
+
+export interface CircuitBreakerConfig {
+  /** Consecutive infra failures before tripping the breaker. */
+  readonly failureThreshold: number;
+  /** Milliseconds to remain in OPEN state before allowing a probe. */
+  readonly resetTimeoutMs: number;
+  /** Max consecutive successes in HALF_OPEN required to close. */
+  readonly halfOpenSuccesses: number;
+}
+
+export const DEFAULT_CIRCUIT_CONFIG: CircuitBreakerConfig = {
+  failureThreshold: 3,
+  resetTimeoutMs: 30_000,
+  halfOpenSuccesses: 2,
+};
+
+export interface CircuitSnapshot {
+  readonly modelId: string;
+  readonly state: CircuitState;
+  readonly consecutiveFailures: number;
+  readonly consecutiveSuccesses: number;
+  readonly lastFailureAt: number | null;
+  readonly lastStateChangeAt: number;
+}
+
+interface CircuitEntry {
+  state: CircuitState;
+  consecutiveFailures: number;
+  consecutiveSuccesses: number;
+  lastFailureAt: number | null;
+  lastStateChangeAt: number;
+}
+
+/**
+ * Returns true when the error is an infrastructure failure that should
+ * trigger the circuit breaker. Policy/safety rejections are excluded
+ * per FR-018.
+ */
+export function isInfraError(error: { statusCode?: number; code?: string; message?: string }): boolean {
+  if (error.code === 'ECONNREFUSED' || error.code === 'ECONNRESET' ||
+      error.code === 'ETIMEDOUT' || error.code === 'ENOTFOUND' ||
+      error.code === 'UND_ERR_CONNECT_TIMEOUT' || error.code === 'UND_ERR_SOCKET') {
+    return true;
+  }
+
+  if (error.statusCode !== undefined) {
+    if (error.statusCode >= 500 || error.statusCode === 429) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export class CircuitBreaker {
+  private readonly circuits = new Map<string, CircuitEntry>();
+  private readonly config: CircuitBreakerConfig;
+
+  constructor(config: Partial<CircuitBreakerConfig> = {}) {
+    this.config = { ...DEFAULT_CIRCUIT_CONFIG, ...config };
+  }
+
+  /**
+   * Check whether a model endpoint is available for requests.
+   * OPEN circuits reject immediately. OPEN circuits whose reset timeout
+   * has elapsed transition to HALF_OPEN and allow a probe.
+   */
+  canDispatch(modelId: string): boolean {
+    const entry = this.circuits.get(modelId);
+    if (!entry) return true;
+
+    if (entry.state === 'closed' || entry.state === 'half_open') {
+      return true;
+    }
+
+    const elapsed = Date.now() - entry.lastStateChangeAt;
+    if (elapsed >= this.config.resetTimeoutMs) {
+      entry.state = 'half_open';
+      entry.consecutiveSuccesses = 0;
+      entry.lastStateChangeAt = Date.now();
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Record a successful response from a model endpoint.
+   * In HALF_OPEN, accumulates successes until the threshold is met,
+   * then transitions to CLOSED. In CLOSED, resets the failure counter.
+   */
+  recordSuccess(modelId: string): void {
+    const entry = this.circuits.get(modelId);
+    if (!entry) return;
+
+    entry.consecutiveFailures = 0;
+
+    if (entry.state === 'half_open') {
+      entry.consecutiveSuccesses += 1;
+      if (entry.consecutiveSuccesses >= this.config.halfOpenSuccesses) {
+        entry.state = 'closed';
+        entry.lastStateChangeAt = Date.now();
+      }
+    } else if (entry.state === 'closed') {
+      entry.consecutiveSuccesses = 0;
+    }
+  }
+
+  /**
+   * Record an infrastructure failure from a model endpoint.
+   * Only infra errors should be reported here (caller checks isInfraError).
+   * HALF_OPEN → OPEN immediately. CLOSED → OPEN when threshold exceeded.
+   */
+  recordFailure(modelId: string): void {
+    const now = Date.now();
+    let entry = this.circuits.get(modelId);
+
+    if (!entry) {
+      entry = {
+        state: 'closed',
+        consecutiveFailures: 0,
+        consecutiveSuccesses: 0,
+        lastFailureAt: null,
+        lastStateChangeAt: now,
+      };
+      this.circuits.set(modelId, entry);
+    }
+
+    entry.consecutiveFailures += 1;
+    entry.lastFailureAt = now;
+    entry.consecutiveSuccesses = 0;
+
+    if (entry.state === 'half_open') {
+      entry.state = 'open';
+      entry.lastStateChangeAt = now;
+      return;
+    }
+
+    if (entry.consecutiveFailures >= this.config.failureThreshold) {
+      entry.state = 'open';
+      entry.lastStateChangeAt = now;
+    }
+  }
+
+  /** Get a read-only snapshot of a model's circuit state. */
+  getSnapshot(modelId: string): CircuitSnapshot {
+    const entry = this.circuits.get(modelId);
+    if (!entry) {
+      return {
+        modelId,
+        state: 'closed',
+        consecutiveFailures: 0,
+        consecutiveSuccesses: 0,
+        lastFailureAt: null,
+        lastStateChangeAt: 0,
+      };
+    }
+
+    return {
+      modelId,
+      state: entry.state,
+      consecutiveFailures: entry.consecutiveFailures,
+      consecutiveSuccesses: entry.consecutiveSuccesses,
+      lastFailureAt: entry.lastFailureAt,
+      lastStateChangeAt: entry.lastStateChangeAt,
+    };
+  }
+
+  /** Reset a specific model's circuit to CLOSED. */
+  reset(modelId: string): void {
+    this.circuits.delete(modelId);
+  }
+
+  /** List all model IDs with OPEN circuits (unhealthy endpoints). */
+  getOpenCircuits(): readonly string[] {
+    const open: string[] = [];
+    for (const [modelId, entry] of this.circuits) {
+      if (entry.state === 'open') {
+        open.push(modelId);
+      }
+    }
+    return open;
+  }
+}