dsh-lcx-codex 0.6.0 → 0.7.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.
package/lib/route.js CHANGED
@@ -2,9 +2,9 @@ import { createHash, randomUUID } from "node:crypto";
2
2
  import { credentialRef } from "@deepseek-ai/dsh-credentials";
3
3
  import { SessionId } from "@deepseek-ai/dsh-session";
4
4
  import "@deepseek-ai/dsh-settings";
5
- import { assertUsableApiKey, attributionHeaders, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
5
+ import { assertUsableApiKey, attributionHeaders, LlmError, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
6
6
  import { resolveCatalogModel } from "./model-catalog.js";
7
- import { clampOpenAIPromptCacheKey } from "./pi-responses-runtime.js";
7
+ import { clampOpenAIPromptCacheKey, getCatalogModels } from "./pi-responses-runtime.js";
8
8
  import { providerSessionHeaders } from "./provider-headers.js";
9
9
  import { codedError, isPositiveFinite, isPositiveSafeInteger, isRecord } from "./util.js";
10
10
  import { DEFAULTS } from "./defaults.js";
@@ -14,6 +14,53 @@ export function normalizeBaseURL(value) {
14
14
  export function baseURLFingerprint(baseURL) {
15
15
  return createHash("sha256").update(normalizeBaseURL(baseURL), "utf8").digest("hex");
16
16
  }
17
+ function findHeaderCaseInsensitive(headers, target) {
18
+ const normalized = target.toLowerCase();
19
+ for (const [name, value] of Object.entries(headers ?? {})) {
20
+ if (name.toLowerCase() === normalized)
21
+ return String(value);
22
+ }
23
+ return undefined;
24
+ }
25
+ function effectiveCredentialIdentity(effectiveAuthorization) {
26
+ if (typeof effectiveAuthorization === "string" && /^Bearer\s+eyJ/iu.test(effectiveAuthorization.trim())) {
27
+ const token = effectiveAuthorization.trim().replace(/^Bearer\s+/iu, "");
28
+ const parts = token.split(".");
29
+ if (parts.length === 3 && parts[1]) {
30
+ try {
31
+ const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
32
+ const authClaim = isRecord(payload) ? payload["https://api.openai.com/auth"] : undefined;
33
+ const accountId = isRecord(authClaim) ? authClaim.chatgpt_account_id : undefined;
34
+ if (typeof accountId === "string" && accountId.trim().length > 0) {
35
+ return `chatgpt-acct:${accountId.trim()}`;
36
+ }
37
+ }
38
+ catch { }
39
+ }
40
+ }
41
+ return `auth:${effectiveAuthorization ?? ""}`;
42
+ }
43
+ function canonicalAuthorityHeaders(headers, excludeAuth = false) {
44
+ return Object.entries(headers ?? {})
45
+ .filter(([name]) => !excludeAuth || name.toLowerCase() !== "authorization")
46
+ .map(([name, value]) => [name.toLowerCase(), String(value)])
47
+ .sort(([left], [right]) => left.localeCompare(right));
48
+ }
49
+ export function requestHeaderAuthorityFingerprint(headers, credentialAuthority) {
50
+ const effectiveAuth = credentialAuthority?.effectiveAuthorization ??
51
+ findHeaderCaseInsensitive(headers, "authorization");
52
+ const authDigest = createHash("sha256")
53
+ .update(effectiveCredentialIdentity(effectiveAuth), "utf8")
54
+ .digest("hex");
55
+ return createHash("sha256")
56
+ .update(JSON.stringify({
57
+ v: 2,
58
+ apiKeyEnv: String(credentialAuthority?.apiKeyEnv ?? ""),
59
+ authDigest,
60
+ headers: canonicalAuthorityHeaders(headers, true),
61
+ }), "utf8")
62
+ .digest("hex");
63
+ }
17
64
  export function routeFingerprint(route, options = {}) {
18
65
  const includeSession = options.includeSession !== false;
19
66
  return createHash("sha256").update([
@@ -27,7 +74,7 @@ export function promptCacheSessionId(route, config = {}, ctx = undefined) {
27
74
  if (!sessionId)
28
75
  return undefined;
29
76
  const sessions = ctx?.sessions;
30
- let current = sessions?.get(SessionId(sessionId));
77
+ let current = typeof sessions?.get === "function" ? sessions.get(SessionId(sessionId)) : undefined;
31
78
  if (current?.header?.origin !== "subagent")
32
79
  return sessionId;
33
80
  const seen = new Set([sessionId]);
@@ -35,7 +82,7 @@ export function promptCacheSessionId(route, config = {}, ctx = undefined) {
35
82
  const parentId = current.header.parentSession;
36
83
  if (seen.has(parentId))
37
84
  return sessionId;
38
- const parent = sessions?.get(SessionId(parentId));
85
+ const parent = typeof sessions?.get === "function" ? sessions.get(SessionId(parentId)) : undefined;
39
86
  if (!parent)
40
87
  return sessionId;
41
88
  seen.add(parentId);
@@ -44,6 +91,8 @@ export function promptCacheSessionId(route, config = {}, ctx = undefined) {
44
91
  return current?.id ?? sessionId;
45
92
  }
46
93
  export function promptCacheKey(route, config = {}, ctx = undefined) {
94
+ if (config.responsesCompat?.promptCacheKeyMode === "disabled")
95
+ return undefined;
47
96
  return clampOpenAIPromptCacheKey(promptCacheSessionId(route, config, ctx));
48
97
  }
49
98
  /** Grok follows Pi directly: cache/affinity belongs to the selected child session. */
@@ -87,16 +136,29 @@ function configuredProviderProfile(ctx, provider) {
87
136
  return undefined;
88
137
  }
89
138
  }
90
- const RESPONSES_COMPAT_FIELDS = new Set(["supportsDeveloperRole", "sessionAffinityFormat", "supportsStrictMode", "supportsLongCacheRetention", "supportsOpenAIGrammarTools", "supportsAdditionalTools", "supportsToolSearch", "supportsExplicitPromptCacheMode", "supportsMaxOutputTokens"]);
91
- function copyResponsesCompat(target, source) {
139
+ const RESPONSES_COMPAT_FIELDS = new Set(["supportsDeveloperRole", "sessionAffinityFormat", "promptCacheKeyMode", "supportsStrictMode", "supportsLongCacheRetention", "supportsOpenAIGrammarTools", "supportsAdditionalTools", "supportsToolSearch", "supportsExplicitPromptCacheMode", "supportsMaxOutputTokens"]);
140
+ const RESPONSES_PROFILE_COMPAT_FIELDS = new Set(["supportsDeveloperRole", "supportsMaxOutputTokens", "supportsStrictMode", "supportsLongCacheRetention"]);
141
+ /** True when `model` names a Grok model (`grok-*`, `x-ai/grok-*`, or camelCase `grokCustom`/`GrOkCustomPreview`), rejecting non-Grok substrings like `vendor/grokking`. */
142
+ export function isGrokModelId(model) {
143
+ const trimmed = String(model ?? "").trim();
144
+ const terminal = trimmed.slice(trimmed.lastIndexOf("/") + 1);
145
+ return (/^grok(?:$|[-._0-9])/iu.test(terminal) ||
146
+ /^grok[A-Z]/u.test(terminal) ||
147
+ /^[gG][rR][oO][kK][A-Z][a-z]/u.test(terminal));
148
+ }
149
+ function copyResponsesCompat(target, source, allowedFields = RESPONSES_COMPAT_FIELDS) {
92
150
  if (!isRecord(source))
93
151
  return;
94
- for (const field of RESPONSES_COMPAT_FIELDS) {
152
+ for (const field of allowedFields) {
95
153
  const value = source[field];
96
154
  if (field === "sessionAffinityFormat") {
97
155
  if (value === "openai" || value === "openai-nosession" || value === "openrouter")
98
156
  target.sessionAffinityFormat = value;
99
157
  }
158
+ else if (field === "promptCacheKeyMode") {
159
+ if (value === "auto" || value === "disabled" || value === "enabled")
160
+ target.promptCacheKeyMode = value;
161
+ }
100
162
  else if (typeof value === "boolean")
101
163
  Object.assign(target, { [field]: value });
102
164
  }
@@ -179,7 +241,7 @@ export async function warmHostRecognizedModels(ctx) {
179
241
  continue;
180
242
  }
181
243
  for (const model of models) {
182
- if (!/^(?:gpt-|grok)/iu.test(model.id))
244
+ if (!/^gpt-/iu.test(model.id) && !isGrokModelId(model.id))
183
245
  continue;
184
246
  if (resolveCatalogModel(entry.provider, model.id).source === "catalog-model")
185
247
  continue;
@@ -238,8 +300,8 @@ function configuredModelProfile(profile, modelId) {
238
300
  }
239
301
  function configuredResponsesCompat(profile, modelId) {
240
302
  const compat = {};
241
- copyResponsesCompat(compat, profile?.compat);
242
- copyResponsesCompat(compat, configuredModelProfile(profile, modelId)?.compat);
303
+ copyResponsesCompat(compat, profile?.compat, RESPONSES_PROFILE_COMPAT_FIELDS);
304
+ copyResponsesCompat(compat, configuredModelProfile(profile, modelId)?.compat, RESPONSES_PROFILE_COMPAT_FIELDS);
243
305
  return Object.keys(compat).length ? compat : undefined;
244
306
  }
245
307
  const MODEL_THINKING_LEVELS = [
@@ -328,6 +390,9 @@ export function resolveResponsesRouteConfig(ctx, options, policy, assumeHostServ
328
390
  copyResponsesCompat(responsesCompat, builtin?.compat);
329
391
  copyResponsesCompat(responsesCompat, lcxCapabilityRoute ? policy.responsesCompat : undefined);
330
392
  copyResponsesCompat(responsesCompat, configuredResponsesCompat(configured, model));
393
+ if (policy.promptCacheKeyMode === "disabled" || policy.promptCacheKeyMode === "enabled") {
394
+ responsesCompat.promptCacheKeyMode = policy.promptCacheKeyMode;
395
+ }
331
396
  const promptCacheModel = lcxCapabilityRoute && policy.supportsExplicitPromptCacheMode === true ? resolveCatalogModel("openai", model).descriptor : undefined;
332
397
  const promptCacheRaw = promptCacheModel;
333
398
  const promptCacheCompat = isRecord(promptCacheRaw)
@@ -338,18 +403,30 @@ export function resolveResponsesRouteConfig(ctx, options, policy, assumeHostServ
338
403
  responsesCompat.supportsExplicitPromptCacheMode === undefined)
339
404
  responsesCompat.supportsExplicitPromptCacheMode = true;
340
405
  const resolvedCompat = Object.keys(responsesCompat).length ? responsesCompat : undefined;
341
- const supportsLongCacheRetention = resolvedCompat?.supportsLongCacheRetention ?? (lcxCapabilityRoute && policy.supportsLongCacheRetention === true);
406
+ // Pi defaults missing `supportsLongCacheRetention` to true (`model.compat?.supportsLongCacheRetention ?? true`)
407
+ // while leaving missing `cacheRetention` on `"short"` (`resolveCacheRetention`). Only explicit `lcx/gpt-5.6-*`
408
+ // capability routes retain LCX's legacy `supportsLongCacheRetention` -> `"long"` default when unconfigured.
409
+ const supportsLongCacheRetention = resolvedCompat?.supportsLongCacheRetention ??
410
+ (lcxCapabilityRoute ? policy.supportsLongCacheRetention === true : true);
342
411
  responsesCompat.supportsLongCacheRetention = supportsLongCacheRetention;
343
412
  const configuredRetention = configured.cacheRetention;
344
413
  const fallbackRetention = lcxCapabilityRoute ? policy.cacheRetention : undefined;
345
- const requestedRetention = configuredRetention === "none" || configuredRetention === "short" || configuredRetention === "long" ? configuredRetention : fallbackRetention === "none" || fallbackRetention === "short" || fallbackRetention === "long" ? fallbackRetention : undefined;
346
- const cacheRetention = requestedRetention === "long" && !supportsLongCacheRetention ? "short" : requestedRetention ?? (supportsLongCacheRetention ? "long" : "short");
414
+ const envRetention = process.env.PI_CACHE_RETENTION === "long" ? "long" : undefined;
415
+ const requestedRetention = configuredRetention === "none" || configuredRetention === "short" || configuredRetention === "long"
416
+ ? configuredRetention
417
+ : fallbackRetention === "none" || fallbackRetention === "short" || fallbackRetention === "long"
418
+ ? fallbackRetention
419
+ : envRetention;
420
+ const defaultRetention = lcxCapabilityRoute && supportsLongCacheRetention ? "long" : "short";
421
+ const cacheRetention = requestedRetention === "long" && !supportsLongCacheRetention ? "short" : (requestedRetention ?? defaultRetention);
347
422
  const declaredControls = declaredReasoningControls(configured, model);
423
+ const configuredModel = configuredModelProfile(configured, model);
348
424
  return {
349
425
  provider,
350
426
  model,
351
427
  api: "openai-responses",
352
428
  baseURL: normalizeBaseURL(baseURL),
429
+ rawBaseURL: baseURL,
353
430
  apiKeyEnv,
354
431
  ...(builtin?.headers === undefined ? {} : { catalogHeaders: { ...builtin.headers } }),
355
432
  headers: { ...(configured.headers ?? {}) },
@@ -359,9 +436,15 @@ export function resolveResponsesRouteConfig(ctx, options, policy, assumeHostServ
359
436
  // Only a declared `reasoningEfforts` is projected here; an undeclared model follows the catalog
360
437
  // and what DSH resolved for it (see `routeModelOverride`).
361
438
  ...(declaredControls === undefined ? {} : { modelControls: declaredControls }),
439
+ profileReasoning: profileReasoning(configured.reasoning),
440
+ ...(isPositiveSafeInteger(catalog.maxTokens) ? { catalogMaxTokens: catalog.maxTokens } : {}),
441
+ ...(isPositiveSafeInteger(configuredModel?.maxTokens) ? { profileModelMaxTokens: configuredModel.maxTokens } : {}),
442
+ ...(isPositiveSafeInteger(configured.defaultMaxTokens) ? { profileDefaultMaxTokens: configured.defaultMaxTokens } : {}),
362
443
  // These are explicitly LCX-owned transport and request-capability policies.
363
444
  timeoutMs: isPositiveSafeInteger(configured.timeoutMs) ? configured.timeoutMs : policy.timeoutMs,
364
445
  maxAttempts: retryAttempts(configured.retryPolicy, policy.maxAttempts),
446
+ maxRequestImages: isPositiveSafeInteger(configured.maxRequestImages) ? configured.maxRequestImages : 50,
447
+ imageOffloadCountQuantum: isPositiveSafeInteger(configured.imageOffloadCountQuantum) ? configured.imageOffloadCountQuantum : Math.min(10, isPositiveSafeInteger(configured.maxRequestImages) ? configured.maxRequestImages : 50),
365
448
  maxRequestImageBytes: isPositiveSafeInteger(configured.maxRequestImageBytes) ? configured.maxRequestImageBytes : policy.maxRequestImageBytes,
366
449
  requestImagePixelBudget: isPositiveSafeInteger(configured.requestImagePixelBudget) ? configured.requestImagePixelBudget : policy.requestImagePixelBudget,
367
450
  requestImageMaxBytes: isPositiveSafeInteger(configured.requestImageMaxBytes) ? configured.requestImageMaxBytes : policy.requestImageMaxBytes,
@@ -386,11 +469,11 @@ export function diagnoseResponsesRoute(ctx, options) {
386
469
  return "api-unresolved";
387
470
  return api === "openai-responses" ? "incomplete" : "api-not-responses";
388
471
  }
389
- /** Resolve a Grok-prefixed model through its selected DSH Responses profile. */
472
+ /** Resolve a Grok model through its selected DSH Responses profile. */
390
473
  export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
391
474
  const provider = String(options?.provider ?? "");
392
475
  const model = String(options?.model ?? "");
393
- if (!provider.trim() || !/^grok/iu.test(model))
476
+ if (!provider.trim() || !isGrokModelId(model))
394
477
  return undefined;
395
478
  const configured = configuredProviderProfile(ctx, provider);
396
479
  if (!isRecord(configured))
@@ -412,19 +495,28 @@ export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
412
495
  const responsesCompat = {};
413
496
  copyResponsesCompat(responsesCompat, selectedBuiltin?.compat);
414
497
  copyResponsesCompat(responsesCompat, configuredResponsesCompat(configured, model));
415
- const supportsLongCacheRetention = responsesCompat.supportsLongCacheRetention === true;
498
+ if (policy.promptCacheKeyMode === "disabled" || policy.promptCacheKeyMode === "enabled") {
499
+ responsesCompat.promptCacheKeyMode = policy.promptCacheKeyMode;
500
+ }
501
+ const supportsLongCacheRetention = responsesCompat.supportsLongCacheRetention !== false;
416
502
  responsesCompat.supportsLongCacheRetention = supportsLongCacheRetention;
417
- const requestedRetention = configured.cacheRetention;
503
+ const configuredRetention = configured.cacheRetention;
504
+ const envRetention = process.env.PI_CACHE_RETENTION === "long" ? "long" : undefined;
505
+ const requestedRetention = configuredRetention === "none" || configuredRetention === "short" || configuredRetention === "long"
506
+ ? configuredRetention
507
+ : envRetention;
418
508
  const cacheRetention = requestedRetention === "none"
419
509
  ? "none"
420
510
  : requestedRetention === "long" && supportsLongCacheRetention
421
511
  ? "long"
422
512
  : "short";
513
+ const configuredModel = configuredModelProfile(configured, model);
423
514
  return {
424
515
  provider,
425
516
  model,
426
517
  api: "openai-responses",
427
518
  baseURL: normalizeBaseURL(baseURL),
519
+ rawBaseURL: baseURL,
428
520
  apiKeyEnv,
429
521
  ...(selectedBuiltin?.headers === undefined ? {} : { catalogHeaders: { ...selectedBuiltin.headers } }),
430
522
  headers: effectiveGrokProfileHeaders(configured.headers),
@@ -437,6 +529,9 @@ export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
437
529
  includeEncryptedReasoning: true,
438
530
  },
439
531
  profileReasoning: profileReasoning(configured.reasoning),
532
+ ...(isPositiveSafeInteger(catalog.maxTokens) ? { catalogMaxTokens: catalog.maxTokens } : {}),
533
+ ...(isPositiveSafeInteger(configuredModel?.maxTokens) ? { profileModelMaxTokens: configuredModel.maxTokens } : {}),
534
+ ...(isPositiveSafeInteger(configured.defaultMaxTokens) ? { profileDefaultMaxTokens: configured.defaultMaxTokens } : {}),
440
535
  // Pi applies only an explicitly configured request deadline; stream liveness
441
536
  // is owned separately by the provider idle watchdog.
442
537
  timeoutMs: isPositiveSafeInteger(configured.timeoutMs)
@@ -446,6 +541,8 @@ export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
446
541
  ? configured.streamIdleTimeoutMs
447
542
  : DEFAULTS.streamIdleTimeoutMs,
448
543
  maxAttempts: retryAttempts(configured.retryPolicy, policy.maxAttempts),
544
+ maxRequestImages: isPositiveSafeInteger(configured.maxRequestImages) ? configured.maxRequestImages : 50,
545
+ imageOffloadCountQuantum: isPositiveSafeInteger(configured.imageOffloadCountQuantum) ? configured.imageOffloadCountQuantum : Math.min(10, isPositiveSafeInteger(configured.maxRequestImages) ? configured.maxRequestImages : 50),
449
546
  maxRequestImageBytes: isPositiveSafeInteger(configured.maxRequestImageBytes)
450
547
  ? configured.maxRequestImageBytes
451
548
  : policy.maxRequestImageBytes,
@@ -457,6 +554,104 @@ export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
457
554
  : policy.requestImageMaxBytes,
458
555
  };
459
556
  }
557
+ function positiveFiniteNumber(value) {
558
+ return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
559
+ }
560
+ function isGrokBudgetRoute(route) {
561
+ const provider = String(route?.provider ?? "").trim();
562
+ return provider.length > 0 && isGrokModelId(route?.model);
563
+ }
564
+ export function grokBudgetInputSignature(ctx, route, requestMaxTokens) {
565
+ const provider = String(route?.provider ?? "").trim();
566
+ const model = String(route?.model ?? "").trim();
567
+ const profile = provider ? configuredProviderProfile(ctx, provider) : undefined;
568
+ const modelProfile = isRecord(profile) && model ? configuredModelProfile(profile, model) : undefined;
569
+ return JSON.stringify([
570
+ requestMaxTokens ?? null,
571
+ isRecord(profile) ? profile.defaultContextWindow ?? null : null,
572
+ modelProfile?.contextWindow ?? null,
573
+ modelProfile?.maxTokens ?? null,
574
+ Array.isArray(profile?.models) ? profile.models.map((entry) => String(entry?.id ?? "")) : null,
575
+ ]);
576
+ }
577
+ /**
578
+ * Pure pre-flight diagnostic for Grok profiles whose resolved `maxTokens >= contextWindow`.
579
+ *
580
+ * In DSH 0.2.2 (`dsh-llm-pi-ai` + `dsh-compaction-basic`), an explicit `maxTokens` on `models[]` or
581
+ * `modelOverrides` becomes `ModelInfo.defaultMaxTokens` (reserved completion tokens). When `requestMaxTokens`
582
+ * or `defaultMaxTokens >= contextWindow`, `contextWindow - reservedCompletionTokens <= 0`, blocking model
583
+ * switches to Grok with `MODEL_SWITCH_COMPACTION_FAILED`.
584
+ */
585
+ export function diagnoseGrokProfileBudget(profile, route, options) {
586
+ const provider = String(route?.provider ?? "").trim();
587
+ const model = String(route?.model ?? "").trim();
588
+ if (!provider || !isGrokBudgetRoute({ provider, model }))
589
+ return undefined;
590
+ if (isRecord(profile) && profileExcludesModel(profile, model))
591
+ return undefined;
592
+ if (!isRecord(profile) && !options?.resolvedModelInfo)
593
+ return undefined;
594
+ const modelProfile = isRecord(profile) && model ? configuredModelProfile(profile, model) : undefined;
595
+ const catalogModel = model ? getCatalogModels(provider).find((entry) => entry.id === model) : undefined;
596
+ const contextWindow = positiveFiniteNumber(options?.resolvedModelInfo?.contextWindow) ??
597
+ positiveFiniteNumber(modelProfile?.contextWindow) ??
598
+ positiveFiniteNumber(catalogModel?.contextWindow) ??
599
+ (isRecord(profile) ? positiveFiniteNumber(profile.defaultContextWindow) : undefined);
600
+ const maxTokens = positiveFiniteNumber(options?.requestMaxTokens) ??
601
+ positiveFiniteNumber(options?.resolvedModelInfo?.defaultMaxTokens) ??
602
+ positiveFiniteNumber(modelProfile?.maxTokens);
603
+ if (contextWindow === undefined || maxTokens === undefined || maxTokens < contextWindow)
604
+ return undefined;
605
+ const target = model ? `${provider}/${model}` : provider;
606
+ return `[lcx-codex] Grok route "${target}" resolves maxTokens (${maxTokens}) >= contextWindow (${contextWindow}); DSH 0.2.2 blocks switching to Grok with MODEL_SWITCH_COMPACTION_FAILED (leaving zero message budget). Set maxTokens clearly below contextWindow (for example, 64000 or 128000 for a 500000 context window) in the llm-pi-ai provider profile ("models[].maxTokens" or "modelOverrides[\\"${model}\\"].maxTokens") or pass a lower request maxTokens.`;
607
+ }
608
+ export function diagnoseGrokContextBudget(ctx, route, options) {
609
+ if (!isGrokBudgetRoute(route))
610
+ return undefined;
611
+ const provider = String(route?.provider ?? "").trim();
612
+ const profile = configuredProviderProfile(ctx, provider);
613
+ return diagnoseGrokProfileBudget(profile, route, options);
614
+ }
615
+ export function grokRouteMayNeedHostBudgetLookup(ctx, route, requestMaxTokens) {
616
+ const provider = String(route?.provider ?? "").trim();
617
+ const model = String(route?.model ?? "").trim();
618
+ if (!provider || !isGrokBudgetRoute({ provider, model }))
619
+ return false;
620
+ const profile = configuredProviderProfile(ctx, provider);
621
+ if (!isRecord(profile) || profileExcludesModel(profile, model))
622
+ return false;
623
+ const modelProfile = configuredModelProfile(profile, model);
624
+ return (positiveFiniteNumber(requestMaxTokens) !== undefined ||
625
+ positiveFiniteNumber(modelProfile?.maxTokens) !== undefined);
626
+ }
627
+ export async function diagnoseGrokContextBudgetAsync(ctx, route, options) {
628
+ const provider = String(route?.provider ?? "").trim();
629
+ const model = String(route?.model ?? "").trim();
630
+ if (!provider || !isGrokBudgetRoute({ provider, model }))
631
+ return undefined;
632
+ const profile = configuredProviderProfile(ctx, provider);
633
+ if (!isRecord(profile) || profileExcludesModel(profile, model))
634
+ return undefined;
635
+ let resolvedModelInfo;
636
+ if (typeof ctx?.llm?.resolveModelInfo === "function") {
637
+ try {
638
+ const info = await ctx.llm.resolveModelInfo(provider, model, options?.signal);
639
+ if (isRecord(info)) {
640
+ resolvedModelInfo = {
641
+ contextWindow: isRecord(info.context) ? info.context.contextWindow : undefined,
642
+ defaultMaxTokens: info.defaultMaxTokens,
643
+ };
644
+ }
645
+ }
646
+ catch {
647
+ // Fall back to configured profile + catalog metadata if host model resolution fails.
648
+ }
649
+ }
650
+ return diagnoseGrokProfileBudget(profile, route, {
651
+ requestMaxTokens: options?.requestMaxTokens,
652
+ resolvedModelInfo,
653
+ });
654
+ }
460
655
  export async function resolveApiKey(ctx, config) {
461
656
  const resolved = await ctx?.credentials.resolve(credentialRef(config.apiKeyEnv));
462
657
  // DSH's own definition of a usable key (trimmed, nothing an HTTP header cannot carry). A rejected key is
@@ -503,21 +698,59 @@ function sessionAffinityFormat(config) {
503
698
  ? "openrouter"
504
699
  : "openai";
505
700
  }
701
+ /** Headers whose owners (credentials, session affinity, correlation) layer them after the contributors. */
702
+ const OWNER_PROTECTED_HEADERS = new Set(["authorization", "cf-aig-authorization", "proxy-authorization", "x-api-key", "api-key", "cookie", "session_id", "session-id", "x-session-id", "x-client-request-id", "x-opencode-session"]);
703
+ /** The host exposes profile headers only. Credential and routing headers are layered by their owners later. */
704
+ export function prepareRequestHeaders(ctx, config, options = {}) {
705
+ try {
706
+ const initial = new Headers();
707
+ // Contributors must never observe explicit profile credentials or routing/session affinity headers;
708
+ // owners re-apply protected profile headers after contributors run.
709
+ for (const [name, value] of Object.entries(config.headers ?? {})) {
710
+ if (!OWNER_PROTECTED_HEADERS.has(name.toLowerCase()))
711
+ initial.set(name, value);
712
+ }
713
+ const request = Object.freeze({ provider: config.provider, model: config.model, baseURL: config.rawBaseURL ?? config.baseURL,
714
+ ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId }),
715
+ ...(options.purpose === undefined ? {} : { purpose: options.purpose }) });
716
+ const waterfall = ctx?.waterfall;
717
+ const headers = waterfall === undefined ? initial : waterfall.call(ctx, "llm-pi-ai/request-headers", request, initial, () => initial);
718
+ for (const [name, value] of Object.entries(attributionHeaders()))
719
+ headers.set(name, value);
720
+ return Object.fromEntries(headers);
721
+ }
722
+ catch (error) {
723
+ const diagnostic = error instanceof TypeError
724
+ ? "TypeError during header preparation; check the contributing plugin's header names, values, and configuration"
725
+ : error instanceof Error ? error.message : "the contributing plugin threw a non-Error value; throw an Error with a safe diagnostic";
726
+ throw new LlmError(`pi-ai request header preparation failed for provider "${config.provider}": ${diagnostic}`, "REQUEST_HEADERS", { cause: error });
727
+ }
728
+ }
729
+ function computeReplayAuthorityHeaders(contributorHeaders, protectedProfile) {
730
+ const attributionKeys = new Set(Object.keys(attributionHeaders()).map((name) => name.toLowerCase()));
731
+ const authorityContributors = Object.fromEntries(Object.entries(contributorHeaders).filter(([name]) => !attributionKeys.has(name.toLowerCase())));
732
+ return layerHeaders(authorityContributors, protectedProfile);
733
+ }
506
734
  /**
507
735
  * The headers of one GPT request. `sessionId` is the prompt-cache / affinity session (the root session for a
508
736
  * subagent, absent without cache retention); `providerSessionId` is the CURRENT DSH session, which is what Pi's
509
737
  * client sends in provider routing headers (`x-opencode-session`) whatever the cache policy is.
510
738
  */
511
- export async function authenticatedHeaders(ctx, config, sessionId, requestId, dynamicHeaders = {}, providerSessionId) {
739
+ export async function authenticatedRequestHeaders(ctx, config, sessionId, requestId, dynamicHeaders = {}, providerSessionId, request, resolvedApiKey) {
512
740
  const explicit = { ...(config.headers ?? {}) };
741
+ const currentSessionId = providerSessionId ?? (sessionId ? String(sessionId) : undefined);
742
+ // As on the host, the credential is resolved before contributors run: a missing one never reaches them.
743
+ const apiKey = resolvedApiKey ?? (await resolveApiKey(ctx, config));
744
+ const prepared = prepareRequestHeaders(ctx, config, request ?? (currentSessionId === undefined ? {} : { sessionId: currentSessionId }));
745
+ const contributorHeaders = Object.fromEntries(Object.entries(prepared).filter(([name]) => !OWNER_PROTECTED_HEADERS.has(name.toLowerCase())));
513
746
  const sid = sessionId ? String(sessionId) : undefined;
514
747
  const format = sessionAffinityFormat(config);
515
- // Lowest first, as Pi's client layers them: the catalog model's own headers, DSH attribution, the credential,
516
- // the provider's per-request headers (Copilot initiator / vision, OpenCode routing), then the affinity ids.
517
- const headers = layerHeaders(config.catalogHeaders, attributionHeaders(), { authorization: `Bearer ${await resolveApiKey(ctx, config)}` }, dynamicHeaders, providerSessionHeaders(config.provider, providerSessionId ?? sid));
748
+ // Model/provider defaults precede the contributed profile layer. Credentials and session routing
749
+ // are owned by their later layers; attribution is re-applied last.
750
+ const headers = layerHeaders(config.catalogHeaders, dynamicHeaders, contributorHeaders, { authorization: `Bearer ${apiKey}` }, providerSessionHeaders(config.provider, providerSessionId ?? sid));
518
751
  if (sid && !hasExplicitSessionAffinity(explicit)) {
519
752
  if (format === "openai")
520
- headers.session_id = sid;
753
+ headers["session-id"] = sid;
521
754
  else if (format === "openrouter")
522
755
  headers["x-session-id"] = sid;
523
756
  }
@@ -526,34 +759,70 @@ export async function authenticatedHeaders(ctx, config, sessionId, requestId, dy
526
759
  if (correlation)
527
760
  headers["x-client-request-id"] = correlation;
528
761
  }
529
- // The profile's own headers win over every default.
530
- return layerHeaders(headers, explicit);
762
+ // Ordinary profile headers keep whatever the contributors made of them. The owner-protected ones (credential,
763
+ // session affinity, correlation) are the profile's to set over every default and never a contributor's.
764
+ // Attribution is re-applied last, as on the host.
765
+ const protectedProfile = Object.fromEntries(Object.entries(explicit).filter(([name]) => OWNER_PROTECTED_HEADERS.has(name.toLowerCase())));
766
+ const finalHeaders = layerHeaders(headers, protectedProfile, attributionHeaders());
767
+ const replayAuthorityHeaders = computeReplayAuthorityHeaders(contributorHeaders, protectedProfile);
768
+ const headerAuthorityFingerprint = requestHeaderAuthorityFingerprint(replayAuthorityHeaders, {
769
+ apiKeyEnv: config.apiKeyEnv,
770
+ effectiveAuthorization: findHeaderCaseInsensitive(finalHeaders, "authorization"),
771
+ });
772
+ return {
773
+ headers: finalHeaders,
774
+ replayAuthorityHeaders,
775
+ headerAuthorityFingerprint,
776
+ };
531
777
  }
532
- /** Grok mirrors Pi createClient ordering without changing accepted GPT headers. */
533
- export async function authenticatedGrokHeaders(ctx, config, sessionId, dynamicHeaders = {}, providerSessionId) {
778
+ export async function authenticatedHeaders(ctx, config, sessionId, requestId, dynamicHeaders = {}, providerSessionId, request, resolvedApiKey) {
779
+ return (await authenticatedRequestHeaders(ctx, config, sessionId, requestId, dynamicHeaders, providerSessionId, request, resolvedApiKey)).headers;
780
+ }
781
+ /** Grok mirrors Pi createClient ordering and request-header contributor hook without changing accepted GPT precedence. */
782
+ export async function authenticatedGrokRequestHeaders(ctx, config, sessionId, dynamicHeaders = {}, providerSessionId, request, resolvedApiKey) {
534
783
  const explicit = effectiveGrokProfileHeaders(config.headers);
535
784
  const sid = sessionId ? String(sessionId) : undefined;
536
- // The catalog model's headers come first, so DSH attribution (applied last, as the host does) replaces them.
537
- const headers = layerHeaders(config.catalogHeaders, {
538
- authorization: `Bearer ${await resolveApiKey(ctx, config)}`,
539
- }, dynamicHeaders, providerSessionHeaders(config.provider, providerSessionId ?? sid));
785
+ const currentSessionId = providerSessionId ?? sid;
786
+ // Resolve credentials before contributors run, matching authenticatedHeaders and DSH PiAiAdapter.
787
+ const apiKey = resolvedApiKey ?? (await resolveApiKey(ctx, config));
788
+ const prepared = prepareRequestHeaders(ctx, { ...config, headers: explicit }, request ?? (currentSessionId === undefined ? {} : { sessionId: currentSessionId }));
789
+ const contributorHeaders = Object.fromEntries(Object.entries(prepared).filter(([name]) => !OWNER_PROTECTED_HEADERS.has(name.toLowerCase())));
790
+ // The catalog model's headers precede contributed/dynamic layers; credentials, session affinity,
791
+ // protected profile headers, and final DSH attribution follow in owner order.
792
+ const headers = layerHeaders(config.catalogHeaders, dynamicHeaders, contributorHeaders, { authorization: `Bearer ${apiKey}` }, providerSessionHeaders(config.provider, currentSessionId));
540
793
  const format = sessionAffinityFormat(config);
541
794
  if (sid) {
542
795
  if (format === "openai")
543
- headers.session_id = sid;
796
+ headers["session-id"] = sid;
544
797
  else if (format === "openrouter")
545
798
  headers["x-session-id"] = sid;
546
799
  if (format === "openai" || format === "openai-nosession")
547
800
  headers["x-client-request-id"] = sid;
548
801
  }
549
- for (const [name, value] of Object.entries(explicit))
550
- setHeaderCaseInsensitive(headers, name, value);
551
- for (const [name, value] of Object.entries(attributionHeaders()))
552
- setHeaderCaseInsensitive(headers, name, value);
553
- return headers;
802
+ const protectedProfile = Object.fromEntries(Object.entries(explicit).filter(([name]) => OWNER_PROTECTED_HEADERS.has(name.toLowerCase())));
803
+ const finalHeaders = layerHeaders(headers, protectedProfile, attributionHeaders());
804
+ const replayAuthorityHeaders = computeReplayAuthorityHeaders(contributorHeaders, protectedProfile);
805
+ const headerAuthorityFingerprint = requestHeaderAuthorityFingerprint(replayAuthorityHeaders, {
806
+ apiKeyEnv: config.apiKeyEnv,
807
+ effectiveAuthorization: findHeaderCaseInsensitive(finalHeaders, "authorization"),
808
+ });
809
+ return {
810
+ headers: finalHeaders,
811
+ replayAuthorityHeaders,
812
+ headerAuthorityFingerprint,
813
+ };
814
+ }
815
+ export async function authenticatedGrokHeaders(ctx, config, sessionId, dynamicHeaders = {}, providerSessionId, request, resolvedApiKey) {
816
+ return (await authenticatedGrokRequestHeaders(ctx, config, sessionId, dynamicHeaders, providerSessionId, request, resolvedApiKey)).headers;
554
817
  }
555
818
  export function currentRoute(options, config) {
556
- return { provider: String(options?.provider ?? config.provider ?? ""), model: String(options?.model ?? config.model ?? ""), baseURL: normalizeBaseURL(config.baseURL), sessionId: String(options?.sessionId ?? "") };
819
+ return {
820
+ provider: String(options?.provider ?? config.provider ?? ""),
821
+ model: String(options?.model ?? config.model ?? ""),
822
+ baseURL: normalizeBaseURL(config.baseURL),
823
+ ...(config.rawBaseURL === undefined ? {} : { rawBaseURL: config.rawBaseURL }),
824
+ sessionId: String(options?.sessionId ?? ""),
825
+ };
557
826
  }
558
827
  export function generationControlsFromHeader(header, route) {
559
828
  const config = header?.config;
@@ -576,7 +845,58 @@ export function generationControlsFromSession(session, route) {
576
845
  return {};
577
846
  }
578
847
  }
848
+ export async function resolveRouteHeaderAuthorityFingerprint(ctx, route, routeConfig, request) {
849
+ const provider = String(route?.provider ?? routeConfig?.provider ?? "");
850
+ const model = String(route?.model ?? routeConfig?.model ?? "");
851
+ const baseURL = String(route?.baseURL ?? routeConfig?.baseURL ?? "");
852
+ const sessionId = String(route?.sessionId ?? "");
853
+ const resolvedFromCtx = provider && model
854
+ ? resolveResponsesRouteConfig(ctx, { provider, model }, {})
855
+ : undefined;
856
+ const rawApiKeyEnv = typeof routeConfig?.apiKeyEnv === "string" && routeConfig.apiKeyEnv.length > 0
857
+ ? routeConfig.apiKeyEnv
858
+ : resolvedFromCtx?.apiKeyEnv;
859
+ const effectiveApiKeyEnv = rawApiKeyEnv ?? "";
860
+ const effectiveHeaders = routeConfig?.headers ?? resolvedFromCtx?.headers;
861
+ if (typeof ctx?.credentials?.resolve === "function") {
862
+ const effectiveConfig = {
863
+ ...(resolvedFromCtx ?? {}),
864
+ ...(routeConfig ?? {}),
865
+ provider,
866
+ model,
867
+ api: "openai-responses",
868
+ baseURL,
869
+ apiKeyEnv: effectiveApiKeyEnv,
870
+ cacheRetention: (routeConfig?.cacheRetention ?? resolvedFromCtx?.cacheRetention ?? "short"),
871
+ supportsLongCacheRetention: Boolean(routeConfig?.supportsLongCacheRetention ?? resolvedFromCtx?.supportsLongCacheRetention),
872
+ ...(effectiveHeaders === undefined ? {} : { headers: effectiveHeaders }),
873
+ };
874
+ try {
875
+ const apiKey = await resolveApiKey(ctx, { apiKeyEnv: rawApiKeyEnv });
876
+ const cacheSessionId = promptCacheSessionId({ provider, model, baseURL, sessionId }, effectiveConfig, ctx);
877
+ return (await authenticatedRequestHeaders(ctx, effectiveConfig, cacheSessionId, cacheSessionId === undefined ? null : sessionId, {}, sessionId || undefined, request, apiKey)).headerAuthorityFingerprint;
878
+ }
879
+ catch {
880
+ return requestHeaderAuthorityFingerprint(effectiveHeaders, {
881
+ apiKeyEnv: effectiveApiKeyEnv,
882
+ });
883
+ }
884
+ }
885
+ return requestHeaderAuthorityFingerprint(effectiveHeaders, {
886
+ apiKeyEnv: effectiveApiKeyEnv,
887
+ });
888
+ }
579
889
  export function routeCompatible(record, route, ctx) {
580
890
  void ctx;
581
- return !!record && record.version === 5 && record.provider === route.provider && record.model === route.model && record.baseURLFingerprint === baseURLFingerprint(route.baseURL) && record.sourceSessionId === route.sessionId;
891
+ return (!!record &&
892
+ record.version === 5 &&
893
+ record.provider === route.provider &&
894
+ record.model === route.model &&
895
+ record.baseURLFingerprint === baseURLFingerprint(route.baseURL) &&
896
+ record.sourceSessionId === route.sessionId &&
897
+ typeof record.headerAuthorityFingerprint === "string" &&
898
+ record.headerAuthorityFingerprint.length > 0 &&
899
+ typeof route.headerAuthorityFingerprint === "string" &&
900
+ route.headerAuthorityFingerprint.length > 0 &&
901
+ record.headerAuthorityFingerprint === route.headerAuthorityFingerprint);
582
902
  }
@@ -51,7 +51,7 @@ export const searchUsageProjection = {
51
51
  };
52
52
  const installed = new WeakMap();
53
53
  /** Own a reversible adapter on the public measure method, never a DSH file or private fold. */
54
- export function installSearchMeasurement(meter, projections) {
54
+ export function installSearchMeasurement(meter, projection) {
55
55
  const existing = installed.get(meter);
56
56
  if (existing) {
57
57
  existing.refs++;
@@ -64,7 +64,7 @@ export function installSearchMeasurement(meter, projections) {
64
64
  const original = meter.measure, descriptor = Object.getOwnPropertyDescriptor(meter, 'measure');
65
65
  function measure(session, header) {
66
66
  const value = original.call(this, session, header);
67
- const state = projections.stateOf(session, 'lcxSearchUsage');
67
+ const state = projection.stateOf(session);
68
68
  if (!state?.aggregateContext)
69
69
  return value;
70
70
  const effectiveHeader = header ?? session.requestHeader();
@@ -106,8 +106,10 @@ function release(meter) {
106
106
  }
107
107
  }
108
108
  export function installSearchUsage(ctx) {
109
- ctx.inject(['sessionProjections'], c => { c.sessionProjections.register(searchUsageProjection); });
110
- ctx.inject(['tokenMeter', 'sessionProjections'], c => {
111
- c.effect(() => installSearchMeasurement(c.tokenMeter, c.sessionProjections), 'lcx search context measurement');
109
+ ctx.inject(['sessionProjections'], async (c) => {
110
+ const handle = await c.sessionProjections.register(searchUsageProjection);
111
+ c.inject(['tokenMeter'], c => {
112
+ c.effect(() => installSearchMeasurement(c.tokenMeter, handle), 'lcx search context measurement');
113
+ });
112
114
  });
113
115
  }