pi-smart-router 0.1.0

package/specs/001-build-smart-router/contracts/telemetry-contrib.schema.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://pi-smart-router.dev/contracts/telemetry-contrib.schema.json",
+  "title": "TelemetryContribRecord",
+  "description": "Privacy-safe community telemetry contribution row (GitHub #67). Scalar routing features and outcome labels only — never prompt text, messages, request_id, or install-local pepper fields.",
+  "type": "object",
+  "required": [
+    "version",
+    "timestamp",
+    "session_id_hash",
+    "turn_type",
+    "reason_code",
+    "selected_model_id",
+    "routing_latency_ms"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Contrib record format version."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 routing decision timestamp."
+    },
+    "session_id_hash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "One-way SHA-256 hash of install-local session_id for correlation without export."
+    },
+    "turn_type": {
+      "type": "string",
+      "minLength": 1
+    },
+    "stage": {
+      "type": "string",
+      "minLength": 1
+    },
+    "reason_code": {
+      "type": "string",
+      "minLength": 1
+    },
+    "selected_model_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "tier": {
+      "type": "string",
+      "enum": ["zero-tier", "economical-cloud", "frontier-cloud"]
+    },
+    "routing_latency_ms": {
+      "type": "number",
+      "minimum": 0
+    },
+    "estimated_cost_usd": {
+      "type": ["number", "null"],
+      "minimum": 0
+    },
+    "estimated_input_tokens": {
+      "type": ["integer", "null"],
+      "minimum": 0
+    },
+    "has_tool_context": {
+      "type": "boolean"
+    },
+    "compaction_flag": {
+      "type": "boolean"
+    },
+    "triage_verdict": {
+      "type": ["string", "null"]
+    },
+    "triage_reason_code": {
+      "type": ["string", "null"]
+    },
+    "triage_cyclomatic_score": {
+      "type": ["number", "null"],
+      "minimum": 0
+    },
+    "triage_trivial_hits": {
+      "type": ["integer", "null"],
+      "minimum": 0
+    },
+    "triage_complex_hits": {
+      "type": ["integer", "null"],
+      "minimum": 0
+    },
+    "triage_sanitized_length_delta": {
+      "type": ["integer", "null"]
+    },
+    "requirement_reasoning": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "maximum": 1
+    },
+    "requirement_code_gen": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "maximum": 1
+    },
+    "requirement_tool_use": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "maximum": 1
+    },
+    "cluster_id": {
+      "type": ["string", "null"]
+    },
+    "cluster_similarity": {
+      "type": ["number", "null"]
+    },
+    "cluster_margin": {
+      "type": ["number", "null"]
+    },
+    "low_intensity_score": {
+      "type": ["number", "null"]
+    },
+    "tier_hint": {
+      "type": ["string", "null"],
+      "enum": ["zero-tier", "economical-cloud", "frontier-cloud", null]
+    },
+    "p_success_cheap": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "maximum": 1
+    },
+    "local_eligible_reason": {
+      "type": ["string", "null"]
+    },
+    "tier_selection_reason_code": {
+      "type": ["string", "null"]
+    },
+    "success_label": {
+      "type": ["boolean", "null"],
+      "description": "Derived outcome label when behavioral signals exist."
+    },
+    "outcome_signals": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "model_override",
+          "compaction_pin_break",
+          "feedback_good",
+          "feedback_bad"
+        ]
+      }
+    }
+  }
+}

package/src/api/explain/router-explain.ts

@@ -0,0 +1,146 @@
+/**
+ * Explain endpoint handler — T041.
+ *
+ * Returns routing rationale (tier, stage, reason_code, candidates) without
+ * dispatching upstream inference. Runs the same pipeline as the live path
+ * to guarantee bit-for-bit decision equivalence.
+ *
+ * Contract: specs/001-build-smart-router/contracts/explain-endpoint.md v1.0.0
+ *
+ * Invariants:
+ *   - MUST NOT call upstream LLM providers
+ *   - MUST produce a decision identical to the live pipeline for the same input
+ *   - MUST emit no RoutingTelemetry with upstream cost (routing_latency_ms only)
+ */
+
+import type { ModelProfile, RoutingDecision, RoutingRequest, Message } from '../../domain/types/index.js';
+import { RoutingRequestSchema } from '../../domain/types/schemas.js';
+import { RouterPipeline } from '../../domain/pipeline/router-pipeline.js';
+import { safeCloudDefault } from '../../domain/pipeline/safe-default.js';
+import type { ClusterMatcher } from '../../domain/matching/cluster-matcher.js';
+import { enrichRoutingDecisionForExplain } from '../../infrastructure/telemetry/routing-telemetry.js';
+
+// ─── Result types ─────────────────────────────────────────────────────────────
+
+export interface ExplainValidationError {
+  readonly error: 'validation_failed';
+  readonly details: readonly string[];
+}
+
+export interface ExplainSuccess {
+  readonly status: 200;
+  readonly body: RoutingDecision;
+}
+
+export interface ExplainBadRequest {
+  readonly status: 400;
+  readonly body: ExplainValidationError;
+}
+
+export interface ExplainUnavailable {
+  readonly status: 503;
+  readonly body: RoutingDecision;
+}
+
+export type ExplainResult = ExplainSuccess | ExplainBadRequest | ExplainUnavailable;
+
+// ─── Handler dependencies ─────────────────────────────────────────────────────
+
+export interface ExplainHandlerDeps {
+  readonly fleet: readonly ModelProfile[];
+  readonly pipeline: RouterPipeline;
+  readonly clusterMatcher?: ClusterMatcher;
+}
+
+// ─── Handler factory ──────────────────────────────────────────────────────────
+
+/**
+ * Create an explain handler bound to a shared pipeline instance.
+ *
+ * Reuses the same RouterPipeline as the live dispatch path so
+ * session pin state and stage ordering are identical.
+ */
+export function createExplainHandler(deps: ExplainHandlerDeps) {
+  const { fleet, pipeline, clusterMatcher } = deps;
+
+  return async function explain(rawBody: unknown): Promise<ExplainResult> {
+    const parsed = RoutingRequestSchema.safeParse(rawBody);
+
+    if (!parsed.success) {
+      return {
+        status: 400,
+        body: {
+          error: 'validation_failed',
+          details: parsed.error.issues.map(
+            (issue) => `${issue.path.join('.')}: ${issue.message}`,
+          ),
+        },
+      };
+    }
+
+    const request = toRoutingRequest(parsed.data);
+    const start = performance.now();
+
+    try {
+      const decision = await pipeline.route(request);
+      return {
+        status: 200,
+        body: await enrichRoutingDecisionForExplain(request, decision, {
+          fleet,
+          ...(clusterMatcher !== undefined ? { clusterMatcher } : {}),
+        }),
+      };
+    } catch {
+      const fallbackModel = safeCloudDefault(fleet);
+      const decision: RoutingDecision = {
+        request_id: request.request_id,
+        selected_model_id: fallbackModel?.id ?? 'unknown',
+        tier: fallbackModel?.tier ?? 'economical-cloud',
+        stage: 'fallback',
+        reason_code: 'safe_default',
+        routing_latency_ms: performance.now() - start,
+        pin_reason: null,
+      };
+      return {
+        status: 503,
+        body: await enrichRoutingDecisionForExplain(request, decision, {
+          fleet,
+          ...(clusterMatcher !== undefined ? { clusterMatcher } : {}),
+        }),
+      };
+    }
+  };
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+type ParsedRequest = ReturnType<typeof RoutingRequestSchema.parse>;
+
+/**
+ * Map Zod-validated data to the domain RoutingRequest entity, bridging
+ * schema field names (tool_call_id/tool_calls) to entity shape (tool_blocks)
+ * and satisfying exactOptionalPropertyTypes constraints.
+ */
+function toRoutingRequest(data: ParsedRequest): RoutingRequest {
+  // Build with known required fields, then add optional fields only when present
+  // to satisfy exactOptionalPropertyTypes (no explicit undefined values).
+  const result: { request_id: string; session_id: string; prompt_text: string; [k: string]: unknown } = {
+    request_id: data.request_id,
+    session_id: data.session_id,
+    prompt_text: data.prompt_text,
+  };
+
+  if (data.messages !== undefined) {
+    result['messages'] = data.messages.map((m): Message => ({
+      role: m.role,
+      content: m.content,
+      ...(m.tool_calls !== undefined ? { tool_blocks: m.tool_calls } : {}),
+    }));
+  }
+  if (data.turn_type !== undefined) result['turn_type'] = data.turn_type;
+  if (data.compaction_flag !== undefined) result['compaction_flag'] = data.compaction_flag;
+  if (data.force_model_id !== undefined) result['force_model_id'] = data.force_model_id;
+  if (data.estimated_input_tokens !== undefined) result['estimated_input_tokens'] = data.estimated_input_tokens;
+
+  return result as RoutingRequest;
+}

package/src/api/middleware/pi-router-middleware.ts

@@ -0,0 +1,169 @@
+/**
+ * Pi lifecycle hook integration — T021, T021b, SP-055.
+ *
+ * Registers compaction and model-override hooks on pi extension events.
+ * Lifecycle flags are consumed when building the next routing request
+ * (extension `buildRoutingRequest` or embedder `dispatch.dispatch`).
+ *
+ * Routing and stream delegation live in `.pi/extensions/smart-router/` for
+ * pi users, or in embedder code that calls `GatewayDispatch.dispatch()`.
+ * This module does not register routing or no-op context hooks.
+ *
+ * Contract: specs/001-build-smart-router/contracts/pi-middleware.md v1.0.0
+ */
+
+// ─── Pi extension event types (structural typing) ────────────────────────────
+
+export interface PiSessionManager {
+  getSessionFile(): string | undefined;
+  getSessionId(): string;
+}
+
+export interface PiExtensionContext {
+  readonly cwd: string;
+  readonly sessionManager: PiSessionManager;
+}
+
+export interface PiMessage {
+  readonly role: string;
+  readonly content: string;
+  readonly tool_call_id?: string;
+  readonly tool_calls?: readonly unknown[];
+}
+
+export interface PiContextEvent {
+  readonly messages: readonly PiMessage[];
+}
+
+export interface PiModelSelectEvent {
+  readonly source: string;
+  readonly model: {
+    readonly provider: string;
+    readonly id: string;
+  };
+}
+
+/** Legacy embedder event shape; routing is handled in the pi extension stream path. */
+export interface PiProviderRequestEvent {
+  readonly provider: string;
+  readonly model: string;
+  readonly messages?: readonly PiMessage[];
+  [key: string]: unknown;
+}
+
+export interface PiExtensionHooks {
+  on(event: 'before_provider_request', handler: (event: PiProviderRequestEvent, ctx: PiExtensionContext) => PiProviderRequestEvent | Promise<PiProviderRequestEvent>): void;
+  on(event: 'context', handler: (event: PiContextEvent, ctx: PiExtensionContext) => void): void;
+  on(event: 'session_compact', handler: (event: unknown, ctx: PiExtensionContext) => void): void;
+  on(event: 'session_before_compact', handler: (event: unknown, ctx: PiExtensionContext) => void): void;
+  on(event: 'model_select', handler: (event: PiModelSelectEvent, ctx: PiExtensionContext) => void): void;
+}
+
+// ─── Lifecycle hook state (FR-008) ───────────────────────────────────────────
+
+export interface LifecycleFlags {
+  readonly compaction_flag?: boolean;
+  readonly force_model_id?: string;
+}
+
+interface SessionLifecycleState {
+  compactionPending: boolean;
+  forceModelId?: string;
+}
+
+/**
+ * Per-session lifecycle flags set by pi compaction and model_select hooks.
+ * Shared across router rebuilds so hook state survives fleet refresh.
+ */
+export class LifecycleHookState {
+  private readonly sessions = new Map<string, SessionLifecycleState>();
+
+  private getOrCreate(sessionId: string): SessionLifecycleState {
+    let state = this.sessions.get(sessionId);
+    if (!state) {
+      state = { compactionPending: false };
+      this.sessions.set(sessionId, state);
+    }
+    return state;
+  }
+
+  markCompaction(sessionId: string): void {
+    this.getOrCreate(sessionId).compactionPending = true;
+  }
+
+  setForceModel(sessionId: string, modelId: string): void {
+    const state = this.getOrCreate(sessionId);
+    state.forceModelId = modelId;
+  }
+
+  /**
+   * Consume lifecycle flags for the next routing request.
+   * Compaction is one-shot; force_model_id is one-shot per consume.
+   */
+  consume(sessionId: string): LifecycleFlags {
+    const state = this.sessions.get(sessionId);
+    if (!state) {
+      return {};
+    }
+
+    const flags: LifecycleFlags = {
+      ...(state.compactionPending ? { compaction_flag: true } : {}),
+      ...(state.forceModelId !== undefined ? { force_model_id: state.forceModelId } : {}),
+    };
+
+    state.compactionPending = false;
+    delete state.forceModelId;
+
+    if (!state.compactionPending && state.forceModelId === undefined) {
+      this.sessions.delete(sessionId);
+    }
+
+    return flags;
+  }
+}
+
+function resolveHookSessionId(ctx: PiExtensionContext): string {
+  return ctx.sessionManager.getSessionId();
+}
+
+// ─── Lifecycle hook registrar ────────────────────────────────────────────────
+
+export interface PiRouterMiddlewareOptions {
+  readonly lifecycleHookState?: LifecycleHookState;
+}
+
+export interface PiRouterMiddleware {
+  readonly register: (hooks: PiExtensionHooks) => void;
+  readonly lifecycleHookState: LifecycleHookState;
+}
+
+/**
+ * Create pi lifecycle hook handlers for session compaction and model overrides.
+ *
+ * Library embedders: call `router.register(hooks)` on the returned `RouterHandle`
+ * and route via `router.dispatch.dispatch()`. For pi, use the project extension at
+ * `.pi/extensions/smart-router/` — it owns stream delegation and routing telemetry.
+ */
+export function createPiRouterMiddleware(
+  options?: PiRouterMiddlewareOptions,
+): PiRouterMiddleware {
+  const lifecycleHookState = options?.lifecycleHookState ?? new LifecycleHookState();
+
+  function register(hooks: PiExtensionHooks): void {
+    hooks.on('session_compact', (_event: unknown, ctx: PiExtensionContext) => {
+      lifecycleHookState.markCompaction(resolveHookSessionId(ctx));
+    });
+
+    hooks.on('session_before_compact', (_event: unknown, ctx: PiExtensionContext) => {
+      lifecycleHookState.markCompaction(resolveHookSessionId(ctx));
+    });
+
+    hooks.on('model_select', (event: PiModelSelectEvent, ctx: PiExtensionContext) => {
+      if (event.source === 'set') {
+        lifecycleHookState.setForceModel(resolveHookSessionId(ctx), event.model.id);
+      }
+    });
+  }
+
+  return { register, lifecycleHookState };
+}