dsh-lcx-codex 0.5.2 → 0.6.0-pre.2

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,42 +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";
5
+ import { assertUsableApiKey, attributionHeaders, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
6
6
  import { resolveCatalogModel } from "./model-catalog.js";
7
- /** @param {unknown} value */
8
- function isRecord(value) {
9
- return value !== null && typeof value === "object" && !Array.isArray(value);
10
- }
11
- /** @param {unknown} value */
12
- function isPositiveInteger(value) {
13
- return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
14
- }
15
- function isPositiveFinite(value) {
16
- return typeof value === "number" && Number.isFinite(value) && value > 0;
17
- }
18
- /** @param {unknown} value */
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";
19
11
  export function normalizeBaseURL(value) {
20
12
  return String(value ?? "").trim().replace(/\/+$/u, "");
21
13
  }
22
- /** @param {unknown} baseURL */
23
14
  export function baseURLFingerprint(baseURL) {
24
15
  return createHash("sha256").update(normalizeBaseURL(baseURL), "utf8").digest("hex");
25
16
  }
26
- /** @param {Partial<RouteIdentity> | null | undefined} route @param {{ includeSession?: boolean }} [options] */
27
17
  export function routeFingerprint(route, options = {}) {
28
18
  const includeSession = options.includeSession !== false;
29
19
  return createHash("sha256").update([
30
20
  route?.provider ?? "", route?.model ?? "", normalizeBaseURL(route?.baseURL), includeSession ? (route?.sessionId ?? "") : "",
31
21
  ].join("\u001f"), "utf8").digest("hex");
32
22
  }
33
- /** @param {unknown} value */
34
- function clampPromptCacheKey(value) {
35
- if (value === undefined)
36
- return undefined;
37
- const chars = Array.from(String(value));
38
- return chars.length <= 64 ? String(value) : chars.slice(0, 64).join("");
39
- }
40
- /** @param {Partial<RouteIdentity> | null | undefined} route @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention'>>} [config] @param {RouteContext | null | undefined} [ctx] */
41
23
  export function promptCacheSessionId(route, config = {}, ctx = undefined) {
42
24
  if (config.cacheRetention === "none")
43
25
  return undefined;
@@ -61,9 +43,8 @@ export function promptCacheSessionId(route, config = {}, ctx = undefined) {
61
43
  }
62
44
  return current?.id ?? sessionId;
63
45
  }
64
- /** @param {Partial<RouteIdentity> | null | undefined} route @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention'>>} [config] @param {RouteContext | null | undefined} [ctx] */
65
46
  export function promptCacheKey(route, config = {}, ctx = undefined) {
66
- return clampPromptCacheKey(promptCacheSessionId(route, config, ctx));
47
+ return clampOpenAIPromptCacheKey(promptCacheSessionId(route, config, ctx));
67
48
  }
68
49
  /** Grok follows Pi directly: cache/affinity belongs to the selected child session. */
69
50
  export function grokPromptCacheSessionId(route, config = {}) {
@@ -72,18 +53,16 @@ export function grokPromptCacheSessionId(route, config = {}) {
72
53
  const sessionId = String(route?.sessionId ?? "");
73
54
  return sessionId || undefined;
74
55
  }
75
- /** @param {Partial<Pick<ResolvedResponsesRoute, 'cacheRetention' | 'supportsLongCacheRetention' | 'responsesCompat'>>} [config] */
76
56
  export function promptCacheRetention(config = {}) {
77
57
  return config.cacheRetention === "long" && config.supportsLongCacheRetention === true && config.responsesCompat?.supportsExplicitPromptCacheMode !== true ? "24h" : undefined;
78
58
  }
79
- /** @param {RetryPolicyConfig | null | undefined} policy @param {number} [fallback] */
80
- function retryAttempts(policy, fallback = 3) {
59
+ function retryAttempts(policy, fallback = DEFAULTS.maxAttempts) {
81
60
  if (!policy)
82
61
  return fallback;
83
62
  try {
84
63
  const resolved = resolveRetryPolicy(policy, "llm-pi-ai provider retryPolicy");
85
- if (resolved.mode === "normal" && isPositiveInteger(resolved.maxRetries))
86
- return Math.min(resolved.maxRetries + 1, 6);
64
+ if (resolved.mode === "normal" && isPositiveSafeInteger(resolved.maxRetries))
65
+ return Math.min(resolved.maxRetries + 1, DEFAULTS.maxAttemptsCap);
87
66
  }
88
67
  catch { }
89
68
  return fallback;
@@ -108,9 +87,7 @@ function configuredProviderProfile(ctx, provider) {
108
87
  return undefined;
109
88
  }
110
89
  }
111
- /** @type {Set<keyof ResponsesCompat>} */
112
90
  const RESPONSES_COMPAT_FIELDS = new Set(["supportsDeveloperRole", "sessionAffinityFormat", "supportsStrictMode", "supportsLongCacheRetention", "supportsOpenAIGrammarTools", "supportsAdditionalTools", "supportsToolSearch", "supportsExplicitPromptCacheMode", "supportsMaxOutputTokens"]);
113
- /** @param {ResponsesCompat} target @param {unknown} source */
114
91
  function copyResponsesCompat(target, source) {
115
92
  if (!isRecord(source))
116
93
  return;
@@ -132,9 +109,100 @@ function modelDescriptorDefaults(model) {
132
109
  thinkingLevelMap: model.thinkingLevelMap,
133
110
  };
134
111
  }
135
- /** The profile lists this model in `models`: the one way DSH serves a model its catalog does not describe. */
136
- function profileDeclaresModel(profile, modelId) {
137
- return Array.isArray(profile?.models) && profile.models.some((entry) => String(entry?.id ?? "") === String(modelId));
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));
138
206
  }
139
207
  /**
140
208
  * A nonempty `models` list replaces the served catalog: DSH serves exactly the listed models, and LCX answers
@@ -144,13 +212,30 @@ function profileExcludesModel(profile, modelId) {
144
212
  return Array.isArray(profile?.models) && profile.models.length > 0 &&
145
213
  !profile.models.some((entry) => String(entry?.id ?? "") === String(modelId));
146
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);
@@ -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,10 +312,10 @@ export function resolveResponsesRouteConfig(ctx, options, policy) {
227
312
  if (!isRecord(profile))
228
313
  return undefined;
229
314
  const configured = profile;
230
- if (profileExcludesModel(configured, model))
315
+ if (profileExcludesModel(configured, model) || usesHostProviderAuth(provider))
231
316
  return undefined;
232
317
  // Protocol and endpoint: the profile, then what DSH resolves for the model (see `resolveCatalogModel`).
233
- const catalog = resolveCatalogModel(provider, model, profileDeclaresModel(configured, model));
318
+ const catalog = resolveCatalogModel(provider, model, dshServesModel(ctx, configured, provider, model, assumeHostServes));
234
319
  const builtin = catalog.descriptor;
235
320
  const api = configured.api ?? catalog.api;
236
321
  if (api !== "openai-responses")
@@ -266,19 +351,20 @@ export function resolveResponsesRouteConfig(ctx, options, policy) {
266
351
  api: "openai-responses",
267
352
  baseURL: normalizeBaseURL(baseURL),
268
353
  apiKeyEnv,
354
+ ...(builtin?.headers === undefined ? {} : { catalogHeaders: { ...builtin.headers } }),
269
355
  headers: { ...(configured.headers ?? {}) },
270
356
  cacheRetention,
271
357
  supportsLongCacheRetention,
272
358
  responsesCompat,
273
359
  // Only a declared `reasoningEfforts` is projected here; an undeclared model follows the catalog
274
- // and what DSH resolved for it (see `gptModelOverride`).
360
+ // and what DSH resolved for it (see `routeModelOverride`).
275
361
  ...(declaredControls === undefined ? {} : { modelControls: declaredControls }),
276
362
  // These are explicitly LCX-owned transport and request-capability policies.
277
- timeoutMs: isPositiveInteger(configured.timeoutMs) ? configured.timeoutMs : policy.timeoutMs,
363
+ timeoutMs: isPositiveSafeInteger(configured.timeoutMs) ? configured.timeoutMs : policy.timeoutMs,
278
364
  maxAttempts: retryAttempts(configured.retryPolicy, policy.maxAttempts),
279
- maxRequestImageBytes: isPositiveInteger(configured.maxRequestImageBytes) ? configured.maxRequestImageBytes : policy.maxRequestImageBytes,
280
- requestImagePixelBudget: isPositiveInteger(configured.requestImagePixelBudget) ? configured.requestImagePixelBudget : policy.requestImagePixelBudget,
281
- 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,
282
368
  };
283
369
  }
284
370
  /**
@@ -293,7 +379,9 @@ export function diagnoseResponsesRoute(ctx, options) {
293
379
  return "no-profile";
294
380
  if (profileExcludesModel(profile, model))
295
381
  return "model-not-configured";
296
- const api = profile.api ?? resolveCatalogModel(provider, model, profileDeclaresModel(profile, model)).api;
382
+ if (usesHostProviderAuth(provider))
383
+ return "host-auth";
384
+ const api = profile.api ?? resolveCatalogModel(provider, model, dshServesModel(ctx, profile, provider, model)).api;
297
385
  if (api === undefined)
298
386
  return "api-unresolved";
299
387
  return api === "openai-responses" ? "incomplete" : "api-not-responses";
@@ -307,9 +395,9 @@ export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
307
395
  const configured = configuredProviderProfile(ctx, provider);
308
396
  if (!isRecord(configured))
309
397
  return undefined;
310
- if (profileExcludesModel(configured, model))
398
+ if (profileExcludesModel(configured, model) || usesHostProviderAuth(provider))
311
399
  return undefined;
312
- const catalog = resolveCatalogModel(provider, model, profileDeclaresModel(configured, model));
400
+ const catalog = resolveCatalogModel(provider, model, dshServesModel(ctx, configured, provider, model));
313
401
  const selectedBuiltin = catalog.descriptor;
314
402
  const api = configured.api ?? catalog.api;
315
403
  if (api !== "openai-responses")
@@ -338,6 +426,7 @@ export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
338
426
  api: "openai-responses",
339
427
  baseURL: normalizeBaseURL(baseURL),
340
428
  apiKeyEnv,
429
+ ...(selectedBuiltin?.headers === undefined ? {} : { catalogHeaders: { ...selectedBuiltin.headers } }),
341
430
  headers: effectiveGrokProfileHeaders(configured.headers),
342
431
  cacheRetention,
343
432
  supportsLongCacheRetention,
@@ -350,32 +439,31 @@ export function resolveGrokResponsesRouteConfig(ctx, options, policy) {
350
439
  profileReasoning: profileReasoning(configured.reasoning),
351
440
  // Pi applies only an explicitly configured request deadline; stream liveness
352
441
  // is owned separately by the provider idle watchdog.
353
- timeoutMs: isPositiveInteger(configured.timeoutMs)
442
+ timeoutMs: isPositiveSafeInteger(configured.timeoutMs)
354
443
  ? configured.timeoutMs
355
444
  : undefined,
356
445
  streamIdleTimeoutMs: isPositiveFinite(configured.streamIdleTimeoutMs)
357
446
  ? configured.streamIdleTimeoutMs
358
- : 300_000,
447
+ : DEFAULTS.streamIdleTimeoutMs,
359
448
  maxAttempts: retryAttempts(configured.retryPolicy, policy.maxAttempts),
360
- maxRequestImageBytes: isPositiveInteger(configured.maxRequestImageBytes)
449
+ maxRequestImageBytes: isPositiveSafeInteger(configured.maxRequestImageBytes)
361
450
  ? configured.maxRequestImageBytes
362
451
  : policy.maxRequestImageBytes,
363
- requestImagePixelBudget: isPositiveInteger(configured.requestImagePixelBudget)
452
+ requestImagePixelBudget: isPositiveSafeInteger(configured.requestImagePixelBudget)
364
453
  ? configured.requestImagePixelBudget
365
454
  : policy.requestImagePixelBudget,
366
- requestImageMaxBytes: isPositiveInteger(configured.requestImageMaxBytes)
455
+ requestImageMaxBytes: isPositiveSafeInteger(configured.requestImageMaxBytes)
367
456
  ? configured.requestImageMaxBytes
368
457
  : policy.requestImageMaxBytes,
369
458
  };
370
459
  }
371
- /** @param {RouteContext | null | undefined} ctx @param {Pick<ResolvedResponsesRoute, 'apiKeyEnv'>} config */
372
460
  export async function resolveApiKey(ctx, config) {
373
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.
374
464
  if (resolved?.value.trim())
375
- return resolved.value.trim();
376
- const error = new Error(`DSH provider credential is unavailable: ${config.apiKeyEnv}`);
377
- error.code = "LCX_CREDENTIAL_UNAVAILABLE";
378
- throw error;
465
+ return assertUsableApiKey(resolved.value, "lcx-codex", config.apiKeyEnv);
466
+ throw codedError(`DSH provider credential is unavailable: ${config.apiKeyEnv}`, "LCX_CREDENTIAL_UNAVAILABLE");
379
467
  }
380
468
  function setHeaderCaseInsensitive(headers, name, value) {
381
469
  const normalized = name.toLowerCase();
@@ -384,6 +472,14 @@ function setHeaderCaseInsensitive(headers, name, value) {
384
472
  delete headers[existing];
385
473
  headers[name] = value;
386
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
+ }
387
483
  /** Apply DSH's case-insensitive attribution reservation at profile resolution. */
388
484
  function effectiveGrokProfileHeaders(configured) {
389
485
  const attribution = attributionHeaders();
@@ -394,11 +490,8 @@ function effectiveGrokProfileHeaders(configured) {
394
490
  setHeaderCaseInsensitive(effective, name, value);
395
491
  return effective;
396
492
  }
397
- /** @param {HeaderMap | null | undefined} headers @param {string} name */
398
493
  function hasHeader(headers, name) { return Object.keys(headers ?? {}).some((key) => key.toLowerCase() === name.toLowerCase()); }
399
- /** @param {HeaderMap | null | undefined} headers */
400
494
  function hasExplicitSessionAffinity(headers) { return ["session-id", "session_id", "x-session-id"].some((name) => hasHeader(headers, name)); }
401
- /** @param {Partial<ResolvedResponsesRoute> | null | undefined} config */
402
495
  function sessionAffinityFormat(config) {
403
496
  if (config?.api && config.api !== "openai-responses")
404
497
  return "none";
@@ -410,15 +503,18 @@ function sessionAffinityFormat(config) {
410
503
  ? "openrouter"
411
504
  : "openai";
412
505
  }
413
- /** @param {RouteContext | null | undefined} ctx @param {ResolvedResponsesRoute} config @param {unknown} sessionId @param {string | null | undefined} requestId @returns {Promise<HeaderMap>} */
414
- 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) {
415
512
  const explicit = { ...(config.headers ?? {}) };
416
- const headers = {
417
- ...attributionHeaders(),
418
- authorization: `Bearer ${await resolveApiKey(ctx, config)}`,
419
- };
420
513
  const sid = sessionId ? String(sessionId) : undefined;
421
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));
422
518
  if (sid && !hasExplicitSessionAffinity(explicit)) {
423
519
  if (format === "openai")
424
520
  headers.session_id = sid;
@@ -430,15 +526,17 @@ export async function authenticatedHeaders(ctx, config, sessionId, requestId) {
430
526
  if (correlation)
431
527
  headers["x-client-request-id"] = correlation;
432
528
  }
433
- return { ...headers, ...explicit };
529
+ // The profile's own headers win over every default.
530
+ return layerHeaders(headers, explicit);
434
531
  }
435
532
  /** Grok mirrors Pi createClient ordering without changing accepted GPT headers. */
436
- export async function authenticatedGrokHeaders(ctx, config, sessionId) {
533
+ export async function authenticatedGrokHeaders(ctx, config, sessionId, dynamicHeaders = {}, providerSessionId) {
437
534
  const explicit = effectiveGrokProfileHeaders(config.headers);
438
- const headers = {
439
- authorization: `Bearer ${await resolveApiKey(ctx, config)}`,
440
- };
441
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));
442
540
  const format = sessionAffinityFormat(config);
443
541
  if (sid) {
444
542
  if (format === "openai")
@@ -454,11 +552,9 @@ export async function authenticatedGrokHeaders(ctx, config, sessionId) {
454
552
  setHeaderCaseInsensitive(headers, name, value);
455
553
  return headers;
456
554
  }
457
- /** @param {RouteOptions | null | undefined} options @param {Pick<UnresolvedRouteConfig, 'provider' | 'model' | 'baseURL'>} config @returns {RouteIdentity} */
458
555
  export function currentRoute(options, config) {
459
556
  return { provider: String(options?.provider ?? config.provider ?? ""), model: String(options?.model ?? config.model ?? ""), baseURL: normalizeBaseURL(config.baseURL), sessionId: String(options?.sessionId ?? "") };
460
557
  }
461
- /** @param {RequestHeader | null | undefined} header @param {Partial<RouteIdentity> | null | undefined} route @returns {GenerationControls} */
462
558
  export function generationControlsFromHeader(header, route) {
463
559
  const config = header?.config;
464
560
  if (!config || String(config.provider ?? "") !== String(route?.provider ?? "") || String(config.model ?? "") !== String(route?.model ?? ""))
@@ -472,7 +568,6 @@ export function generationControlsFromHeader(header, route) {
472
568
  controls.maxTokens = config.maxTokens;
473
569
  return controls;
474
570
  }
475
- /** @param {RouteSession | null | undefined} session @param {Partial<RouteIdentity> | null | undefined} route @returns {GenerationControls} */
476
571
  export function generationControlsFromSession(session, route) {
477
572
  try {
478
573
  return generationControlsFromHeader(session?.requestHeader?.(), route);
@@ -481,7 +576,6 @@ export function generationControlsFromSession(session, route) {
481
576
  return {};
482
577
  }
483
578
  }
484
- /** @param {CheckpointRouteRecord | null | undefined} record @param {RouteIdentity} route @param {unknown} ctx */
485
579
  export function routeCompatible(record, route, ctx) {
486
580
  void ctx;
487
581
  return !!record && record.version === 5 && record.provider === route.provider && record.model === route.model && record.baseURLFingerprint === baseURLFingerprint(route.baseURL) && record.sourceSessionId === route.sessionId;
@@ -8,14 +8,27 @@ export function sanitizeContextDetails(value) {
8
8
  }
9
9
  export const zeroBuckets = () => ({ uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 });
10
10
  export const isSearchTool = (name) => name === 'web_search' || name === 'websearch_gpt_advanced';
11
+ /** DSH 0.2.1 settles a tool called from inside programmatic tool calling (`run_code`) with this event, not `tool/result`. */
12
+ export const NESTED_SETTLE_EVENT = 'tool/ptc-dispatch';
13
+ /**
14
+ * A search call's settlement and its tool-owned presentation `meta`, from either event that carries one: a
15
+ * model-direct call settles as `tool/result` (its name comes from the earlier `tool/call`); a nested call settles
16
+ * as `tool/ptc-dispatch`, whose `name`, `subCallId` and `meta` are its own fields.
17
+ */
18
+ function searchSettlementOf(event, pendingName) {
19
+ if (!object(event) || !object(event.data) || !object(event.data.meta))
20
+ return;
21
+ // Official ToolMessageSource carries only callId; a direct result resolves its name from tool/call.
22
+ // A nested settlement states the tool it dispatched, so it needs no pending entry.
23
+ const name = event.type === NESTED_SETTLE_EVENT ? event.data.name : event.type === 'tool/result' ? pendingName : undefined;
24
+ // Only our owned search results may contribute auxiliary billing or media.
25
+ return isSearchTool(name) ? { name, meta: event.data.meta } : undefined;
26
+ }
11
27
  export function auxiliaryUsageOf(event, toolName) {
12
- if (!object(event) || event.type !== 'tool/result' || !object(event.data?.meta))
28
+ const settled = searchSettlementOf(event, toolName);
29
+ if (!settled)
13
30
  return [];
14
- // Only our owned search results may contribute auxiliary billing.
15
- // Official ToolMessageSource carries only callId; resolve its name from tool/call.
16
- if (!isSearchTool(toolName))
17
- return [];
18
- const raw = event.data.meta.auxiliaryUsage;
31
+ const raw = settled.meta.auxiliaryUsage;
19
32
  if (!Array.isArray(raw))
20
33
  return [];
21
34
  const ids = new Set(), result = [];
@@ -58,21 +71,6 @@ export function mergeBuckets(base, extra) {
58
71
  }
59
72
  return next;
60
73
  }
61
- export function addTurnUsage(base, records) {
62
- if (!object(base) || !records.length || !count(base.totalTokens))
63
- return base;
64
- const next = mergeBuckets(base, addUsage(zeroBuckets(), records));
65
- next.totalTokens = base.totalTokens + records.reduce((n, r) => n + r.usage.totalTokens, 0);
66
- // Auxiliary responses do not always disclose a reasoning subset.
67
- delete next.reasoningTokens;
68
- if (Array.isArray(base.routes)) {
69
- const routes = new Map();
70
- for (const r of [...base.routes, ...records])
71
- routes.set(`${r.provider}\0${r.model}`, { provider: r.provider, model: r.model });
72
- next.routes = [...routes.values()];
73
- }
74
- return next;
75
- }
76
74
  /** The metadata is presentation/accounting state; it never changes request messages. */
77
75
  export function aggregateContextOf(event) {
78
76
  const mark = contextMarkerOf(event);
@@ -1,9 +1,8 @@
1
+ import { isRecord, codedError } from "./util.js";
1
2
  export const PORTABLE_BUDGET_ERROR_CODE = "LCX_PORTABLE_BUDGET_EXCEEDED";
2
3
  export const PORTABLE_UNSUPPORTED_CONTENT_CODE = "LCX_CHECKPOINT_PORTABLE_UNSUPPORTED_CONTENT";
3
4
  function unsupportedContent(kind) {
4
- return Object.assign(new Error(`LCX cannot budget unsupported message content: ${String(kind)}`), {
5
- code: PORTABLE_UNSUPPORTED_CONTENT_CODE,
6
- });
5
+ return codedError(`LCX cannot budget unsupported message content: ${String(kind)}`, PORTABLE_UNSUPPORTED_CONTENT_CODE);
7
6
  }
8
7
  const MAX_BUDGET_INPUT_CHARS = 2_000_000;
9
8
  const CONSERVATIVE_IMAGE_TOKEN_COST = 2_048;
@@ -12,15 +11,12 @@ const ASCII_WORD = /[A-Za-z0-9]/u;
12
11
  const STRUCTURAL = /[\p{P}\p{S}]/u;
13
12
  const DATA_URI = /^data:[^;,\s]+(?:;[^,\s]*)?;base64,[A-Za-z0-9+/\s]+={0,2}$/u;
14
13
  const ENCODED_TEXT = /^[A-Za-z0-9+/_-]{512,}={0,2}$/u;
15
- /** @param {string} value */
16
14
  function looksEncodedText(value) {
17
15
  return DATA_URI.test(value) || ENCODED_TEXT.test(value);
18
16
  }
19
17
  /**
20
18
  * A small conservative fallback, deliberately not a tokenizer. The baseline
21
19
  * preserves legacy /4 while CJK and structural characters cost more.
22
- * @param {unknown} value
23
- * @returns {number | undefined}
24
20
  */
25
21
  export function estimateTextTokens(value) {
26
22
  if (typeof value !== "string")
@@ -50,18 +46,6 @@ export function estimateTextTokens(value) {
50
46
  flushAscii();
51
47
  return Math.max(1, Math.ceil(value.length / 4), weighted);
52
48
  }
53
- /**
54
- * @param {unknown} value
55
- * @returns {value is UnknownRecord}
56
- */
57
- function isObject(value) {
58
- return value !== null && typeof value === "object" && !Array.isArray(value);
59
- }
60
- /**
61
- * @param {unknown} value
62
- * @param {Set<object>} [seen]
63
- * @returns {boolean}
64
- */
65
49
  function containsOpaqueValue(value, seen = new Set()) {
66
50
  if (value === null || typeof value !== "object")
67
51
  return false;
@@ -72,7 +56,6 @@ function containsOpaqueValue(value, seen = new Set()) {
72
56
  seen.add(value);
73
57
  return Object.values(value).some((entry) => containsOpaqueValue(entry, seen));
74
58
  }
75
- /** @param {unknown} value */
76
59
  function safeJson(value) {
77
60
  try {
78
61
  if (containsOpaqueValue(value))
@@ -84,7 +67,6 @@ function safeJson(value) {
84
67
  return undefined;
85
68
  }
86
69
  }
87
- /** @param {unknown} value */
88
70
  function safeScalar(value) {
89
71
  return typeof value === "string" ||
90
72
  typeof value === "number" ||
@@ -92,10 +74,6 @@ function safeScalar(value) {
92
74
  ? String(value)
93
75
  : undefined;
94
76
  }
95
- /**
96
- * @param {unknown} content
97
- * @returns {unknown[] | undefined}
98
- */
99
77
  function visibleContent(content) {
100
78
  if (typeof content === "string")
101
79
  return [{ type: "text", text: content }];
@@ -103,7 +81,7 @@ function visibleContent(content) {
103
81
  return undefined;
104
82
  const parts = [];
105
83
  for (const part of content) {
106
- if (!isObject(part) || typeof part.type !== "string")
84
+ if (!isRecord(part) || typeof part.type !== "string")
107
85
  throw unsupportedContent("missing block type");
108
86
  if (["text", "input_text", "output_text"].includes(part.type)) {
109
87
  if (typeof part.text !== "string")
@@ -137,11 +115,9 @@ function visibleContent(content) {
137
115
  /**
138
116
  * Project an item to model-visible fields only. Opaque provider state, raw
139
117
  * binary, and replay/session metadata are intentionally excluded.
140
- * @param {unknown} item
141
- * @returns {unknown | undefined}
142
118
  */
143
119
  export function modelVisibleBudgetView(item) {
144
- if (!isObject(item))
120
+ if (!isRecord(item))
145
121
  return undefined;
146
122
  if (item.type === "function_call") {
147
123
  const callId = safeScalar(item.call_id);
@@ -181,8 +157,6 @@ export function modelVisibleBudgetView(item) {
181
157
  /**
182
158
  * Images have provider/model-dependent costs. Count each known image block with
183
159
  * a fixed conservative surcharge without inspecting base64 or attachment data.
184
- * @param {unknown} value
185
- * @returns {number}
186
160
  */
187
161
  function imageTokenCost(value) {
188
162
  if (Array.isArray(value)) {
@@ -191,17 +165,13 @@ function imageTokenCost(value) {
191
165
  total += imageTokenCost(entry);
192
166
  return total;
193
167
  }
194
- if (!isObject(value))
168
+ if (!isRecord(value))
195
169
  return 0;
196
170
  let total = value.image === true ? CONSERVATIVE_IMAGE_TOKEN_COST : 0;
197
171
  for (const entry of Object.values(value))
198
172
  total += imageTokenCost(entry);
199
173
  return total;
200
174
  }
201
- /**
202
- * @param {unknown} item
203
- * @returns {number | undefined}
204
- */
205
175
  export function estimateBudgetItem(item) {
206
176
  const view = modelVisibleBudgetView(item);
207
177
  if (view === undefined)
@@ -210,7 +180,6 @@ export function estimateBudgetItem(item) {
210
180
  const textCost = estimateTextTokens(encoded);
211
181
  return textCost === undefined ? undefined : textCost + imageTokenCost(view);
212
182
  }
213
- /** @param {unknown} maxChars */
214
183
  export function portableTokenCeiling(maxChars) {
215
184
  return typeof maxChars === "number" &&
216
185
  Number.isSafeInteger(maxChars) &&
@@ -218,10 +187,6 @@ export function portableTokenCeiling(maxChars) {
218
187
  ? Math.ceil(maxChars / 4)
219
188
  : undefined;
220
189
  }
221
- /** @param {string} message */
222
190
  export function portableBudgetError(message) {
223
- /** @type {Error & { code?: string }} */
224
- const error = new Error(message);
225
- error.code = PORTABLE_BUDGET_ERROR_CODE;
226
- return error;
191
+ return codedError(message, PORTABLE_BUDGET_ERROR_CODE);
227
192
  }