dsh-lcx-codex 0.5.1-pre.1 → 0.5.1

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/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import z from "@deepseek-ai/schemastery";
2
- import { recordHostedUsage, withAuxiliaryUsage } from "./auxiliary-usage.js";
2
+ import { failedAuxiliaryUsageListener, recordHostedUsage, withAuxiliaryUsage } from "./auxiliary-usage.js";
3
3
  import { installSearchUsage } from "./search-usage.js";
4
4
  import { projectToolUpdates } from "@deepseek-ai/dsh-llm";
5
5
  import { WEB_SEARCH_MAX_QUERIES, applyWebSearchTool, } from "@deepseek-ai/dsh-tool-web";
@@ -12,10 +12,10 @@ import { join } from "node:path";
12
12
  import { AsyncLocalStorage } from "node:async_hooks";
13
13
  import { getSupportedThinkingLevels } from "./pi-responses-runtime.js";
14
14
  import { fetchJsonWithRetry } from "./transport.js";
15
- import { agentSessionId, agentUsesSession, compactionConfigState, compactionPatchCandidate, installCompactionPatch, patchCompactionConfig, patchToolResultPruner, readAgentRouteState, readSelectedAgentRouteState, recordAgentRouteEvent, resolveAgentService, resolveContextService, resolveScopedService, restoreCompactionConfig, restoreCompactionPatches, restoreToolResultPruner, sessionFor, sessionFromAgent, scopedToolRuntime, tokenMeterTotal, toolResultPrunerState, } from "./dsh-compat.js";
15
+ import { agentSessionId, agentUsesSession, compactionConfigState, compactionPatchCandidate, installCompactionPatch, patchCompactionConfig, patchToolResultPruner, readAgentRouteState, readSelectedAgentRouteState, recordAgentRouteEvent, resolveAgentService, resolveContextService, resolveScopedService, restoreCompactionConfig, restoreCompactionPatches, restoreToolResultPruner, sessionFor, sessionFromAgent, scopedToolRuntime, onScopedToolExecute, tokenMeterTotal, toolResultPrunerState, } from "./dsh-compat.js";
16
16
  import { InvocationPolicyScope } from "./invocation-policy-scope.js";
17
17
  import { authenticatedGrokHeaders, authenticatedHeaders, currentRoute, generationControlsFromSession, grokPromptCacheSessionId, promptCacheKey, promptCacheRetention, promptCacheSessionId, resolveGrokResponsesRouteConfig, resolveResponsesRouteConfig, routeFingerprint, } from "./route.js";
18
- import { DEFAULT_MAX_REQUEST_IMAGE_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET, DEFAULT_REQUEST_IMAGE_MAX_BYTES, hydrateNativeImageReferences, resolveRouteModelFacts, hasMidHistoryPromptSnapshot, responseInputItems, serializeDshMessages, } from "./dsh-responses.js";
18
+ import { DEFAULT_MAX_REQUEST_IMAGE_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET, DEFAULT_REQUEST_IMAGE_MAX_BYTES, assertAggregateImageBudget, hydrateNativeImageReferences, inputImageBase64Lengths, resolveRouteModelFacts, responseInputItems, serializeDshMessages, } from "./dsh-responses.js";
19
19
  import { mergeFeatureHeader, requestNativeCompaction } from "./compact-v2.js";
20
20
  import { buildResponsesBody } from "./responses-request.js";
21
21
  import { managedFailureChunk, streamResponsesRequest, } from "./responses-stream.js";
@@ -346,6 +346,11 @@ function syncGptToolsForAgent(ctx, agent, state, getConfig, provider, registrati
346
346
  }
347
347
  if (advanced)
348
348
  disposers.push(scopedTools.register(createAdvancedHostedTool(ctx, state, getConfig)));
349
+ // A search that was billed and then failed keeps its usage: only the Agent-scoped around-dispatch
350
+ // seam may attach `meta` to a failed tool result.
351
+ const disposeBilling = onScopedToolExecute(agent, failedAuxiliaryUsageListener);
352
+ if (disposeBilling)
353
+ disposers.push(disposeBilling);
349
354
  registrations.set(agent, {
350
355
  fingerprint,
351
356
  dispose() {
@@ -545,50 +550,45 @@ function mergeMap(target, source) {
545
550
  target.set(key, value);
546
551
  }
547
552
  /**
548
- * Follow traced item positions through the Grok replay restoration, which may splice items. When the
549
- * item count is unchanged the positions are exact; otherwise each traced item is found again by exact
550
- * structural equality in order (restoration never alters instruction items).
553
+ * The reasoning projection a GPT route serializes and sends with. A profile's declared
554
+ * `reasoningEfforts` wins (wire mapping, or `false` for a non-reasoning model); otherwise the catalog
555
+ * entry stands, and a model with no catalog entry follows what DSH itself resolved for it instead of
556
+ * being assumed to reason.
551
557
  */
552
- function locateSupersededItems(original, restored, positions) {
553
- if (positions.length === 0 || original.length === restored.length)
554
- return [...positions];
555
- const located = [];
556
- let cursor = 0;
557
- for (const position of positions) {
558
- const wanted = JSON.stringify(original[position]);
559
- while (cursor < restored.length && JSON.stringify(restored[cursor]) !== wanted)
560
- cursor += 1;
561
- if (cursor >= restored.length)
562
- throw Object.assign(new Error("LCX lost track of a superseded system prompt item"), { code: "LCX_RESPONSES_INVALID_INPUT" });
563
- located.push(cursor);
564
- cursor += 1;
565
- }
566
- return located;
558
+ function gptModelOverride(routeConfig, facts) {
559
+ if (routeConfig.modelControls !== undefined)
560
+ return { ...routeConfig.modelControls };
561
+ if (!facts.resolved)
562
+ return undefined;
563
+ return { reasoning: facts.reasoning !== undefined };
564
+ }
565
+ /** Refuse an effort DSH does not offer for this model, the way the DSH adapter and the Grok route do. */
566
+ function assertSupportedReasoningEffort(effort, facts) {
567
+ if (effort === undefined || !facts.resolved)
568
+ return;
569
+ const supported = facts.reasoning === undefined ? ["off"] : facts.reasoning.efforts;
570
+ if (supported.includes(String(effort)))
571
+ return;
572
+ throw Object.assign(new Error(`Responses route does not support reasoning effort "${String(effort)}"`), { code: "LCX_RESPONSES_UNSUPPORTED_OPTION" });
567
573
  }
568
574
  async function serializeNativeAware(messages, route, routeConfig, ctx, options) {
569
575
  const session = sessionFor(ctx, route.sessionId);
570
- // One adapter-owned lookup supplies image support and the route's system-prompt update mode. On an
571
- // "in-history" route DSH appends a changed prompt as a later full system message; it must reach the
572
- // model in place with instruction authority instead of being demoted to user context.
573
- const { imageSupport, systemPromptUpdate, resolved } = await resolveRouteModelFacts(ctx, route, options.signal);
574
- // An unreadable model mode must not demote instructions: history that holds a DSH prompt snapshot after
575
- // the head can only come from an in-history route, and sending it as user text would silently lower its
576
- // authority. Without such history the conservative default is harmless, so ordinary requests proceed.
577
- if (!resolved && hasMidHistoryPromptSnapshot(messages))
578
- throw Object.assign(new Error("LCX could not read the route's model information, so in-history system prompt updates cannot be sent safely; retry once the route is available"), { code: "LCX_SYSTEM_PROMPT_MODE_UNKNOWN" });
576
+ const modelFacts = await resolveRouteModelFacts(ctx, route, options.signal);
577
+ const { imageSupport } = modelFacts;
578
+ const modelOverride = options.grokNativeReplayRoute === undefined
579
+ ? gptModelOverride(routeConfig, modelFacts)
580
+ : undefined;
579
581
  const input = [];
580
582
  const imageMap = new Map();
581
583
  let nativeTools;
582
584
  let nativeModel;
583
585
  let grammarToolInputProperties;
584
586
  let normal = [];
585
- /** Absolute `input` positions rendered from DSH prompt snapshots that a checkpoint supersedes. */
586
- const supersededInstructionItems = [];
587
587
  const serializeOptions = (imageMapOverride = undefined, extra = {}) => requestImageOptions(routeConfig, imageSupport, options.signal, imageMapOverride, {
588
588
  route,
589
589
  tools: options.tools,
590
590
  responsesCompat: routeConfig.responsesCompat,
591
- systemPromptUpdate,
591
+ ...(modelOverride === undefined ? {} : { model: modelOverride }),
592
592
  ...extra,
593
593
  });
594
594
  const firstMessage = messages[0];
@@ -607,20 +607,22 @@ async function serializeNativeAware(messages, route, routeConfig, ctx, options)
607
607
  nativeTools = prelude.tools;
608
608
  nativeModel = prelude.model;
609
609
  grammarToolInputProperties = prelude.grammarToolInputProperties;
610
+ /** Base64 length of images DSH cannot offload (hydrated checkpoint, portable replay). */
611
+ let fixedImageBytes = 0;
612
+ /** Base64 length of each offloadable surface image, oldest first, across all batches. */
613
+ const surfaceImageBytes = [];
610
614
  const flush = async () => {
611
615
  if (!normal.length)
612
616
  return;
613
617
  const batch = normal;
614
618
  normal = [];
615
619
  const serialized = await serializeDshMessages(batch, ctx, serializeOptions());
620
+ surfaceImageBytes.push(...inputImageBase64Lengths(serialized.input));
616
621
  nativeTools = serialized.tools ?? nativeTools;
617
622
  nativeModel = serialized.model ?? nativeModel;
618
623
  grammarToolInputProperties =
619
624
  serialized.grammarToolInputProperties ?? grammarToolInputProperties;
620
- const restored = restoreGrokNativeReplay(serialized.input, batch.filter(isPersistedMessage), options.grokNativeReplayRoute);
621
- const base = input.length;
622
- supersededInstructionItems.push(...locateSupersededItems(serialized.input, restored, serialized.supersededInstructionItems).map((position) => base + position));
623
- input.push(...restored);
625
+ input.push(...restoreGrokNativeReplay(serialized.input, batch.filter(isPersistedMessage), options.grokNativeReplayRoute));
624
626
  mergeMap(imageMap, serialized.imageMap);
625
627
  };
626
628
  for (const message of surfaceMessages ?? []) {
@@ -639,15 +641,17 @@ async function serializeNativeAware(messages, route, routeConfig, ctx, options)
639
641
  const nativeOutput = state.nativeOutput;
640
642
  const hydratedMap = new Map();
641
643
  const hydrated = await hydrateNativeImageReferences(nativeOutput, ctx, requestImageOptions(routeConfig, imageSupport, options.signal, hydratedMap));
642
- input.push(...responseInputItems(hydrated));
644
+ const hydratedItems = responseInputItems(hydrated);
645
+ for (const bytes of inputImageBase64Lengths(hydratedItems))
646
+ fixedImageBytes += bytes;
647
+ input.push(...hydratedItems);
643
648
  mergeMap(imageMap, hydratedMap);
644
649
  }
645
650
  else {
646
651
  const portable = await portableMessagesForCheckpoint(ctx, session, checkpointId, { maxChars: routeConfig.portableReplayMaxChars });
647
- // Shadowed history is superseded by the head DSH re-rendered when the compaction began its new
648
- // series, so its old system messages stay ordinary context instead of regaining instruction
649
- // authority behind the current prompt.
650
- const serialized = await serializeDshMessages(portable, ctx, serializeOptions(undefined, { systemPromptUpdate: undefined }));
652
+ const serialized = await serializeDshMessages(portable, ctx, serializeOptions());
653
+ for (const bytes of inputImageBase64Lengths(serialized.input))
654
+ fixedImageBytes += bytes;
651
655
  input.push(...serialized.input);
652
656
  mergeMap(imageMap, serialized.imageMap);
653
657
  }
@@ -656,17 +660,24 @@ async function serializeNativeAware(messages, route, routeConfig, ctx, options)
656
660
  normal.push(message);
657
661
  }
658
662
  await flush();
663
+ assertAggregateImageBudget({
664
+ maxBytes: Number.isSafeInteger(routeConfig.maxRequestImageBytes) && Number(routeConfig.maxRequestImageBytes) > 0
665
+ ? Number(routeConfig.maxRequestImageBytes)
666
+ : DEFAULT_MAX_REQUEST_IMAGE_BYTES,
667
+ fixedBytes: fixedImageBytes,
668
+ surfaceBytes: surfaceImageBytes,
669
+ });
659
670
  if (!nativeModel)
660
671
  throw Object.assign(new Error("LCX could not resolve the Pi Responses model descriptor"), { code: "LCX_RESPONSES_MODEL_UNAVAILABLE" });
661
672
  return {
662
673
  input,
663
674
  ephemeralPreludeItemCount,
664
- supersededInstructionItems,
665
675
  imageMap,
666
676
  imageSupport,
667
677
  tools: nativeTools,
668
678
  model: nativeModel,
669
679
  grammarToolInputProperties,
680
+ modelFacts,
670
681
  };
671
682
  }
672
683
  function fallbackEligible(error, signal) {
@@ -717,7 +728,6 @@ async function* remoteCompactionStream(options, routeConfig, ctx, next) {
717
728
  result,
718
729
  input: prepared.input,
719
730
  ephemeralPreludeItemCount: prepared.ephemeralPreludeItemCount,
720
- supersededItemIndices: prepared.supersededInstructionItems,
721
731
  imageMap: prepared.imageMap,
722
732
  retentionOptions: {
723
733
  tokenBudget: routeConfig.nativeRetentionTokenBudget,
@@ -955,6 +965,28 @@ async function messagesContainNativeCheckpoint(ctx, messages, session) {
955
965
  function inputHasNativeState(input) {
956
966
  return input.some((item) => isRecord(item) && item.type === "compaction");
957
967
  }
968
+ /**
969
+ * One redacted line per failed provider request. Only the LCX class and machine-safe provider
970
+ * identifiers are logged: never the provider message, a payload, a header or a credential.
971
+ * `warn` matches the compaction failure line; DSH ships no persistent plugin-logger exporter by default
972
+ * (see ERRORS.md), so the line is visible wherever the host attaches one.
973
+ */
974
+ function logStreamFailure(ctx, route, info) {
975
+ const parts = [
976
+ `route=${route}`,
977
+ `code=${info.code}`,
978
+ info.status === undefined ? "" : `status=${info.status}`,
979
+ info.requestId === undefined ? "" : `requestId=${info.requestId}`,
980
+ info.event === undefined ? "" : `event=${info.event}`,
981
+ info.providerCode === undefined ? "" : `providerCode=${info.providerCode}`,
982
+ info.providerType === undefined ? "" : `providerType=${info.providerType}`,
983
+ info.incompleteReason === undefined
984
+ ? ""
985
+ : `incompleteReason=${info.incompleteReason}`,
986
+ `emitted=${info.contentEmitted}`,
987
+ ].filter(Boolean);
988
+ ctx.logger?.warn?.(`[lcx-codex] responses stream failed: ${parts.join(" ")}`);
989
+ }
958
990
  async function* managedResponsesStream(options, routeConfig, ctx) {
959
991
  const route = currentRoute(options, routeConfig);
960
992
  try {
@@ -962,6 +994,7 @@ async function* managedResponsesStream(options, routeConfig, ctx) {
962
994
  throw Object.assign(new Error("LCX Responses does not support GenerateOptions.stop"), { code: "LCX_RESPONSES_UNSUPPORTED_OPTION" });
963
995
  const projected = projectToolUpdates(options.messages, options.tools, undefined, options.toolHistory);
964
996
  const prepared = await serializeNativeAware(projected.messages, route, routeConfig, ctx, { signal: options.signal, tools: projected.tools && [...projected.tools] });
997
+ assertSupportedReasoningEffort(options.reasoningEffort, prepared.modelFacts);
965
998
  const cacheSessionId = promptCacheSessionId(route, routeConfig, ctx);
966
999
  const headers = await authenticatedHeaders(ctx, routeConfig, cacheSessionId, cacheSessionId === undefined ? null : route.sessionId);
967
1000
  const body = buildResponsesBody({
@@ -993,6 +1026,7 @@ async function* managedResponsesStream(options, routeConfig, ctx) {
993
1026
  timeoutMs: routeConfig.timeoutMs,
994
1027
  maxAttempts: 1,
995
1028
  maxResponseBytes: routeConfig.maxResponseBytes,
1029
+ onFailure: (info) => logStreamFailure(ctx, "gpt", info),
996
1030
  });
997
1031
  }
998
1032
  catch (error) {
@@ -1026,7 +1060,8 @@ async function* managedGrokNativeSearchStream(options, routeConfig, nativeSearch
1026
1060
  };
1027
1061
  const effectiveReasoning = options.reasoningEffort ?? routeConfig.profileReasoning;
1028
1062
  if (effectiveReasoning !== undefined &&
1029
- !getSupportedThinkingLevels(model).some((level) => level === effectiveReasoning))
1063
+ !getSupportedThinkingLevels(model).some((level) => level === effectiveReasoning) &&
1064
+ !(effectiveReasoning === "off" && routeConfig.modelControls?.offOmitsReasoning === true))
1030
1065
  throw Object.assign(new Error(`Grok route does not support reasoning effort "${String(effectiveReasoning)}"`), { code: "LCX_RESPONSES_UNSUPPORTED_OPTION" });
1031
1066
  const body = buildResponsesBody({
1032
1067
  model,
@@ -1062,6 +1097,7 @@ async function* managedGrokNativeSearchStream(options, routeConfig, nativeSearch
1062
1097
  isServerToolItem: (item) => isGrokNativeServerToolItem(item, nativeSearch, declaredToolNames),
1063
1098
  declaredToolNames,
1064
1099
  nativeReplayRoute,
1100
+ onFailure: (info) => logStreamFailure(ctx, "grok-native", info),
1065
1101
  onServerToolUsage(usage) {
1066
1102
  ctx.logger?.info?.(`[lcx-codex] Grok native search used ${usage.total} server-side tool call(s) (web=${usage.webSearchCalls}, x=${usage.xSearchCalls})`);
1067
1103
  },
@@ -321,32 +321,11 @@ export async function activeCompactionId(ctx, session) {
321
321
  lease[Symbol.dispose]();
322
322
  }
323
323
  }
324
- /**
325
- * On "in-history" routes DSH records every system prompt change as a full later `system` message
326
- * (source `system-prompt`). A checkpoint begins a new DSH series whose head is re-rendered with the
327
- * CURRENT prompt, so those snapshots in the retained window are superseded by that head. Retaining
328
- * one, as developer/system or even as user text, would keep a stale full prompt (for example plan-mode
329
- * policy that has since been switched off) in front of the model after the compaction.
330
- *
331
- * Only items the serializer traced back to such snapshots (`supersededItemIndices`, absolute positions
332
- * in `input`) are removed. Any other retained developer/system item is genuine client context and
333
- * stays. The ephemeral prelude is removed by the caller's slice, and the retention budget is computed
334
- * over what is actually kept.
335
- */
336
- function dropSupersededItems(input, preludeCount, superseded) {
337
- const drop = new Set();
338
- for (const position of superseded) {
339
- if (!Number.isSafeInteger(position) || position < preludeCount || position >= input.length)
340
- throw Object.assign(new Error("Native compaction superseded-item provenance is invalid"), { code: "LCX_COMPACTION_PRELUDE_PROVENANCE_INVALID" });
341
- drop.add(position);
342
- }
343
- return input.slice(preludeCount).filter((_, offset) => !drop.has(preludeCount + offset));
344
- }
345
324
  /**
346
325
  * @param {CreateCheckpointOptions} options
347
326
  * @returns {Promise<NativeCheckpointV5>}
348
327
  */
349
- export async function createNativeCheckpointBlock({ ctx, session, route, result, input = [], ephemeralPreludeItemCount = 0, supersededItemIndices = [], imageMap, retentionOptions = {}, }) {
328
+ export async function createNativeCheckpointBlock({ ctx, session, route, result, input = [], ephemeralPreludeItemCount = 0, imageMap, retentionOptions = {}, }) {
350
329
  const compactionId = await activeCompactionId(ctx, session);
351
330
  if (!compactionId) {
352
331
  const error = new Error("Native compaction could not correlate the active DSH compaction transaction");
@@ -358,7 +337,7 @@ export async function createNativeCheckpointBlock({ ctx, session, route, result,
358
337
  ephemeralPreludeItemCount > input.length) {
359
338
  throw Object.assign(new Error("Native compaction prelude provenance is invalid"), { code: "LCX_COMPACTION_PRELUDE_PROVENANCE_INVALID" });
360
339
  }
361
- const retention = retainedConversationPlan(dropSupersededItems(input, ephemeralPreludeItemCount, supersededItemIndices), retentionOptions);
340
+ const retention = retainedConversationPlan(input.slice(ephemeralPreludeItemCount), retentionOptions);
362
341
  /** @type {NativeOutputItem[]} */
363
342
  const nativeOutput = persistNativeImageReferences([...retention.items, structuredClone(result.compaction)], imageMap ?? new Map());
364
343
  return {
@@ -686,46 +665,35 @@ function groupMessages(messages) {
686
665
  .map((block) => String(block.id))
687
666
  : [];
688
667
  if (toolCalls.length === 0) {
668
+ // A tool result no call can claim (its call was not directly in front of it) cannot be replayed:
669
+ // upstream refuses a function_call_output without its call. Results that belong to a call are
670
+ // consumed with that call's group below and never reach this branch.
671
+ if (message.role === "tool")
672
+ continue;
689
673
  groups.push([message]);
690
674
  continue;
691
675
  }
692
676
  const group = [message];
693
677
  const pending = new Set(toolCalls);
694
678
  let cursor = index + 1;
695
- while (cursor < messages.length && pending.size > 0) {
679
+ // The run of tool messages right behind the call belongs to this group. Only the first result of
680
+ // each call it issued joins the group; a result for any other call, or a repeat, is not replayable
681
+ // (upstream refuses a function_call_output without its call) and is dropped. The whole run is
682
+ // consumed either way, so nothing in it is read again as a group of its own.
683
+ while (cursor < messages.length) {
696
684
  const next = messages[cursor];
697
- if (!next)
685
+ if (!next || next.role !== "tool")
698
686
  break;
699
- const results = next.role === "tool" ? [String(next.toolCallId)] : [];
700
- if (results.length === 0)
701
- break;
702
- group.push(next);
703
- for (const id of results)
704
- pending.delete(id);
687
+ const id = String(next.toolCallId);
688
+ if (pending.delete(id))
689
+ group.push(next);
705
690
  cursor += 1;
706
691
  }
707
- if (pending.size === 0)
708
- index = cursor - 1;
692
+ index = cursor - 1;
709
693
  groups.push(group);
710
694
  }
711
695
  return groups;
712
696
  }
713
- /**
714
- * A shadowed `system/message` (source `system-prompt`) is a full system prompt snapshot DSH appended
715
- * when the prompt changed on an "in-history" route. Portable replay is only used when the checkpoint
716
- * cannot be replayed natively (fork, route or model migration), and the request that follows always
717
- * carries a head rendered with the current prompt, so every snapshot in the shadowed range is
718
- * superseded: replaying it, even as user text, would put stale instructions (for example plan-mode
719
- * policy that was switched off) back in front of the model.
720
- *
721
- * Only messages DSH itself marks as system-prompt snapshots are dropped. The head is never inside a
722
- * compaction range, and a Session V3 log (where later system messages were ordinary context) cannot
723
- * reach this path: LCX refuses V3 checkpoints before transport. Other system-role messages without that
724
- * source keep the previous ordinary-context mapping.
725
- */
726
- export function withoutSupersededPromptSnapshots(messages) {
727
- return messages.filter((message) => !(message.role === "system" && message.source?.kind === "system-prompt"));
728
- }
729
697
  /**
730
698
  * @param {Session} session
731
699
  * @param {string} compactionId
@@ -740,8 +708,7 @@ export async function portableMessagesForCheckpoint(ctx, session, compactionId,
740
708
  ? configuredMaxChars
741
709
  : 80_000;
742
710
  const maxTokens = portableTokenCeiling(maxChars) ?? 1;
743
- // Superseded prompt snapshots are removed before grouping so they never consume the replay budget.
744
- const expanded = withoutSupersededPromptSnapshots(await shadowedMessagesForCheckpoint(ctx, session, compactionId));
711
+ const expanded = await shadowedMessagesForCheckpoint(ctx, session, compactionId);
745
712
  if (expanded.length === 0)
746
713
  return [];
747
714
  const groups = groupMessages(expanded);
@@ -38,7 +38,10 @@ export function responsesGenerationEnvelope({ model = "unknown", reasoningEffort
38
38
  result.include = ["reasoning.encrypted_content"];
39
39
  if (reasoningEffort !== undefined && reasoningEffort !== "off") {
40
40
  const requested = String(reasoningEffort);
41
- const wire = descriptor.thinkingLevelMap?.[requested] ?? requested;
41
+ // Unmapped means "send the level as is"; an explicit null means the model declares the level
42
+ // unsupported, so nothing is sent for it (the DSH adapter refuses such a level before dispatch).
43
+ const mapped = descriptor.thinkingLevelMap?.[requested];
44
+ const wire = mapped === undefined ? requested : mapped;
42
45
  if (wire !== null) {
43
46
  result.reasoning = { effort: wire, summary: "auto" };
44
47
  result.include = ["reasoning.encrypted_content"];
@@ -73,12 +73,115 @@ function errorFacts(error) {
73
73
  text: texts.join(" | "),
74
74
  };
75
75
  }
76
+ /** @param {unknown} value */
77
+ function safeMachineField(value) {
78
+ if (typeof value !== "string" || value.length === 0 || value.length > 96)
79
+ return undefined;
80
+ return /^[A-Za-z0-9_.:\[\]-]+$/u.test(value) ? value : undefined;
81
+ }
82
+ /**
83
+ * Record the structured facts of a failure the provider reports in-stream. Pi collapses every such
84
+ * event into one `Error("<code>: <message>")` and `response.completed` with status `failed` into a
85
+ * bare "stream ended in failure", so the machine fields are captured here, before that happens.
86
+ */
87
+ function observeUpstreamFailure(event, meta) {
88
+ const type = String(event.type ?? "");
89
+ let source;
90
+ let details;
91
+ let hasError = false;
92
+ let incomplete = false;
93
+ if (type === "error") {
94
+ // OpenAI sends flat `{code, message}`; some gateways nest `{error: {code, type}}`. `type` is only
95
+ // ever the error type when nested, because the flat `type` is the event name itself.
96
+ const nested = isObject(event.error) ? event.error : undefined;
97
+ source = { code: nested?.code ?? event.code, type: nested?.type };
98
+ hasError = true;
99
+ }
100
+ else if (isObject(event.response)) {
101
+ const response = event.response;
102
+ const status = response.status;
103
+ const failedTerminal = type === "response.failed" ||
104
+ (type === "response.completed" && status === "failed");
105
+ const incompleteTerminal = type === "response.incomplete" ||
106
+ (type === "response.completed" && status === "incomplete");
107
+ if (!failedTerminal && !incompleteTerminal)
108
+ return;
109
+ incomplete = incompleteTerminal;
110
+ details = isObject(response.incomplete_details)
111
+ ? response.incomplete_details.reason
112
+ : undefined;
113
+ // max_output_tokens is a length stop that Pi maps to a normal finish, not a failure.
114
+ if (incompleteTerminal && details === "max_output_tokens")
115
+ return;
116
+ source = isObject(response.error) ? response.error : undefined;
117
+ hasError = source !== undefined;
118
+ }
119
+ else
120
+ return;
121
+ const code = safeMachineField(source?.code);
122
+ const errorType = safeMachineField(source?.type);
123
+ const incompleteReason = safeMachineField(details);
124
+ meta.upstreamFailure = {
125
+ event: type,
126
+ ...(code === undefined ? {} : { code }),
127
+ ...(errorType === undefined ? {} : { type: errorType }),
128
+ ...(incompleteReason === undefined ? {} : { incompleteReason }),
129
+ hasError,
130
+ incomplete,
131
+ };
132
+ }
133
+ /** Closed mapping from provider machine identifiers to the DSH failure taxonomy; unknown identifiers return undefined. */
134
+ function classifyProviderIdentifier(value) {
135
+ if (value === undefined)
136
+ return undefined;
137
+ const id = value.toLowerCase();
138
+ if (id === "insufficient_quota" || id === "insufficient_user_quota")
139
+ return "INSUFFICIENT_QUOTA";
140
+ if (/^(?:invalid_api_key|authentication_error|permission_error)$/u.test(id))
141
+ return "AUTH";
142
+ if (/^rate_limit|^too_many_requests$/u.test(id))
143
+ return "RATE_LIMIT";
144
+ if (id === "context_length_exceeded")
145
+ return "CONTEXT_WINDOW_EXCEEDED";
146
+ if (id === "content_filter" ||
147
+ id === "content_policy_violation" ||
148
+ id.startsWith("invalid_"))
149
+ return "INVALID_REQUEST";
150
+ if (/^(?:server_error|internal_error|internal_server_error|api_error|service_unavailable|bad_response_status_code)$/u.test(id) ||
151
+ id.includes("overloaded"))
152
+ return "SERVER";
153
+ return undefined;
154
+ }
155
+ /**
156
+ * Failure class for an in-stream provider failure, from its structured fields only.
157
+ * `definite` classes come from a recognised identifier and outrank everything else. A failed response
158
+ * with no usable `error.code` (no error object, `{}`, a message only, an empty code, or only an unknown
159
+ * type) is still a provider-side failure and defaults to SERVER, but not definitely: wording in the
160
+ * message that clearly names another class (rate limit, context window, timeout) keeps that class.
161
+ * An unrecognised non-empty code is left to the text heuristics and the generic fallback.
162
+ */
163
+ function classifyUpstreamFailure(upstream) {
164
+ if (upstream === undefined)
165
+ return undefined;
166
+ const fromError = classifyProviderIdentifier(upstream.code) ??
167
+ classifyProviderIdentifier(upstream.type);
168
+ if (fromError !== undefined)
169
+ return { code: fromError, definite: true };
170
+ const fromReason = classifyProviderIdentifier(upstream.incompleteReason);
171
+ if (fromReason !== undefined)
172
+ return { code: fromReason, definite: true };
173
+ if (upstream.incomplete)
174
+ return undefined;
175
+ if (upstream.code === undefined)
176
+ return { code: "SERVER", definite: false };
177
+ return undefined;
178
+ }
76
179
  /**
77
180
  * Provider bodies/messages are deliberately not surfaced. Only a stable class and safe facts leave the wire boundary.
78
181
  * @param {unknown} error
79
182
  * @param {AbortSignal} [signal]
80
183
  */
81
- export function managedFailure(error, signal) {
184
+ export function managedFailure(error, signal, upstream) {
82
185
  const facts = errorFacts(error);
83
186
  const sourceCodes = new Set(facts.codes);
84
187
  const text = facts.text;
@@ -87,8 +190,11 @@ export function managedFailure(error, signal) {
87
190
  (signalReason?.name === "TimeoutError" ||
88
191
  signalReason?.code === "TimeoutError" ||
89
192
  /time(?:d)?\s*out|timeout/iu.test(String(signalReason?.message ?? "")));
193
+ const upstreamClass = signal?.aborted ? undefined : classifyUpstreamFailure(upstream);
90
194
  let code = "RESPONSES_ERROR";
91
- if (signalTimedOut ||
195
+ if (upstreamClass?.definite === true)
196
+ code = upstreamClass.code;
197
+ else if (signalTimedOut ||
92
198
  facts.status === 408 ||
93
199
  sourceCodes.has("TimeoutError") ||
94
200
  /time(?:d)?\s*out|timeout/iu.test(text))
@@ -104,8 +210,7 @@ export function managedFailure(error, signal) {
104
210
  else if (sourceCodes.has("LCX_GROK_NATIVE_PROTOCOL_ERROR"))
105
211
  code = "GROK_NATIVE_PROTOCOL_ERROR";
106
212
  else if (sourceCodes.has("LCX_RESPONSES_ROUTE_UNAVAILABLE") ||
107
- sourceCodes.has("LCX_RESPONSES_MODEL_UNAVAILABLE") ||
108
- sourceCodes.has("LCX_SYSTEM_PROMPT_MODE_UNKNOWN"))
213
+ sourceCodes.has("LCX_RESPONSES_MODEL_UNAVAILABLE"))
109
214
  code = "NO_ADAPTER";
110
215
  else if (sourceCodes.has("LCX_INSUFFICIENT_QUOTA"))
111
216
  code = "INSUFFICIENT_QUOTA";
@@ -129,6 +234,7 @@ export function managedFailure(error, signal) {
129
234
  facts.status === 422 ||
130
235
  sourceCodes.has("LCX_RESPONSES_INVALID_INPUT") ||
131
236
  sourceCodes.has("LCX_CHECKPOINT_UNSUPPORTED") ||
237
+ sourceCodes.has("LCX_CHECKPOINT_IMAGE_BUDGET") ||
132
238
  /invalid.?request|payload too large|length limit exceeded/iu.test(text))
133
239
  code = "INVALID_REQUEST";
134
240
  else if (sourceCodes.has("LCX_RESPONSE_TOO_LARGE"))
@@ -139,19 +245,22 @@ export function managedFailure(error, signal) {
139
245
  else if (error instanceof TypeError ||
140
246
  /\bnetwork|connection|socket|fetch|ECONN|EAI_AGAIN|terminated|premature close\b/iu.test(text))
141
247
  code = "TRANSPORT";
248
+ // Nothing in the text said otherwise: a failure the provider reported without a usable code is its own.
249
+ if (code === "RESPONSES_ERROR" && upstreamClass !== undefined)
250
+ code = upstreamClass.code;
142
251
  const messages = /** @type {Record<string, string>} */ {
143
252
  ABORTED: "Responses request was aborted",
144
253
  AUTH: "Responses request was rejected by authentication",
145
254
  INSUFFICIENT_QUOTA: "服务商额度不足或未满足请求预留额度,请检查中转额度(并非 API 密钥无效) / Provider quota is insufficient for this request",
146
255
  UNSUPPORTED_OPTION: "LCX Responses does not support this request option",
147
- NO_ADAPTER: sourceCodes.has("LCX_SYSTEM_PROMPT_MODE_UNKNOWN")
148
- ? "LCX could not read the route's model information, so in-history system prompt updates cannot be sent safely; retry once the route is available"
149
- : "LCX could not resolve the selected Responses route",
256
+ NO_ADAPTER: "LCX could not resolve the selected Responses route",
150
257
  RATE_LIMIT: "Responses provider rate limit was reached",
151
258
  SERVER: "Responses provider returned a server failure",
152
259
  INVALID_REQUEST: sourceCodes.has("LCX_CHECKPOINT_UNSUPPORTED")
153
260
  ? "Unsupported or invalid LCX checkpoint; start a new session"
154
- : "Responses provider rejected the request",
261
+ : sourceCodes.has("LCX_CHECKPOINT_IMAGE_BUDGET")
262
+ ? "Images kept in the compaction checkpoint exceed the request image bound; start a new session or raise maxRequestImageBytes"
263
+ : "Responses provider rejected the request",
155
264
  CONTEXT_WINDOW_EXCEEDED: "Responses request exceeded the model context window",
156
265
  UNSUPPORTED_CONTENT: "LCX cannot serialize a DSH content block for this Responses route",
157
266
  GROK_NATIVE_PROTOCOL_ERROR: "Grok returned an unrecognized client tool call while native search was enabled",
@@ -722,6 +831,7 @@ async function* normalizedResponseEvents(source, meta = {}, options = {}) {
722
831
  if (!isObject(raw))
723
832
  continue;
724
833
  const event = /** @type {UnknownRecord} */ raw;
834
+ observeUpstreamFailure(event, meta);
725
835
  if (options.serverToolTypes && ['response.completed', 'response.failed', 'response.incomplete'].includes(String(event.type))) {
726
836
  meta.contextDetails = sanitizeContextDetails(isObject(event.response) && isObject(event.response.usage)
727
837
  ? event.response.usage.context_details : undefined);
@@ -1335,7 +1445,33 @@ async function* toDshChunks(events, signal, wireMeta, nativeReplayRoute) {
1335
1445
  * @param {ReadonlySet<string>} [options.serverToolTypes]
1336
1446
  * @param {(usage: ServerToolUsage) => void} [options.onServerToolUsage]
1337
1447
  */
1338
- export async function* streamResponsesRequest({ baseURL, provider, model, piModel, body, grammarToolInputProperties, headers, signal, timeoutMs, applyDefaultTimeout = true, streamIdleTimeoutMs, maxAttempts = 1, maxResponseBytes, serverToolTypes, isServerToolItem, declaredToolNames, nativeReplayRoute, onServerToolUsage, }) {
1448
+ export async function* streamResponsesRequest({ baseURL, provider, model, piModel, body, grammarToolInputProperties, headers, signal, timeoutMs, applyDefaultTimeout = true, streamIdleTimeoutMs, maxAttempts = 1, maxResponseBytes, serverToolTypes, isServerToolItem, declaredToolNames, nativeReplayRoute, onServerToolUsage, onFailure, }) {
1449
+ let contentEmitted = false;
1450
+ let failureReported = false;
1451
+ /** One redacted report per request; user aborts are not failures. */
1452
+ const reportFailure = (chunk, managed, upstream) => {
1453
+ if (failureReported || onFailure === undefined)
1454
+ return;
1455
+ if (chunk.type !== "finish" || chunk.reason.kind !== "error")
1456
+ return;
1457
+ failureReported = true;
1458
+ const failure = chunk.reason.failure;
1459
+ try {
1460
+ onFailure({
1461
+ code: String(failure.code),
1462
+ ...(typeof failure.status === "number" ? { status: failure.status } : {}),
1463
+ ...(managed?.requestId === undefined ? {} : { requestId: managed.requestId }),
1464
+ ...(upstream?.code === undefined ? {} : { providerCode: upstream.code }),
1465
+ ...(upstream?.type === undefined ? {} : { providerType: upstream.type }),
1466
+ ...(upstream?.incompleteReason === undefined ? {} : { incompleteReason: upstream.incompleteReason }),
1467
+ ...(upstream === undefined ? {} : { event: upstream.event }),
1468
+ contentEmitted,
1469
+ });
1470
+ }
1471
+ catch {
1472
+ // Diagnostics must never change the stream outcome.
1473
+ }
1474
+ };
1339
1475
  const effectiveTimeoutMs = timeoutMs ?? (applyDefaultTimeout ? 300_000 : undefined);
1340
1476
  const deadline = requestDeadline(signal, effectiveTimeoutMs);
1341
1477
  const watchdog = streamIdleWatchdog(deadline.signal, streamIdleTimeoutMs);
@@ -1383,7 +1519,7 @@ export async function* streamResponsesRequest({ baseURL, provider, model, piMode
1383
1519
  output.stopReason = signal?.aborted ? "aborted" : "error";
1384
1520
  output.errorMessage =
1385
1521
  error instanceof Error ? error.message : "Responses stream failed";
1386
- output.__lcxFailure = managedFailure(error, signal);
1522
+ output.__lcxFailure = managedFailure(error, signal, wireMeta.upstreamFailure);
1387
1523
  piEvents.push({
1388
1524
  type: "error",
1389
1525
  reason: /** @type {'aborted' | 'error'} */ output.stopReason,
@@ -1405,7 +1541,13 @@ export async function* streamResponsesRequest({ baseURL, provider, model, piMode
1405
1541
  break;
1406
1542
  }
1407
1543
  watchdog.disarm();
1408
- yield result.value;
1544
+ const value = result.value;
1545
+ if (value.type === "text-delta" ||
1546
+ value.type === "reasoning-delta" ||
1547
+ value.type === "tool-call-delta")
1548
+ contentEmitted = true;
1549
+ reportFailure(value, output.__lcxFailure, wireMeta.upstreamFailure);
1550
+ yield value;
1409
1551
  watchdog.arm();
1410
1552
  }
1411
1553
  }
@@ -1417,7 +1559,9 @@ export async function* streamResponsesRequest({ baseURL, provider, model, piMode
1417
1559
  await parser;
1418
1560
  }
1419
1561
  catch (error) {
1420
- yield managedFailureChunk(error, signal);
1562
+ const chunk = managedFailureChunk(error, signal);
1563
+ reportFailure(chunk, managedFailure(error, signal), undefined);
1564
+ yield chunk;
1421
1565
  }
1422
1566
  finally {
1423
1567
  watchdog.dispose();