dsh-lcx-codex 0.6.0-pre.1 → 0.6.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,43 +2,24 @@ 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 { attributionHeaders, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
6
- import { getBuiltinModels, getBuiltinProviders, } from "./pi-responses-runtime.js";
7
- import { wasPi086ResponsesModel } from "./pi086-responses-allowlist.js";
8
- /** @param {unknown} value */
9
- function isRecord(value) {
10
- return value !== null && typeof value === "object" && !Array.isArray(value);
11
- }
12
- /** @param {unknown} value */
13
- function isPositiveInteger(value) {
14
- return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
15
- }
16
- function isPositiveFinite(value) {
17
- return typeof value === "number" && Number.isFinite(value) && value > 0;
18
- }
19
- /** @param {unknown} value */
5
+ import { assertUsableApiKey, attributionHeaders, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
6
+ import { resolveCatalogModel } from "./model-catalog.js";
7
+ import { clampOpenAIPromptCacheKey } from "./pi-responses-runtime.js";
8
+ import { providerSessionHeaders } from "./provider-headers.js";
9
+ import { codedError, isPositiveFinite, isPositiveSafeInteger, isRecord } from "./util.js";
10
+ import { DEFAULTS } from "./defaults.js";
20
11
  export function normalizeBaseURL(value) {
21
12
  return String(value ?? "").trim().replace(/\/+$/u, "");
22
13
  }
23
- /** @param {unknown} baseURL */
24
14
  export function baseURLFingerprint(baseURL) {
25
15
  return createHash("sha256").update(normalizeBaseURL(baseURL), "utf8").digest("hex");
26
16
  }
27
- /** @param {Partial<RouteIdentity> | null | undefined} route @param {{ includeSession?: boolean }} [options] */
28
17
  export function routeFingerprint(route, options = {}) {
29
18
  const includeSession = options.includeSession !== false;
30
19
  return createHash("sha256").update([
31
20
  route?.provider ?? "", route?.model ?? "", normalizeBaseURL(route?.baseURL), includeSession ? (route?.sessionId ?? "") : "",
32
21
  ].join("\u001f"), "utf8").digest("hex");
33
22
  }
34
- /** @param {unknown} value */
35
- function clampPromptCacheKey(value) {
36
- if (value === undefined)
37
- return undefined;
38
- const chars = Array.from(String(value));
39
- return chars.length <= 64 ? String(value) : chars.slice(0, 64).join("");
40
- }
41
- /** @param {Partial<RouteIdentity> | null | undefined} route @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention'>>} [config] @param {RouteContext | null | undefined} [ctx] */
42
23
  export function promptCacheSessionId(route, config = {}, ctx = undefined) {
43
24
  if (config.cacheRetention === "none")
44
25
  return undefined;
@@ -62,9 +43,8 @@ export function promptCacheSessionId(route, config = {}, ctx = undefined) {
62
43
  }
63
44
  return current?.id ?? sessionId;
64
45
  }
65
- /** @param {Partial<RouteIdentity> | null | undefined} route @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention'>>} [config] @param {RouteContext | null | undefined} [ctx] */
66
46
  export function promptCacheKey(route, config = {}, ctx = undefined) {
67
- return clampPromptCacheKey(promptCacheSessionId(route, config, ctx));
47
+ return clampOpenAIPromptCacheKey(promptCacheSessionId(route, config, ctx));
68
48
  }
69
49
  /** Grok follows Pi directly: cache/affinity belongs to the selected child session. */
70
50
  export function grokPromptCacheSessionId(route, config = {}) {
@@ -73,18 +53,16 @@ export function grokPromptCacheSessionId(route, config = {}) {
73
53
  const sessionId = String(route?.sessionId ?? "");
74
54
  return sessionId || undefined;
75
55
  }
76
- /** @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention' | 'supportsLongCacheRetention' | 'responsesCompat'>>} [config] */
77
56
  export function promptCacheRetention(config = {}) {
78
57
  return config.cacheRetention === "long" && config.supportsLongCacheRetention === true && config.responsesCompat?.supportsExplicitPromptCacheMode !== true ? "24h" : undefined;
79
58
  }
80
- /** @param {RetryPolicyConfig | null | undefined} policy @param {number} [fallback] */
81
- function retryAttempts(policy, fallback = 3) {
59
+ function retryAttempts(policy, fallback = DEFAULTS.maxAttempts) {
82
60
  if (!policy)
83
61
  return fallback;
84
62
  try {
85
63
  const resolved = resolveRetryPolicy(policy, "llm-pi-ai provider retryPolicy");
86
- if (resolved.mode === "normal" && isPositiveInteger(resolved.maxRetries))
87
- return Math.min(resolved.maxRetries + 1, 6);
64
+ if (resolved.mode === "normal" && isPositiveSafeInteger(resolved.maxRetries))
65
+ return Math.min(resolved.maxRetries + 1, DEFAULTS.maxAttemptsCap);
88
66
  }
89
67
  catch { }
90
68
  return fallback;
@@ -109,9 +87,7 @@ function configuredProviderProfile(ctx, provider) {
109
87
  return undefined;
110
88
  }
111
89
  }
112
- /** @type {Set<keyof ResponsesCompat>} */
113
90
  const RESPONSES_COMPAT_FIELDS = new Set(["supportsDeveloperRole", "sessionAffinityFormat", "supportsStrictMode", "supportsLongCacheRetention", "supportsOpenAIGrammarTools", "supportsAdditionalTools", "supportsToolSearch", "supportsExplicitPromptCacheMode", "supportsMaxOutputTokens"]);
114
- /** @param {ResponsesCompat} target @param {unknown} source */
115
91
  function copyResponsesCompat(target, source) {
116
92
  if (!isRecord(source))
117
93
  return;
@@ -125,17 +101,6 @@ function copyResponsesCompat(target, source) {
125
101
  Object.assign(target, { [field]: value });
126
102
  }
127
103
  }
128
- /** @param {unknown} provider @param {unknown} modelId */
129
- function builtinResponsesModel(provider, modelId) {
130
- const providerName = String(provider ?? "");
131
- // A newer plugin-Pi catalog must not grant LCX a route that Pi 0.86 lacked.
132
- if (!wasPi086ResponsesModel(providerName, String(modelId ?? "")))
133
- return undefined;
134
- const builtinProvider = getBuiltinProviders().find((candidate) => candidate === providerName);
135
- if (builtinProvider === undefined)
136
- return undefined;
137
- return getBuiltinModels(builtinProvider).find((model) => model.id === String(modelId ?? "") && model.api === "openai-responses");
138
- }
139
104
  function modelDescriptorDefaults(model) {
140
105
  if (!model)
141
106
  return undefined;
@@ -144,13 +109,133 @@ function modelDescriptorDefaults(model) {
144
109
  thinkingLevelMap: model.thinkingLevelMap,
145
110
  };
146
111
  }
112
+ /**
113
+ * Models DSH itself resolved (`llm.resolveModelInfo` succeeded), remembered per plugin context together with a
114
+ * fingerprint of the provider profile they were observed under. The route resolvers are synchronous, so the
115
+ * stream handler asks DSH once for a route it cannot resolve and records the answer here; later resolutions of
116
+ * the same model under the same profile need no further lookup. A live profile change alters the fingerprint,
117
+ * which drops the answer and lets a fresh lookup decide again.
118
+ */
119
+ const hostRecognizedModels = new WeakMap();
120
+ function recognitionKey(provider, modelId) {
121
+ return `${String(provider)}\u001f${String(modelId)}`;
122
+ }
123
+ /** What decides whether DSH serves a model of this provider: the endpoint, the protocol and the served model ids. */
124
+ function profileFingerprint(profile) {
125
+ const ids = (list) => Array.isArray(list) ? list.map((entry) => String(entry?.id ?? "")) : [];
126
+ return JSON.stringify([
127
+ profile?.api ?? null,
128
+ profile?.baseURL ?? null,
129
+ ids(profile?.models),
130
+ Object.keys(profile?.modelOverrides ?? {}).sort(),
131
+ ]);
132
+ }
133
+ /**
134
+ * Record that DSH resolves this exact provider/model under the provider's current profile.
135
+ * @returns whether this changed what is remembered (a new model, or the profile changed since).
136
+ */
137
+ export function markHostRecognizedModel(ctx, provider, modelId) {
138
+ const owner = ctx;
139
+ if (owner === null || typeof owner !== "object")
140
+ return false;
141
+ let known = hostRecognizedModels.get(owner);
142
+ if (known === undefined)
143
+ hostRecognizedModels.set(owner, known = new Map());
144
+ if (known.size >= 256)
145
+ known.clear();
146
+ const key = recognitionKey(provider, modelId);
147
+ const fingerprint = profileFingerprint(configuredProviderProfile(ctx, String(provider)));
148
+ const changed = known.get(key) !== fingerprint;
149
+ known.set(key, fingerprint);
150
+ return changed;
151
+ }
152
+ /**
153
+ * Ask DSH, ahead of any request, which GPT / Grok models it serves on providers whose profile lists no
154
+ * `models`, and remember the ones LCX's bundled catalog does not describe. One `listModels` call per such
155
+ * provider: it returns exactly the models DSH would resolve. A model listed in a profile needs no lookup
156
+ * (the list itself declares it) and a provider DSH does not serve is skipped.
157
+ * @returns whether the remembered set changed, so the caller can resynchronise the tools it registers.
158
+ */
159
+ export async function warmHostRecognizedModels(ctx) {
160
+ let entries;
161
+ try {
162
+ entries = ctx?.llm.listConfigurableProviders() ?? [];
163
+ }
164
+ catch {
165
+ return false;
166
+ }
167
+ let changed = false;
168
+ for (const entry of entries) {
169
+ if (entry.settingsNs !== "llm-pi-ai" || (typeof entry.error === "string" && entry.error.trim()))
170
+ continue;
171
+ const profile = configuredProviderProfile(ctx, entry.provider);
172
+ if (!isRecord(profile) || (Array.isArray(profile.models) && profile.models.length > 0))
173
+ continue;
174
+ let models;
175
+ try {
176
+ models = (await ctx?.llm.listModels(entry.provider)) ?? [];
177
+ }
178
+ catch {
179
+ continue;
180
+ }
181
+ for (const model of models) {
182
+ if (!/^(?:gpt-|grok)/iu.test(model.id))
183
+ continue;
184
+ if (resolveCatalogModel(entry.provider, model.id).source === "catalog-model")
185
+ continue;
186
+ if (markHostRecognizedModel(ctx, entry.provider, model.id))
187
+ changed = true;
188
+ }
189
+ }
190
+ return changed;
191
+ }
192
+ function hostRecognizesModel(ctx, profile, provider, modelId) {
193
+ const owner = ctx;
194
+ if (owner === null || typeof owner !== "object")
195
+ return false;
196
+ return hostRecognizedModels.get(owner)?.get(recognitionKey(provider, modelId)) === profileFingerprint(profile);
197
+ }
198
+ /**
199
+ * Providers whose authentication Pi resolves itself and LCX cannot reproduce from one credential reference:
200
+ * Cloudflare AI Gateway needs the account and gateway ids in the endpoint and sends the key as
201
+ * `cf-aig-authorization` while removing `Authorization`. DSH serves them, LCX leaves them to DSH.
202
+ */
203
+ const HOST_AUTH_PROVIDERS = new Set(["cloudflare-ai-gateway"]);
204
+ function usesHostProviderAuth(provider) {
205
+ return HOST_AUTH_PROVIDERS.has(String(provider));
206
+ }
207
+ /**
208
+ * A nonempty `models` list replaces the served catalog: DSH serves exactly the listed models, and LCX answers
209
+ * `llm/stream` before DSH's adapter does, so a claim here would send a request DSH itself refuses.
210
+ */
211
+ function profileExcludesModel(profile, modelId) {
212
+ return Array.isArray(profile?.models) && profile.models.length > 0 &&
213
+ !profile.models.some((entry) => String(entry?.id ?? "") === String(modelId));
214
+ }
215
+ /**
216
+ * DSH serves a model its catalog does not describe only when the profile lists it in `models`, or, for a profile
217
+ * with no `models` list, when its own (newer) catalog describes it; the latter is visible to a plugin only as a
218
+ * successful `resolveModelInfo`. A nonempty `models` list is authoritative: DSH serves exactly the listed models,
219
+ * so a remembered recognition never widens it.
220
+ *
221
+ * `assumeHostServes` answers the undecided case optimistically, for the one decision that cannot wait for DSH:
222
+ * which tools to register while an agent's tools are assembled. It is exact, not a guess: a model on a provider
223
+ * with no `models` list that DSH does not serve is refused by DSH (UNKNOWN_MODEL) before any request, so no tool
224
+ * is ever sent for it, and one DSH does serve is taken by LCX (the stream awaits DSH's answer; see
225
+ * `hostRecognizedRouteStream`), which is where the tools are used. The protocol still has to be the provider's
226
+ * shared Responses protocol, and the model must not be one the catalog itself marks as another protocol.
227
+ */
228
+ function dshServesModel(ctx, profile, provider, modelId, assumeHostServes = false) {
229
+ if (Array.isArray(profile?.models) && profile.models.length > 0)
230
+ return profile.models.some((entry) => String(entry?.id ?? "") === String(modelId));
231
+ return assumeHostServes || hostRecognizesModel(ctx, profile, provider, modelId);
232
+ }
147
233
  function configuredModelProfile(profile, modelId) {
148
234
  const configuredModels = Array.isArray(profile?.models) ? profile.models : [];
149
235
  return configuredModels.length > 0
150
236
  ? configuredModels.find((entry) => String(entry?.id ?? "") === String(modelId))
151
237
  : profile?.modelOverrides?.[String(modelId)];
152
238
  }
153
- /** @param {ProviderProfile | null | undefined} profile @param {unknown} modelId @returns {ResponsesCompat | undefined} */
154
239
  function configuredResponsesCompat(profile, modelId) {
155
240
  const compat = {};
156
241
  copyResponsesCompat(compat, profile?.compat);
@@ -189,7 +274,7 @@ function declaredReasoningControls(profile, modelId) {
189
274
  if (value === undefined)
190
275
  thinkingLevelMap[level] = null;
191
276
  else if (value === null) {
192
- // DSH permits only off:null: it means supported-off by omitting the wire option. Pi 1.1.0 would
277
+ // DSH permits only off:null: it means supported-off by omitting the wire option. Pi (1.3.0) would
193
278
  // read an absent `off` as "send none", so the omission is made explicit here.
194
279
  thinkingLevelMap[level] = null;
195
280
  if (level === "off")
@@ -217,7 +302,7 @@ function isLcxCapabilityRoute(provider, model) {
217
302
  /^gpt-5\.6-(?:sol|luna|terra)$/iu.test(model);
218
303
  }
219
304
  /** Resolve only the selected DSH profile; policy cannot supply route identity or credentials. */
220
- export function resolveResponsesRouteConfig(ctx, options, policy) {
305
+ export function resolveResponsesRouteConfig(ctx, options, policy, assumeHostServes = false) {
221
306
  const provider = String(options?.provider ?? "");
222
307
  const model = String(options?.model ?? "");
223
308
  if (!provider.trim() || !/^gpt-/iu.test(model))
@@ -227,11 +312,15 @@ export function resolveResponsesRouteConfig(ctx, options, policy) {
227
312
  if (!isRecord(profile))
228
313
  return undefined;
229
314
  const configured = profile;
230
- const builtin = builtinResponsesModel(provider, model);
231
- const api = configured.api ?? builtin?.api;
315
+ if (profileExcludesModel(configured, model) || usesHostProviderAuth(provider))
316
+ return undefined;
317
+ // Protocol and endpoint: the profile, then what DSH resolves for the model (see `resolveCatalogModel`).
318
+ const catalog = resolveCatalogModel(provider, model, dshServesModel(ctx, configured, provider, model, assumeHostServes));
319
+ const builtin = catalog.descriptor;
320
+ const api = configured.api ?? catalog.api;
232
321
  if (api !== "openai-responses")
233
322
  return undefined;
234
- const baseURL = configured.baseURL ?? builtin?.baseUrl;
323
+ const baseURL = configured.baseURL ?? catalog.baseUrl;
235
324
  const apiKeyEnv = configured.apiKeyEnv;
236
325
  if (typeof baseURL !== "string" || !normalizeBaseURL(baseURL) || typeof apiKeyEnv !== "string" || !apiKeyEnv.trim())
237
326
  return undefined;
@@ -239,7 +328,7 @@ export function resolveResponsesRouteConfig(ctx, options, policy) {
239
328
  copyResponsesCompat(responsesCompat, builtin?.compat);
240
329
  copyResponsesCompat(responsesCompat, lcxCapabilityRoute ? policy.responsesCompat : undefined);
241
330
  copyResponsesCompat(responsesCompat, configuredResponsesCompat(configured, model));
242
- const promptCacheModel = lcxCapabilityRoute && policy.supportsExplicitPromptCacheMode === true ? builtinResponsesModel("openai", model) : undefined;
331
+ const promptCacheModel = lcxCapabilityRoute && policy.supportsExplicitPromptCacheMode === true ? resolveCatalogModel("openai", model).descriptor : undefined;
243
332
  const promptCacheRaw = promptCacheModel;
244
333
  const promptCacheCompat = isRecord(promptCacheRaw)
245
334
  ? promptCacheRaw.compat
@@ -262,21 +351,41 @@ export function resolveResponsesRouteConfig(ctx, options, policy) {
262
351
  api: "openai-responses",
263
352
  baseURL: normalizeBaseURL(baseURL),
264
353
  apiKeyEnv,
354
+ ...(builtin?.headers === undefined ? {} : { catalogHeaders: { ...builtin.headers } }),
265
355
  headers: { ...(configured.headers ?? {}) },
266
356
  cacheRetention,
267
357
  supportsLongCacheRetention,
268
358
  responsesCompat,
269
359
  // Only a declared `reasoningEfforts` is projected here; an undeclared model follows the catalog
270
- // and what DSH resolved for it (see `gptModelOverride`).
360
+ // and what DSH resolved for it (see `routeModelOverride`).
271
361
  ...(declaredControls === undefined ? {} : { modelControls: declaredControls }),
272
362
  // These are explicitly LCX-owned transport and request-capability policies.
273
- timeoutMs: isPositiveInteger(configured.timeoutMs) ? configured.timeoutMs : policy.timeoutMs,
363
+ timeoutMs: isPositiveSafeInteger(configured.timeoutMs) ? configured.timeoutMs : policy.timeoutMs,
274
364
  maxAttempts: retryAttempts(configured.retryPolicy, policy.maxAttempts),
275
- maxRequestImageBytes: isPositiveInteger(configured.maxRequestImageBytes) ? configured.maxRequestImageBytes : policy.maxRequestImageBytes,
276
- requestImagePixelBudget: isPositiveInteger(configured.requestImagePixelBudget) ? configured.requestImagePixelBudget : policy.requestImagePixelBudget,
277
- requestImageMaxBytes: isPositiveInteger(configured.requestImageMaxBytes) ? configured.requestImageMaxBytes : policy.requestImageMaxBytes,
365
+ maxRequestImageBytes: isPositiveSafeInteger(configured.maxRequestImageBytes) ? configured.maxRequestImageBytes : policy.maxRequestImageBytes,
366
+ requestImagePixelBudget: isPositiveSafeInteger(configured.requestImagePixelBudget) ? configured.requestImagePixelBudget : policy.requestImagePixelBudget,
367
+ requestImageMaxBytes: isPositiveSafeInteger(configured.requestImageMaxBytes) ? configured.requestImageMaxBytes : policy.requestImageMaxBytes,
278
368
  };
279
369
  }
370
+ /**
371
+ * Name the reason `resolveResponsesRouteConfig` returned nothing, so the failure can tell the user what to
372
+ * change: `api-unresolved` means neither the profile nor the model catalog names a protocol for this model.
373
+ */
374
+ export function diagnoseResponsesRoute(ctx, options) {
375
+ const provider = String(options?.provider ?? "");
376
+ const model = String(options?.model ?? "");
377
+ const profile = provider.trim() ? configuredProviderProfile(ctx, provider) : undefined;
378
+ if (!isRecord(profile))
379
+ return "no-profile";
380
+ if (profileExcludesModel(profile, model))
381
+ return "model-not-configured";
382
+ if (usesHostProviderAuth(provider))
383
+ return "host-auth";
384
+ const api = profile.api ?? resolveCatalogModel(provider, model, dshServesModel(ctx, profile, provider, model)).api;
385
+ if (api === undefined)
386
+ return "api-unresolved";
387
+ return api === "openai-responses" ? "incomplete" : "api-not-responses";
388
+ }
280
389
  /** Resolve a Grok-prefixed model through its selected DSH Responses profile. */
281
390
  export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
282
391
  const provider = String(options?.provider ?? "");
@@ -286,11 +395,14 @@ export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
286
395
  const configured = configuredProviderProfile(ctx, provider);
287
396
  if (!isRecord(configured))
288
397
  return undefined;
289
- const selectedBuiltin = builtinResponsesModel(provider, model);
290
- const api = configured.api ?? selectedBuiltin?.api;
398
+ if (profileExcludesModel(configured, model) || usesHostProviderAuth(provider))
399
+ return undefined;
400
+ const catalog = resolveCatalogModel(provider, model, dshServesModel(ctx, configured, provider, model));
401
+ const selectedBuiltin = catalog.descriptor;
402
+ const api = configured.api ?? catalog.api;
291
403
  if (api !== "openai-responses")
292
404
  return undefined;
293
- const baseURL = configured.baseURL ?? selectedBuiltin?.baseUrl;
405
+ const baseURL = configured.baseURL ?? catalog.baseUrl;
294
406
  const apiKeyEnv = configured.apiKeyEnv;
295
407
  if (typeof baseURL !== "string" ||
296
408
  !normalizeBaseURL(baseURL) ||
@@ -314,6 +426,7 @@ export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
314
426
  api: "openai-responses",
315
427
  baseURL: normalizeBaseURL(baseURL),
316
428
  apiKeyEnv,
429
+ ...(selectedBuiltin?.headers === undefined ? {} : { catalogHeaders: { ...selectedBuiltin.headers } }),
317
430
  headers: effectiveGrokProfileHeaders(configured.headers),
318
431
  cacheRetention,
319
432
  supportsLongCacheRetention,
@@ -326,32 +439,31 @@ export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
326
439
  profileReasoning: profileReasoning(configured.reasoning),
327
440
  // Pi applies only an explicitly configured request deadline; stream liveness
328
441
  // is owned separately by the provider idle watchdog.
329
- timeoutMs: isPositiveInteger(configured.timeoutMs)
442
+ timeoutMs: isPositiveSafeInteger(configured.timeoutMs)
330
443
  ? configured.timeoutMs
331
444
  : undefined,
332
445
  streamIdleTimeoutMs: isPositiveFinite(configured.streamIdleTimeoutMs)
333
446
  ? configured.streamIdleTimeoutMs
334
- : 300_000,
447
+ : DEFAULTS.streamIdleTimeoutMs,
335
448
  maxAttempts: retryAttempts(configured.retryPolicy, policy.maxAttempts),
336
- maxRequestImageBytes: isPositiveInteger(configured.maxRequestImageBytes)
449
+ maxRequestImageBytes: isPositiveSafeInteger(configured.maxRequestImageBytes)
337
450
  ? configured.maxRequestImageBytes
338
451
  : policy.maxRequestImageBytes,
339
- requestImagePixelBudget: isPositiveInteger(configured.requestImagePixelBudget)
452
+ requestImagePixelBudget: isPositiveSafeInteger(configured.requestImagePixelBudget)
340
453
  ? configured.requestImagePixelBudget
341
454
  : policy.requestImagePixelBudget,
342
- requestImageMaxBytes: isPositiveInteger(configured.requestImageMaxBytes)
455
+ requestImageMaxBytes: isPositiveSafeInteger(configured.requestImageMaxBytes)
343
456
  ? configured.requestImageMaxBytes
344
457
  : policy.requestImageMaxBytes,
345
458
  };
346
459
  }
347
- /** @param {RouteContext | null | undefined} ctx @param {Pick<ResolvedResponsesRoute, 'apiKeyEnv'>} config */
348
460
  export async function resolveApiKey(ctx, config) {
349
461
  const resolved = await ctx?.credentials.resolve(credentialRef(config.apiKeyEnv));
462
+ // DSH's own definition of a usable key (trimmed, nothing an HTTP header cannot carry). A rejected key is
463
+ // reported by its reference only, never by its value.
350
464
  if (resolved?.value.trim())
351
- return resolved.value.trim();
352
- const error = new Error(`DSH provider credential is unavailable: ${config.apiKeyEnv}`);
353
- error.code = "LCX_CREDENTIAL_UNAVAILABLE";
354
- throw error;
465
+ return assertUsableApiKey(resolved.value, "lcx-codex", config.apiKeyEnv);
466
+ throw codedError(`DSH provider credential is unavailable: ${config.apiKeyEnv}`, "LCX_CREDENTIAL_UNAVAILABLE");
355
467
  }
356
468
  function setHeaderCaseInsensitive(headers, name, value) {
357
469
  const normalized = name.toLowerCase();
@@ -360,6 +472,14 @@ function setHeaderCaseInsensitive(headers, name, value) {
360
472
  delete headers[existing];
361
473
  headers[name] = value;
362
474
  }
475
+ /** Layer header maps, later ones replacing earlier ones whatever the header name's case. */
476
+ function layerHeaders(...layers) {
477
+ const result = {};
478
+ for (const layer of layers)
479
+ for (const [name, value] of Object.entries(layer ?? {}))
480
+ setHeaderCaseInsensitive(result, name, value);
481
+ return result;
482
+ }
363
483
  /** Apply DSH's case-insensitive attribution reservation at profile resolution. */
364
484
  function effectiveGrokProfileHeaders(configured) {
365
485
  const attribution = attributionHeaders();
@@ -370,11 +490,8 @@ function effectiveGrokProfileHeaders(configured) {
370
490
  setHeaderCaseInsensitive(effective, name, value);
371
491
  return effective;
372
492
  }
373
- /** @param {HeaderMap | null | undefined} headers @param {string} name */
374
493
  function hasHeader(headers, name) { return Object.keys(headers ?? {}).some((key) => key.toLowerCase() === name.toLowerCase()); }
375
- /** @param {HeaderMap | null | undefined} headers */
376
494
  function hasExplicitSessionAffinity(headers) { return ["session-id", "session_id", "x-session-id"].some((name) => hasHeader(headers, name)); }
377
- /** @param {Partial<ResolvedResponsesRoute> | null | undefined} config */
378
495
  function sessionAffinityFormat(config) {
379
496
  if (config?.api && config.api !== "openai-responses")
380
497
  return "none";
@@ -386,15 +503,18 @@ function sessionAffinityFormat(config) {
386
503
  ? "openrouter"
387
504
  : "openai";
388
505
  }
389
- /** @param {RouteContext | null | undefined} ctx @param {ResolvedResponsesRoute} config @param {unknown} sessionId @param {string | null | undefined} requestId @returns {Promise<HeaderMap>} */
390
- export async function authenticatedHeaders(ctx, config, sessionId, requestId) {
506
+ /**
507
+ * The headers of one GPT request. `sessionId` is the prompt-cache / affinity session (the root session for a
508
+ * subagent, absent without cache retention); `providerSessionId` is the CURRENT DSH session, which is what Pi's
509
+ * client sends in provider routing headers (`x-opencode-session`) whatever the cache policy is.
510
+ */
511
+ export async function authenticatedHeaders(ctx, config, sessionId, requestId, dynamicHeaders = {}, providerSessionId) {
391
512
  const explicit = { ...(config.headers ?? {}) };
392
- const headers = {
393
- ...attributionHeaders(),
394
- authorization: `Bearer ${await resolveApiKey(ctx, config)}`,
395
- };
396
513
  const sid = sessionId ? String(sessionId) : undefined;
397
514
  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));
398
518
  if (sid && !hasExplicitSessionAffinity(explicit)) {
399
519
  if (format === "openai")
400
520
  headers.session_id = sid;
@@ -406,15 +526,17 @@ export async function authenticatedHeaders(ctx, config, sessionId, requestId) {
406
526
  if (correlation)
407
527
  headers["x-client-request-id"] = correlation;
408
528
  }
409
- return { ...headers, ...explicit };
529
+ // The profile's own headers win over every default.
530
+ return layerHeaders(headers, explicit);
410
531
  }
411
532
  /** Grok mirrors Pi createClient ordering without changing accepted GPT headers. */
412
- export async function authenticatedGrokHeaders(ctx, config, sessionId) {
533
+ export async function authenticatedGrokHeaders(ctx, config, sessionId, dynamicHeaders = {}, providerSessionId) {
413
534
  const explicit = effectiveGrokProfileHeaders(config.headers);
414
- const headers = {
415
- authorization: `Bearer ${await resolveApiKey(ctx, config)}`,
416
- };
417
535
  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));
418
540
  const format = sessionAffinityFormat(config);
419
541
  if (sid) {
420
542
  if (format === "openai")
@@ -430,11 +552,9 @@ export async function authenticatedGrokHeaders(ctx, config, sessionId) {
430
552
  setHeaderCaseInsensitive(headers, name, value);
431
553
  return headers;
432
554
  }
433
- /** @param {RouteOptions | null | undefined} options @param {Pick<UnresolvedRouteConfig, 'provider' | 'model' | 'baseURL'>} config @returns {RouteIdentity} */
434
555
  export function currentRoute(options, config) {
435
556
  return { provider: String(options?.provider ?? config.provider ?? ""), model: String(options?.model ?? config.model ?? ""), baseURL: normalizeBaseURL(config.baseURL), sessionId: String(options?.sessionId ?? "") };
436
557
  }
437
- /** @param {RequestHeader | null | undefined} header @param {Partial<RouteIdentity> | null | undefined} route @returns {GenerationControls} */
438
558
  export function generationControlsFromHeader(header, route) {
439
559
  const config = header?.config;
440
560
  if (!config || String(config.provider ?? "") !== String(route?.provider ?? "") || String(config.model ?? "") !== String(route?.model ?? ""))
@@ -448,7 +568,6 @@ export function generationControlsFromHeader(header, route) {
448
568
  controls.maxTokens = config.maxTokens;
449
569
  return controls;
450
570
  }
451
- /** @param {RouteSession | null | undefined} session @param {Partial<RouteIdentity> | null | undefined} route @returns {GenerationControls} */
452
571
  export function generationControlsFromSession(session, route) {
453
572
  try {
454
573
  return generationControlsFromHeader(session?.requestHeader?.(), route);
@@ -457,7 +576,6 @@ export function generationControlsFromSession(session, route) {
457
576
  return {};
458
577
  }
459
578
  }
460
- /** @param {CheckpointRouteRecord | null | undefined} record @param {RouteIdentity} route @param {unknown} ctx */
461
579
  export function routeCompatible(record, route, ctx) {
462
580
  void ctx;
463
581
  return !!record && record.version === 5 && record.provider === route.provider && record.model === route.model && record.baseURLFingerprint === baseURLFingerprint(route.baseURL) && record.sourceSessionId === route.sessionId;
@@ -15,7 +15,7 @@ export const NESTED_SETTLE_EVENT = 'tool/ptc-dispatch';
15
15
  * model-direct call settles as `tool/result` (its name comes from the earlier `tool/call`); a nested call settles
16
16
  * as `tool/ptc-dispatch`, whose `name`, `subCallId` and `meta` are its own fields.
17
17
  */
18
- export function searchSettlementOf(event, pendingName) {
18
+ function searchSettlementOf(event, pendingName) {
19
19
  if (!object(event) || !object(event.data) || !object(event.data.meta))
20
20
  return;
21
21
  // Official ToolMessageSource carries only callId; a direct result resolves its name from tool/call.
@@ -71,21 +71,6 @@ export function mergeBuckets(base, extra) {
71
71
  }
72
72
  return next;
73
73
  }
74
- export function addTurnUsage(base, records) {
75
- if (!object(base) || !records.length || !count(base.totalTokens))
76
- return base;
77
- const next = mergeBuckets(base, addUsage(zeroBuckets(), records));
78
- next.totalTokens = base.totalTokens + records.reduce((n, r) => n + r.usage.totalTokens, 0);
79
- // Auxiliary responses do not always disclose a reasoning subset.
80
- delete next.reasoningTokens;
81
- if (Array.isArray(base.routes)) {
82
- const routes = new Map();
83
- for (const r of [...base.routes, ...records])
84
- routes.set(`${r.provider}\0${r.model}`, { provider: r.provider, model: r.model });
85
- next.routes = [...routes.values()];
86
- }
87
- return next;
88
- }
89
74
  /** The metadata is presentation/accounting state; it never changes request messages. */
90
75
  export function aggregateContextOf(event) {
91
76
  const mark = contextMarkerOf(event);
@@ -4,10 +4,16 @@ import { addUsage, aggregateContextOf, auxiliaryUsageOf, isSearchTool, providerC
4
4
  const n = z.number().int().nonnegative();
5
5
  const schema = z.object({ auxiliary: z.object({ uncachedInputTokens: n, outputTokens: n, cacheReadTokens: n, cacheWriteTokens: n }).strict(), aggregateContext: z.boolean(),
6
6
  contextDetails: z.object({ input_tokens: n, output_tokens: n }).strict().optional(), contextProvenance: z.literal('provider-context-details').optional() }).strict();
7
+ const stateSchema = schema.extend({ pending: z.record(z.string(), z.string()), headerKey: z.string().optional(), sampleHeaderKey: z.string().optional() });
8
+ // DSH (since 0.2.1-alpha.5) pins its own zod, which need not be the one this plugin resolves, and TypeScript
9
+ // cannot relate schemas of two zod copies. The host only calls `parse` on them, so they are checked against
10
+ // the plugin's zod here and handed to the host typed by its own contract.
11
+ const hostStateSchema = stateSchema;
12
+ const hostViewSchema = schema;
7
13
  const headerKey = (header) => header === undefined ? undefined : JSON.stringify(canonicalHeader(header));
8
14
  /** Separate, durable extension: the host's own usage projection remains primary-call billing. */
9
15
  export const searchUsageProjection = {
10
- key: 'lcxSearchUsage', stateVersion: 3, stateSchema: schema.extend({ pending: z.record(z.string(), z.string()), headerKey: z.string().optional(), sampleHeaderKey: z.string().optional() }),
16
+ key: 'lcxSearchUsage', stateVersion: 3, stateSchema: hostStateSchema,
11
17
  init: () => ({ auxiliary: zeroBuckets(), aggregateContext: false, pending: {} }),
12
18
  apply(state, event) {
13
19
  // Unit state is checkpointed by the host's projection cache, which refuses any state that is not
@@ -41,7 +47,7 @@ export const searchUsageProjection = {
41
47
  return { ...state, auxiliary, aggregateContext, pending: {} };
42
48
  return auxiliary === state.auxiliary && aggregateContext === state.aggregateContext ? state : { ...state, auxiliary, aggregateContext };
43
49
  },
44
- wire: { viewSchema: schema, view: ({ auxiliary, aggregateContext, contextDetails, contextProvenance }) => ({ auxiliary, aggregateContext, ...(contextDetails ? { contextDetails, contextProvenance } : {}) }) },
50
+ wire: { viewSchema: hostViewSchema, view: ({ auxiliary, aggregateContext, contextDetails, contextProvenance }) => ({ auxiliary, aggregateContext, ...(contextDetails ? { contextDetails, contextProvenance } : {}) }) },
45
51
  };
46
52
  const installed = new WeakMap();
47
53
  /** Own a reversible adapter on the public measure method, never a DSH file or private fold. */