pi-smart-router 1.3.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/.pi/extensions/smart-router/delegate-stream.ts +36 -4
  2. package/.pi/extensions/smart-router/route-and-delegate.ts +111 -17
  3. package/README.md +29 -17
  4. package/config/benchmark-profiles.json +76 -44
  5. package/dist/config/pi-model-mapper.d.ts.map +1 -1
  6. package/dist/config/pi-model-mapper.js +3 -0
  7. package/dist/config/pi-model-mapper.js.map +1 -1
  8. package/dist/domain/delegation/degenerate-output.d.ts +36 -0
  9. package/dist/domain/delegation/degenerate-output.d.ts.map +1 -0
  10. package/dist/domain/delegation/degenerate-output.js +75 -0
  11. package/dist/domain/delegation/degenerate-output.js.map +1 -0
  12. package/dist/domain/pipeline/local-zero-stage.d.ts +4 -0
  13. package/dist/domain/pipeline/local-zero-stage.d.ts.map +1 -1
  14. package/dist/domain/pipeline/local-zero-stage.js +23 -3
  15. package/dist/domain/pipeline/local-zero-stage.js.map +1 -1
  16. package/dist/domain/pipeline/low-intensity-stage.d.ts +3 -0
  17. package/dist/domain/pipeline/low-intensity-stage.d.ts.map +1 -1
  18. package/dist/domain/pipeline/low-intensity-stage.js +96 -14
  19. package/dist/domain/pipeline/low-intensity-stage.js.map +1 -1
  20. package/dist/domain/pipeline/router-pipeline.d.ts.map +1 -1
  21. package/dist/domain/pipeline/router-pipeline.js +39 -7
  22. package/dist/domain/pipeline/router-pipeline.js.map +1 -1
  23. package/dist/domain/pipeline/turn-envelope-stage.d.ts +1 -0
  24. package/dist/domain/pipeline/turn-envelope-stage.d.ts.map +1 -1
  25. package/dist/domain/pipeline/turn-envelope-stage.js +59 -2
  26. package/dist/domain/pipeline/turn-envelope-stage.js.map +1 -1
  27. package/dist/domain/routing/cross-provider-handoff.d.ts +39 -0
  28. package/dist/domain/routing/cross-provider-handoff.d.ts.map +1 -0
  29. package/dist/domain/routing/cross-provider-handoff.js +66 -0
  30. package/dist/domain/routing/cross-provider-handoff.js.map +1 -0
  31. package/dist/domain/routing/flash-class.d.ts +32 -0
  32. package/dist/domain/routing/flash-class.d.ts.map +1 -0
  33. package/dist/domain/routing/flash-class.js +58 -0
  34. package/dist/domain/routing/flash-class.js.map +1 -0
  35. package/dist/index.d.ts +1 -0
  36. package/dist/index.d.ts.map +1 -1
  37. package/dist/index.js +1 -0
  38. package/dist/index.js.map +1 -1
  39. package/dist/infrastructure/delegation/provider-error.d.ts.map +1 -1
  40. package/dist/infrastructure/delegation/provider-error.js +12 -4
  41. package/dist/infrastructure/delegation/provider-error.js.map +1 -1
  42. package/dist/infrastructure/gateway/gateway-dispatch.d.ts +31 -6
  43. package/dist/infrastructure/gateway/gateway-dispatch.d.ts.map +1 -1
  44. package/dist/infrastructure/gateway/gateway-dispatch.js +154 -13
  45. package/dist/infrastructure/gateway/gateway-dispatch.js.map +1 -1
  46. package/package.json +3 -3
  47. package/src/config/pi-model-mapper.ts +3 -0
  48. package/src/domain/delegation/degenerate-output.ts +124 -0
  49. package/src/domain/pipeline/local-zero-stage.ts +29 -3
  50. package/src/domain/pipeline/low-intensity-stage.ts +136 -19
  51. package/src/domain/pipeline/router-pipeline.ts +57 -7
  52. package/src/domain/pipeline/turn-envelope-stage.ts +81 -2
  53. package/src/domain/routing/cross-provider-handoff.ts +104 -0
  54. package/src/domain/routing/flash-class.ts +95 -0
  55. package/src/index.ts +11 -0
  56. package/src/infrastructure/delegation/provider-error.ts +13 -4
  57. package/src/infrastructure/gateway/gateway-dispatch.ts +193 -13
@@ -36,7 +36,12 @@ import {
36
36
  selectTierByExpectedCost,
37
37
  type ExpectedCostBreakdown,
38
38
  } from '../routing/expected-cost.js';
39
+ import {
40
+ applyMainLoopCapabilityFloor,
41
+ isFlashClassModel,
42
+ } from '../routing/flash-class.js';
39
43
  import type { Tier } from '../types/index.js';
44
+ import { DEFAULT_TYPED_JUDGMENT_CONFIG } from '../types/schemas.js';
40
45
  import { isPinOnlyFallbackActive } from './stage-helpers.js';
41
46
  import type { PipelineStage, RoutingContext } from './pipeline-stage.js';
42
47
  import type { StageResult } from './router-pipeline.js';
@@ -104,9 +109,114 @@ function resolveTierHint(
104
109
  return { tierHint: null, reasonCode: null };
105
110
  }
106
111
 
107
- interface ExpectedCostTierHintSelection {
112
+ interface TierHintSelection {
108
113
  tierHint: Tier | null;
109
114
  reasonCode: string | null;
115
+ }
116
+
117
+ const TIER_RANK: Readonly<Record<Tier, number>> = {
118
+ 'zero-tier': 0,
119
+ 'economical-cloud': 1,
120
+ 'frontier-cloud': 2,
121
+ };
122
+
123
+ /** Stable explain / LOG_ROUTING attribution for a judgment-driven tier hint. */
124
+ export function typedJudgmentTierReasonCode(tier: Tier): string {
125
+ return `typed_judgment_tier_${tier}`;
126
+ }
127
+
128
+ function isSessionDepthFloorActive(context: RoutingContext): boolean {
129
+ return (
130
+ applyMainLoopCapabilityFloor(context.request, context.fullFleet)
131
+ .excludedModelIds.length > 0
132
+ );
133
+ }
134
+
135
+ function isLoopEscalationFloorActive(context: RoutingContext): boolean {
136
+ return (
137
+ context.options.sessionPinner?.getPin(context.request.session_id)
138
+ ?.pin_reason === 'loop_escalation'
139
+ );
140
+ }
141
+
142
+ /**
143
+ * Compose capability_deserved with the structural/expected-cost hint.
144
+ * High-confidence judgments may replace the prior hint in either direction;
145
+ * below min_confidence they may only raise it. Deterministic floors always
146
+ * win over a judgment-driven downgrade.
147
+ */
148
+ function computeAdjustedHint(
149
+ context: RoutingContext,
150
+ structuralHint: TierHintSelection,
151
+ ): TierHintSelection {
152
+ const judgment = context.typedJudgment;
153
+ const capability = judgment?.capabilityDeserved;
154
+ if (!judgment || capability === null || capability === undefined) {
155
+ return structuralHint;
156
+ }
157
+
158
+ let candidate: Tier | null = null;
159
+ if (capability === 0 || capability === 1 / 3) {
160
+ candidate = capability === 0 ? 'zero-tier' : 'economical-cloud';
161
+ } else if (capability >= 2 / 3) {
162
+ candidate = 'frontier-cloud';
163
+ }
164
+ if (candidate === null) {
165
+ return structuralHint;
166
+ }
167
+
168
+ if (
169
+ (isSessionDepthFloorActive(context) ||
170
+ isLoopEscalationFloorActive(context)) &&
171
+ TIER_RANK[candidate] < TIER_RANK['frontier-cloud']
172
+ ) {
173
+ candidate = 'frontier-cloud';
174
+ }
175
+
176
+ // No tier change means no judgment-driven hint to attribute. Besides
177
+ // preserving observability, this keeps a non-deciding judgment byte-identical
178
+ // when it agrees with the deterministic / expected-cost selection.
179
+ if (structuralHint.tierHint === candidate) {
180
+ return structuralHint;
181
+ }
182
+
183
+ const confidence = judgment.confidences['capability_deserved'] ?? 0;
184
+ const minConfidence =
185
+ context.options.typedJudgmentConfig?.min_confidence ??
186
+ DEFAULT_TYPED_JUDGMENT_CONFIG.min_confidence;
187
+ if (confidence < minConfidence) {
188
+ const baseline = structuralHint.tierHint;
189
+ const raisesTier =
190
+ baseline === null
191
+ ? candidate === 'frontier-cloud'
192
+ : TIER_RANK[candidate] > TIER_RANK[baseline];
193
+ if (!raisesTier) {
194
+ return structuralHint;
195
+ }
196
+ }
197
+
198
+ return {
199
+ tierHint: candidate,
200
+ reasonCode: typedJudgmentTierReasonCode(candidate),
201
+ };
202
+ }
203
+
204
+ /** Minimal (level 0) is the only judgment allowed onto local/flash models. */
205
+ function applyTypedJudgmentModelFloor(context: RoutingContext): void {
206
+ const capability = context.typedJudgment?.capabilityDeserved;
207
+ if (capability === null || capability === undefined || capability === 0) {
208
+ return;
209
+ }
210
+
211
+ const filtered = context.fleet.filter(
212
+ (model) => model.tier !== 'zero-tier' && !isFlashClassModel(model),
213
+ );
214
+ if (filtered.some((model) => model.healthy !== false)) {
215
+ context.fleet = filtered;
216
+ }
217
+ }
218
+
219
+ interface ExpectedCostTierHintSelection extends TierHintSelection {
110
220
  tierCosts: readonly ExpectedCostBreakdown[];
111
221
  rationale: string;
112
222
  }
@@ -265,6 +375,8 @@ export function createLowIntensityStage(): PipelineStage {
265
375
  const alpha = config.p_success_alpha;
266
376
  context.pSuccessAlpha = alpha;
267
377
 
378
+ applyTypedJudgmentModelFloor(context);
379
+
268
380
  const cyclomaticThreshold = resolveCyclomaticThreshold(context);
269
381
  const triageResult = triageClassify(request.prompt_text, { cyclomaticThreshold });
270
382
  let clusterMatch: ClusterMatchResult | undefined;
@@ -304,24 +416,29 @@ export function createLowIntensityStage(): PipelineStage {
304
416
  );
305
417
  const weightsTrained =
306
418
  weights.trained_sample_count >= weights.min_training_samples;
307
- const adjustedHint = weightsTrained
308
- ? (() => {
309
- const selection = selectExpectedCostTierHint(
310
- context,
311
- pSuccessForGate,
312
- alpha,
313
- );
314
- logExpectedCostExplain(pSuccessForGate, alpha, selection, {
315
- p_success_raw: pResult.probability,
316
- p_success_calibrated: pSuccessForGate,
317
- calibration_applied: calibratedResult.calibration_applied,
318
- });
319
- return {
320
- tierHint: selection.tierHint,
321
- reasonCode: selection.reasonCode,
322
- };
323
- })()
324
- : structuralHint;
419
+ const expectedCostSelection = weightsTrained
420
+ ? selectExpectedCostTierHint(context, pSuccessForGate, alpha)
421
+ : null;
422
+ const adjustedHint = computeAdjustedHint(
423
+ context,
424
+ expectedCostSelection ?? structuralHint,
425
+ );
426
+ if (expectedCostSelection) {
427
+ logExpectedCostExplain(
428
+ pSuccessForGate,
429
+ alpha,
430
+ {
431
+ ...expectedCostSelection,
432
+ tierHint: adjustedHint.tierHint,
433
+ reasonCode: adjustedHint.reasonCode,
434
+ },
435
+ {
436
+ p_success_raw: pResult.probability,
437
+ p_success_calibrated: pSuccessForGate,
438
+ calibration_applied: calibratedResult.calibration_applied,
439
+ },
440
+ );
441
+ }
325
442
  context.tierHint = adjustedHint.tierHint;
326
443
  context.tierHintReasonCode = adjustedHint.reasonCode;
327
444
 
@@ -99,7 +99,11 @@ import {
99
99
  } from './typed-judgment-stage.js';
100
100
  import { createContextFitStage } from './context-fit-stage.js';
101
101
  import { createLowIntensityStage } from './low-intensity-stage.js';
102
- import { createLocalZeroStage } from './local-zero-stage.js';
102
+ import {
103
+ createLocalZeroStage,
104
+ TYPED_JUDGMENT_DESTRUCTIVE,
105
+ TYPED_JUDGMENT_TOOL_USE_SHORTFALL,
106
+ } from './local-zero-stage.js';
103
107
  import {
104
108
  createSafeDefaultStage,
105
109
  buildSafeDefaultFallbackDecision,
@@ -109,7 +113,14 @@ import {
109
113
  buildContextOverflowFallbackDecision,
110
114
  shouldAttemptContextOverflowFallback,
111
115
  } from './context-overflow-fallback-stage.js';
112
- import { redactPromptFromError } from './stage-helpers.js';
116
+ import {
117
+ isPinOnlyFallbackActive,
118
+ redactPromptFromError,
119
+ } from './stage-helpers.js';
120
+ import {
121
+ applyMainLoopCapabilityFloor,
122
+ SESSION_DEPTH_CAPABILITY_FLOOR,
123
+ } from '../routing/flash-class.js';
113
124
 
114
125
  // ─── Stage result ────────────────────────────────────────────────────────────
115
126
 
@@ -153,6 +164,26 @@ interface NamedPipelineStage {
153
164
  readonly run: StageRun;
154
165
  }
155
166
 
167
+ /** Privacy-safe rejected candidates recording the SP-323 floor in LOG_ROUTING. */
168
+ function capabilityFloorCandidates(
169
+ ctx: RoutingContext,
170
+ ): readonly CandidateScore[] {
171
+ // pin-only fallback deliberately skips turn_envelope, so do not claim its
172
+ // floor ran while attaching features to that emergency path.
173
+ if (isPinOnlyFallbackActive(ctx.options, ctx.request)) {
174
+ return [];
175
+ }
176
+
177
+ return applyMainLoopCapabilityFloor(ctx.request, ctx.fullFleet).excludedModelIds.map(
178
+ (modelId) => ({
179
+ model_id: modelId,
180
+ score: 0,
181
+ shortfall: 0,
182
+ rejected_reason: SESSION_DEPTH_CAPABILITY_FLOOR,
183
+ }),
184
+ );
185
+ }
186
+
156
187
  /** Inputs for local_zero eligibility beyond trivial-only triage (SP-111, #59).
157
188
  * Moved to ./stage-helpers.ts (SP-273); re-exported for import-path stability. */
158
189
  export {
@@ -544,11 +575,14 @@ export class RouterPipeline {
544
575
  return decision;
545
576
  }
546
577
 
547
- const capabilityGateActive = ctx.localZeroGateSkipReasons.some(
578
+ const explicitLocalGateActive = ctx.localZeroGateSkipReasons.some(
548
579
  (reason) =>
549
- reason === TOOL_USE_CAPABILITY_SHORTFALL || reason === LOCAL_ZERO_DISABLED,
580
+ reason === TOOL_USE_CAPABILITY_SHORTFALL ||
581
+ reason === LOCAL_ZERO_DISABLED ||
582
+ reason === TYPED_JUDGMENT_DESTRUCTIVE ||
583
+ reason === TYPED_JUDGMENT_TOOL_USE_SHORTFALL,
550
584
  );
551
- const inferredReasons = capabilityGateActive
585
+ const inferredReasons = explicitLocalGateActive
552
586
  ? tierSelection.local_zero_skip_reasons.filter(
553
587
  (reason) => reason !== 'hardware_or_local_unavailable',
554
588
  )
@@ -586,6 +620,7 @@ export class RouterPipeline {
586
620
  }
587
621
 
588
622
  private mergeFeatureCandidates(ctx: RoutingContext): readonly CandidateScore[] | null {
623
+ const floorCandidates = capabilityFloorCandidates(ctx);
589
624
  const hydraCandidates = ctx.hydraResult?.candidates ?? [];
590
625
  const expectedCostCandidates =
591
626
  ctx.expectedCostByTier?.map((entry) => ({
@@ -596,6 +631,7 @@ export class RouterPipeline {
596
631
  })) ?? [];
597
632
 
598
633
  if (
634
+ floorCandidates.length === 0 &&
599
635
  ctx.contextFitRejected.length === 0 &&
600
636
  hydraCandidates.length === 0 &&
601
637
  expectedCostCandidates.length === 0
@@ -603,6 +639,7 @@ export class RouterPipeline {
603
639
  return null;
604
640
  }
605
641
  return [
642
+ ...floorCandidates,
606
643
  ...ctx.contextFitRejected,
607
644
  ...expectedCostCandidates,
608
645
  ...hydraCandidates,
@@ -722,12 +759,25 @@ export class RouterPipeline {
722
759
 
723
760
  private async turnEnvelope(request: RoutingRequest): Promise<StageResult> {
724
761
  void request;
725
- return this.runStageWithContext(this.turnEnvelopePipelineStage);
762
+ const context = this.requireRouteContext();
763
+ // SP-326: turn_envelope consumes task_kind for its planning override.
764
+ // Materialize the fail-open signal immediately before that consumer while
765
+ // retaining the canonical registered stage order for telemetry contracts.
766
+ await this.typedJudgmentPipelineStage.run(context);
767
+ return this.turnEnvelopePipelineStage.run(context);
726
768
  }
727
769
 
728
770
  private async typedJudgment(request: RoutingRequest): Promise<StageResult> {
729
771
  void request;
730
- return this.runStageWithContext(this.typedJudgmentPipelineStage);
772
+ const context = this.requireRouteContext();
773
+ // turnEnvelope already ran the stage; avoid a duplicate judge call.
774
+ if (
775
+ context.typedJudgment !== null ||
776
+ context.typedJudgmentSkipReason !== null
777
+ ) {
778
+ return { decided: false, stage: 'typed_judgment' };
779
+ }
780
+ return this.typedJudgmentPipelineStage.run(context);
731
781
  }
732
782
 
733
783
  private async contextFitStage(request: RoutingRequest): Promise<StageResult> {
@@ -14,6 +14,7 @@ import type {
14
14
  ModelProfile,
15
15
  PlanningDelegateConfig,
16
16
  RoutingRequest,
17
+ TurnType,
17
18
  } from '../types/index.js';
18
19
  import { classifyTurnEnvelope } from '../triage/turn-envelope.js';
19
20
  import {
@@ -21,7 +22,10 @@ import {
21
22
  type ModelSwitchBreakevenContext,
22
23
  } from '../pinning/session-pinner.js';
23
24
  import { selectLowestCostModel } from '../pinning/sub-route-policy.js';
25
+ import { applyMainLoopCapabilityFloor } from '../routing/flash-class.js';
26
+ import { CrossProviderHandoffTracker } from '../routing/cross-provider-handoff.js';
24
27
  import { DEFAULT_OPERATOR_CONFIG } from '../../config/defaults.js';
28
+ import { DEFAULT_TYPED_JUDGMENT_CONFIG } from '../types/schemas.js';
25
29
  import {
26
30
  createPlanningDelegateObservability,
27
31
  PLANNING_DELEGATE,
@@ -168,12 +172,65 @@ function setPlanningDelegateDirectFallback(
168
172
  });
169
173
  }
170
174
 
175
+ const PLANNING_TASK_KINDS: ReadonlySet<string> = new Set([
176
+ 'plan',
177
+ 'debug',
178
+ 'review',
179
+ ]);
180
+
181
+ export const TYPED_JUDGMENT_PLANNING = 'typed_judgment_planning';
182
+
183
+ /**
184
+ * A confident task-kind judgment replaces only the regex planning signal.
185
+ * Explicit host turn types remain authoritative except for a positive
186
+ * planning override; low-confidence judgments leave classification untouched.
187
+ */
188
+ function resolveTurnType(
189
+ context: RoutingContext,
190
+ classifiedTurnType: TurnType,
191
+ ): TurnType {
192
+ const judgment = context.typedJudgment;
193
+ if (!judgment?.taskKind) {
194
+ return classifiedTurnType;
195
+ }
196
+
197
+ const minConfidence =
198
+ context.options.typedJudgmentConfig?.min_confidence ??
199
+ DEFAULT_TYPED_JUDGMENT_CONFIG.min_confidence;
200
+ if ((judgment.taskKindConfidence ?? 0) < minConfidence) {
201
+ return classifiedTurnType;
202
+ }
203
+
204
+ if (PLANNING_TASK_KINDS.has(judgment.taskKind)) {
205
+ return 'planning';
206
+ }
207
+ if (
208
+ context.request.turn_type === undefined &&
209
+ classifiedTurnType === 'planning'
210
+ ) {
211
+ return 'main_loop';
212
+ }
213
+ return classifiedTurnType;
214
+ }
215
+
171
216
  /** Step 2b: per-turn tier bias with pin-breakeven + planning-delegate gating. */
172
217
  export function createTurnEnvelopeStage(): PipelineStage {
218
+ const handoffTracker = new CrossProviderHandoffTracker();
219
+
173
220
  return {
174
221
  name: 'turn_envelope',
175
222
  async run(context: RoutingContext): Promise<StageResult> {
176
223
  const request: RoutingRequest = context.request;
224
+ const classifiedTurnType =
225
+ request.turn_type ?? classifyTurnEnvelope(request.messages);
226
+ const turnType = resolveTurnType(context, classifiedTurnType);
227
+ const handoff = handoffTracker.observe({
228
+ sessionId: request.session_id,
229
+ turnType,
230
+ pin: context.options.sessionPinner?.getPin(request.session_id) ?? null,
231
+ fleet: context.fleet,
232
+ });
233
+
177
234
  if (isPinOnlyFallbackActive(context.options, request)) {
178
235
  return { decided: false, stage: 'turn_envelope' };
179
236
  }
@@ -186,7 +243,26 @@ export function createTurnEnvelopeStage(): PipelineStage {
186
243
  return { decided: false, stage: 'turn_envelope' };
187
244
  }
188
245
 
189
- const turnType = request.turn_type ?? classifyTurnEnvelope(request.messages);
246
+ // SP-323 / #179: filter before any downstream pin, tier, or HyDRA
247
+ // selection. main_loop has no direct tier target, but the shared fleet
248
+ // narrowing still prevents a terse deep-session continuation from
249
+ // matching a flash-class model when a capable peer is available.
250
+ context.fleet = applyMainLoopCapabilityFloor(
251
+ request,
252
+ context.fleet,
253
+ handoff.shouldRecheck ? 'main_loop' : turnType,
254
+ ).fleet;
255
+
256
+ // SP-324 / #179: one foreign-history tool_result gets a full route rather
257
+ // than inheriting the handoff target through turn_envelope/session_pin.
258
+ // Breaking only this transitioned pin lets the normal later stages make
259
+ // and persist a fresh decision. The main_loop floor above keeps SP-323's
260
+ // deep-session flash exclusion active during that re-check.
261
+ if (handoff.shouldRecheck) {
262
+ context.options.sessionPinner?.breakPin(request.session_id);
263
+ return { decided: false, stage: 'turn_envelope' };
264
+ }
265
+
190
266
  const targetTier = TURN_TIER_MAP[turnType] ?? null;
191
267
 
192
268
  if (!targetTier) {
@@ -254,7 +330,10 @@ export function createTurnEnvelopeStage(): PipelineStage {
254
330
  }
255
331
  }
256
332
 
257
- const directReasonCode = `turn_${turnType}`;
333
+ const directReasonCode =
334
+ turnType === 'planning' && classifiedTurnType !== 'planning'
335
+ ? TYPED_JUDGMENT_PLANNING
336
+ : `turn_${turnType}`;
258
337
  let planningDirectFallback: string | null = null;
259
338
 
260
339
  if (
@@ -0,0 +1,104 @@
1
+ /**
2
+ * First-tool-result re-check after an observed cross-provider handoff
3
+ * (SP-324, #179).
4
+ *
5
+ * A handoff is detected from consecutive session-pin snapshots resolved
6
+ * against the fleet. The transition remains pending until the first
7
+ * tool_result, where it is consumed exactly once. Same-provider model changes
8
+ * and newly-created pins do not qualify.
9
+ *
10
+ * Detection exception: pi-ai assistant messages carry provider metadata, but
11
+ * the normalized RoutingRequest message contract intentionally omits it. An
12
+ * external Cursor → API handoff with no prior smart-router pin is therefore
13
+ * indistinguishable from a fresh session in the domain pipeline. Such a
14
+ * handoff needs a host-provided routing signal before it can be detected; this
15
+ * tracker never guesses and disables ordinary tool_result stickiness.
16
+ */
17
+
18
+ import type {
19
+ ModelProfile,
20
+ SessionPin,
21
+ TurnType,
22
+ } from '../types/index.js';
23
+
24
+ export interface CrossProviderHandoffObservation {
25
+ readonly sessionId: string;
26
+ readonly turnType: TurnType;
27
+ readonly pin: SessionPin | null;
28
+ readonly fleet: readonly ModelProfile[];
29
+ }
30
+
31
+ export interface CrossProviderHandoffResult {
32
+ /** True only for the first tool_result after an observed provider change. */
33
+ readonly shouldRecheck: boolean;
34
+ readonly previousProvider: string | null;
35
+ readonly currentProvider: string | null;
36
+ }
37
+
38
+ interface PinProviderSnapshot {
39
+ readonly provider: string;
40
+ readonly handoffPending: boolean;
41
+ }
42
+
43
+ function normalizeProvider(provider: string): string | null {
44
+ const normalized = provider.trim().toLowerCase();
45
+ return normalized.length > 0 ? normalized : null;
46
+ }
47
+
48
+ /**
49
+ * Stateful only across route calls; all session state remains in memory and is
50
+ * isolated by session id. RouterPipeline owns one tracker through its single
51
+ * turn-envelope stage, whose route calls are already serialized (SP-230).
52
+ */
53
+ export class CrossProviderHandoffTracker {
54
+ private readonly snapshots = new Map<string, PinProviderSnapshot>();
55
+
56
+ observe(
57
+ observation: CrossProviderHandoffObservation,
58
+ ): CrossProviderHandoffResult {
59
+ const { sessionId, turnType, pin, fleet } = observation;
60
+ const previous = this.snapshots.get(sessionId) ?? null;
61
+ const pinnedModel = pin
62
+ ? fleet.find(
63
+ (model) =>
64
+ model.id === pin.pinned_model_id && model.healthy !== false,
65
+ )
66
+ : undefined;
67
+ const currentProvider = pinnedModel
68
+ ? normalizeProvider(pinnedModel.provider)
69
+ : null;
70
+
71
+ if (!pin || !pinnedModel || !currentProvider) {
72
+ this.snapshots.delete(sessionId);
73
+ return {
74
+ shouldRecheck: false,
75
+ previousProvider: previous?.provider ?? null,
76
+ currentProvider: null,
77
+ };
78
+ }
79
+
80
+ // Loop escalation re-pins earlier in this same routing pass; that provider
81
+ // change is already a deliberate full-route escalation, not foreign replay.
82
+ const providerChanged =
83
+ pin.pin_reason !== 'loop_escalation' &&
84
+ previous !== null &&
85
+ previous.provider !== currentProvider;
86
+ const handoffPending =
87
+ providerChanged || (previous?.handoffPending ?? false);
88
+ const shouldRecheck = turnType === 'tool_result' && handoffPending;
89
+
90
+ this.snapshots.set(sessionId, {
91
+ provider: currentProvider,
92
+ // A non-tool turn preserves a pending transition until the first tool
93
+ // result. That first tool result consumes it even when routing later
94
+ // fails open, preventing repeated pin breaks on every tool turn.
95
+ handoffPending: turnType === 'tool_result' ? false : handoffPending,
96
+ });
97
+
98
+ return {
99
+ shouldRecheck,
100
+ previousProvider: previous?.provider ?? null,
101
+ currentProvider,
102
+ };
103
+ }
104
+ }
@@ -0,0 +1,95 @@
1
+ /**
2
+ * Deterministic flash-class capability floor for deep agentic main_loop turns.
3
+ *
4
+ * Shared with typed-judgment consumers (#188): judgment may raise capability
5
+ * requirements, but must never lower them below this deterministic floor.
6
+ */
7
+
8
+ import type {
9
+ ModelProfile,
10
+ RoutingRequest,
11
+ TurnType,
12
+ } from '../types/index.js';
13
+ import { classifyTurnEnvelope } from '../triage/turn-envelope.js';
14
+
15
+ export const DEEP_SESSION_MESSAGE_COUNT_THRESHOLD = 1_000;
16
+ export const DEEP_SESSION_ESTIMATED_TOKEN_THRESHOLD = 100_000;
17
+ export const FLASH_CLASS_CAPABILITY_FLOOR = 0.7;
18
+ export const SESSION_DEPTH_CAPABILITY_FLOOR = 'session_depth_capability_floor';
19
+
20
+ const FLASH_CLASS_ID_PATTERN =
21
+ /(?:^|[^a-z0-9])(?:flash|lite|mini|nano)(?=$|[^a-z0-9])/i;
22
+
23
+ export interface MainLoopCapabilityFloorResult {
24
+ /** Filtered candidates, or the original array reference when no floor applies. */
25
+ readonly fleet: readonly ModelProfile[];
26
+ /** Healthy flash-class candidates excluded by the floor, in fleet order. */
27
+ readonly excludedModelIds: readonly string[];
28
+ }
29
+
30
+ /**
31
+ * Capability thresholds are primary; the id pattern conservatively catches
32
+ * named flash variants whose catalog capabilities have not been calibrated.
33
+ */
34
+ export function isFlashClassModel(
35
+ model: Pick<ModelProfile, 'id' | 'capabilities'>,
36
+ ): boolean {
37
+ return (
38
+ model.capabilities.reasoning < FLASH_CLASS_CAPABILITY_FLOOR ||
39
+ model.capabilities.tool_use < FLASH_CLASS_CAPABILITY_FLOOR ||
40
+ FLASH_CLASS_ID_PATTERN.test(model.id)
41
+ );
42
+ }
43
+
44
+ /** Strict issue-#179 boundaries: more than 1,000 messages OR 100k tokens. */
45
+ export function isDeepAgenticSession(
46
+ request: Pick<RoutingRequest, 'messages' | 'estimated_input_tokens'>,
47
+ ): boolean {
48
+ return (
49
+ (request.messages?.length ?? 0) > DEEP_SESSION_MESSAGE_COUNT_THRESHOLD ||
50
+ (request.estimated_input_tokens ?? 0) >
51
+ DEEP_SESSION_ESTIMATED_TOKEN_THRESHOLD
52
+ );
53
+ }
54
+
55
+ /**
56
+ * Exclude flash-class candidates for deep main_loop turns when a healthy
57
+ * higher-capability peer exists. With no such peer, retain the original fleet
58
+ * rather than leaving the host without a usable route. Explicit model forces
59
+ * and non-main_loop turns are unchanged.
60
+ */
61
+ export function applyMainLoopCapabilityFloor(
62
+ request: RoutingRequest,
63
+ fleet: readonly ModelProfile[],
64
+ turnType: TurnType = request.turn_type ?? classifyTurnEnvelope(request.messages),
65
+ ): MainLoopCapabilityFloorResult {
66
+ const unchanged = { fleet, excludedModelIds: [] } as const;
67
+ if (
68
+ request.force_model_id ||
69
+ turnType !== 'main_loop' ||
70
+ !isDeepAgenticSession(request)
71
+ ) {
72
+ return unchanged;
73
+ }
74
+
75
+ const hasHigherCapabilityPeer = fleet.some(
76
+ (model) => model.healthy !== false && !isFlashClassModel(model),
77
+ );
78
+ if (!hasHigherCapabilityPeer) {
79
+ return unchanged;
80
+ }
81
+
82
+ const filteredFleet = fleet.filter((model) => !isFlashClassModel(model));
83
+ if (filteredFleet.length === fleet.length) {
84
+ return unchanged;
85
+ }
86
+
87
+ return {
88
+ fleet: filteredFleet,
89
+ // Unhealthy entries were already ineligible; do not attribute their
90
+ // rejection to this floor in routing explain / LOG_ROUTING metadata.
91
+ excludedModelIds: fleet
92
+ .filter((model) => model.healthy !== false && isFlashClassModel(model))
93
+ .map((model) => model.id),
94
+ };
95
+ }
package/src/index.ts CHANGED
@@ -215,6 +215,17 @@ export {
215
215
  computeOutputHeadroom,
216
216
  type OutputHeadroomConfig,
217
217
  } from './domain/delegation/output-headroom.js';
218
+ export {
219
+ DEGENERATE_OUTPUT,
220
+ DEGENERATE_OUTPUT_ERROR_CODE,
221
+ DEFAULT_DEGENERATE_OUTPUT_CONFIG,
222
+ classifyDegenerateOutput,
223
+ isDegenerateOutput,
224
+ repeatedNgramRatio,
225
+ type DegenerateOutputClassification,
226
+ type DegenerateOutputConfig,
227
+ type DegenerateOutputMessage,
228
+ } from './domain/delegation/degenerate-output.js';
218
229
 
219
230
  // Domain — matching, pinning, pipeline, pricing, routing
220
231
  export {
@@ -39,8 +39,13 @@ function parseNumericCode(value: unknown): number | undefined {
39
39
  */
40
40
  export function parseProviderError(errorMessage: string): ParsedProviderError | undefined {
41
41
  const trimmed = errorMessage.trim();
42
- if (!trimmed.startsWith('{')) {
43
- const statusMatch = trimmed.match(/\b(429|5\d{2})\b/);
42
+ const statusPrefixMatch = trimmed.match(/^(\d{3}):\s*/);
43
+ const jsonText = statusPrefixMatch
44
+ ? trimmed.slice(statusPrefixMatch[0].length)
45
+ : trimmed;
46
+
47
+ if (!jsonText.startsWith('{')) {
48
+ const statusMatch = trimmed.match(/^(429|5\d{2})\b/);
44
49
  if (statusMatch) {
45
50
  return { statusCode: Number.parseInt(statusMatch[1]!, 10) };
46
51
  }
@@ -48,7 +53,7 @@ export function parseProviderError(errorMessage: string): ParsedProviderError |
48
53
  }
49
54
 
50
55
  try {
51
- const parsed = JSON.parse(trimmed) as {
56
+ const parsed = JSON.parse(jsonText) as {
52
57
  error?: { code?: unknown; status?: unknown; message?: unknown };
53
58
  code?: unknown;
54
59
  status?: unknown;
@@ -56,11 +61,15 @@ export function parseProviderError(errorMessage: string): ParsedProviderError |
56
61
  };
57
62
 
58
63
  const nested = parsed.error;
64
+ const prefixStatusCode = statusPrefixMatch
65
+ ? Number.parseInt(statusPrefixMatch[1]!, 10)
66
+ : undefined;
59
67
  const statusCode =
60
68
  parseNumericCode(nested?.code) ??
61
69
  parseNumericCode(nested?.status) ??
62
70
  parseNumericCode(parsed.code) ??
63
- parseNumericCode(parsed.status);
71
+ parseNumericCode(parsed.status) ??
72
+ prefixStatusCode;
64
73
 
65
74
  const code =
66
75
  typeof nested?.status === 'string'