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.
@@ -1,9 +1,10 @@
1
- // @ts-check
2
1
  import { isCompactCheckpointSource } from "@deepseek-ai/dsh-compaction";
3
2
  import { projectToolUpdates, } from "@deepseek-ai/dsh-llm";
4
3
  import { baseURLFingerprint, routeCompatible } from "./route.js";
5
4
  import { persistNativeImageReferences, responseInputItems } from "./dsh-responses.js";
6
5
  import { estimateBudgetItem, modelVisibleBudgetView, portableBudgetError, portableTokenCeiling, } from "./token-budget.js";
6
+ import { isRecord } from "./util.js";
7
+ import { DEFAULTS } from "./defaults.js";
7
8
  function sessionQueryUnavailable(cause) {
8
9
  return Object.assign(new Error("LCX checkpoint history requires the DSH session query service", { cause }), { code: "LCX_SESSION_QUERY_UNAVAILABLE" });
9
10
  }
@@ -18,127 +19,65 @@ async function observeEvents(ctx, session) {
18
19
  throw sessionQueryUnavailable(cause);
19
20
  }
20
21
  }
21
- /**
22
- * @typedef {object} NativeCheckpointBase
23
- * @property {string} compactionId
24
- * @property {string} provider
25
- * @property {string} model
26
- * @property {string} baseURLFingerprint
27
- * @property {string} sourceSessionId
28
- * @property {NativeOutputItem[]} nativeOutput
29
- * @property {CompactionItem} [nativeCompaction]
30
- * @property {number} [retainedInputCount]
31
- * @property {number} [retainedClientCount]
32
- * @property {number} [retainedAssistantCount]
33
- * @property {number} [retainedEstimatedTokens]
34
- * @property {number} [createdAt]
35
- */
36
- /** @typedef {NativeCheckpointBase & { type: 'lcx-native-compaction-v5', version: 5, retentionPolicy?: 'conversation-fidelity-v1' }} NativeCheckpointV5 */
37
- /** @typedef {NativeCheckpointV5} NativeCheckpointBlock */
38
22
  /**
39
23
  * Minimal validated candidate shape. DSH rawOutput is unknown until the existing
40
24
  * version, field, count, and compaction validation below has completed.
41
- * @typedef {object} NativeCheckpointCandidate
42
- * @property {typeof NATIVE_BLOCK_TYPE} type
43
- * @property {typeof NATIVE_BLOCK_VERSION} version
44
- * @property {unknown} [compactionId]
45
- * @property {unknown} [nativeOutput]
46
- * @property {unknown} [provider]
47
- * @property {unknown} [model]
48
- * @property {unknown} [baseURLFingerprint]
49
- * @property {unknown} [sourceSessionId]
50
- * @property {unknown} [retainedInputCount]
51
- * @property {unknown} [retainedClientCount]
52
- * @property {unknown} [retainedAssistantCount]
53
25
  */
54
- /** @typedef {{ compaction: CompactionItem }} NativeCompactionResult */
55
- /** @typedef {{ session: Session, route: RouteIdentity, result: NativeCompactionResult, input?: unknown[], ephemeralPreludeItemCount?: number, imageMap?: unknown, retentionOptions?: RetentionOptions }} CreateCheckpointOptions */
56
- /** @typedef {Error & { code?: string }} LcxError */
57
26
  export const NATIVE_BLOCK_TYPE = "lcx-native-compaction-v5";
58
27
  const MIGRATED_NATIVE_BLOCK_PREFIX = "plugin:lcx-native-compaction-";
59
28
  export const NATIVE_BLOCK_VERSION = 5;
60
- export const RETAINED_MESSAGE_TOKEN_BUDGET = 64_000;
61
- export const ASSISTANT_RETENTION_TOKEN_RESERVE = 24_000;
62
- export const ASSISTANT_RETENTION_PER_MESSAGE_TOKEN_CAP = 3_000;
63
- /**
64
- * @param {unknown} value
65
- * @returns {value is UnknownRecord}
66
- */
67
- function isObject(value) {
68
- return value !== null && typeof value === "object" && !Array.isArray(value);
69
- }
70
- /** @param {Message | null | undefined} message */
71
- function textOf(message) {
72
- return (message?.content ?? [])
73
- .filter((block) => block.type === "text")
74
- .map((block) => block.text)
75
- .join("");
76
- }
77
- /** @param {unknown} item */
29
+ export const RETAINED_MESSAGE_TOKEN_BUDGET = DEFAULTS.nativeRetentionTokenBudget;
30
+ export const ASSISTANT_RETENTION_TOKEN_RESERVE = DEFAULTS.assistantRetentionTokenReserve;
31
+ export const ASSISTANT_RETENTION_PER_MESSAGE_TOKEN_CAP = DEFAULTS.assistantRetentionPerMessageTokenCap;
78
32
  function estimatedItemTokens(item) {
79
33
  return estimateBudgetItem(item);
80
34
  }
81
- /**
82
- * @param {unknown} item
83
- * @returns {item is UnknownRecord}
84
- */
85
35
  function isRetainedClientItem(item) {
86
- if (!isObject(item) || (item.type !== undefined && item.type !== "message"))
36
+ if (!isRecord(item) || (item.type !== undefined && item.type !== "message"))
87
37
  return false;
88
38
  return (item.role === "user" || item.role === "developer" || item.role === "system");
89
39
  }
90
40
  function assistantTextParts(item) {
91
- if (!isObject(item) ||
41
+ if (!isRecord(item) ||
92
42
  item.type !== "message" ||
93
43
  item.role !== "assistant" ||
94
44
  !Array.isArray(item.content))
95
45
  return [];
96
- return item.content.filter((part) => isObject(part) &&
46
+ return item.content.filter((part) => isRecord(part) &&
97
47
  part.type === "output_text" &&
98
48
  typeof part.text === "string" &&
99
49
  part.text.length > 0);
100
50
  }
101
- /** @param {unknown} item */
102
51
  function isRetainedAssistantItem(item) {
103
52
  return assistantTextParts(item).length > 0;
104
53
  }
105
- /** @param {unknown} item */
106
54
  function assistantText(item) {
107
55
  return assistantTextParts(item)
108
56
  .map((part) => part.text)
109
57
  .join("");
110
58
  }
111
- /** @param {unknown} item */
112
59
  function retainedAssistantPhase(item) {
113
- const phase = isObject(item) ? item.phase : undefined;
60
+ const phase = isRecord(item) ? item.phase : undefined;
114
61
  return phase === "commentary" || phase === "final_answer" ? phase : undefined;
115
62
  }
116
- /** @param {unknown} value */
117
63
  function containsBudgetImage(value) {
118
64
  if (Array.isArray(value))
119
65
  return value.some(containsBudgetImage);
120
- if (!isObject(value))
66
+ if (!isRecord(value))
121
67
  return false;
122
68
  return value.image === true || Object.values(value).some(containsBudgetImage);
123
69
  }
124
- /** @param {unknown} item */
125
70
  function isImageBudgetItem(item) {
126
71
  return containsBudgetImage(modelVisibleBudgetView(item));
127
72
  }
128
- /**
129
- * @param {unknown} item
130
- * @param {number} [maxTokens]
131
- * @returns {UnknownRecord | undefined}
132
- */
133
73
  function truncateVisibleAssistantItem(item, maxTokens = ASSISTANT_RETENTION_PER_MESSAGE_TOKEN_CAP) {
134
74
  const text = assistantText(item);
135
75
  if (!text)
136
76
  return undefined;
137
77
  const phase = retainedAssistantPhase(item);
138
- const providerId = isObject(item) && typeof item.id === "string" && item.id
78
+ const providerId = isRecord(item) && typeof item.id === "string" && item.id
139
79
  ? item.id
140
80
  : undefined;
141
- /** @param {string} retained @param {boolean} preserveProviderId */
142
81
  const candidate = (retained, preserveProviderId) => ({
143
82
  type: "message",
144
83
  role: "assistant",
@@ -150,7 +89,6 @@ function truncateVisibleAssistantItem(item, maxTokens = ASSISTANT_RETENTION_PER_
150
89
  if ((estimatedItemTokens(full) ?? Infinity) <= maxTokens)
151
90
  return full;
152
91
  const marker = "\n…[LCX retained answer truncated]…\n";
153
- /** @param {number} count */
154
92
  const shortened = (count) => {
155
93
  const available = Math.max(0, count - marker.length);
156
94
  const head = Math.floor(available * 0.72);
@@ -172,15 +110,7 @@ function truncateVisibleAssistantItem(item, maxTokens = ASSISTANT_RETENTION_PER_
172
110
  }
173
111
  return best;
174
112
  }
175
- /**
176
- * @param {IndexedItem[]} candidates
177
- * @param {number} budget
178
- * @param {(value: IndexedItem) => unknown} [transform]
179
- * @param {boolean} [stopOnImageOverflow]
180
- * @returns {Selection}
181
- */
182
113
  function selectNewest(candidates, budget, transform = (value) => structuredClone(value.item), stopOnImageOverflow = false) {
183
- /** @type {SelectedItem[]} */
184
114
  const selected = [];
185
115
  let used = 0;
186
116
  for (let index = candidates.length - 1; index >= 0; index -= 1) {
@@ -201,30 +131,6 @@ function selectNewest(candidates, budget, transform = (value) => structuredClone
201
131
  }
202
132
  return { selected, used };
203
133
  }
204
- /**
205
- * @param {unknown[] | null | undefined} input
206
- * @param {RetentionOptions} [options]
207
- * @returns {unknown[]}
208
- */
209
- export function retainedCompactionInput(input, options = {}) {
210
- const configuredBudget = options.tokenBudget;
211
- const budget = typeof configuredBudget === "number" &&
212
- Number.isSafeInteger(configuredBudget) &&
213
- configuredBudget > 0
214
- ? configuredBudget
215
- : RETAINED_MESSAGE_TOKEN_BUDGET;
216
- const candidates = (input ?? [])
217
- .map((item, index) => ({ item, index }))
218
- .filter(({ item }) => isRetainedClientItem(item));
219
- return selectNewest(candidates, budget)
220
- .selected.sort((a, b) => a.index - b.index)
221
- .map(({ item }) => item);
222
- }
223
- /**
224
- * @param {unknown[] | null | undefined} input
225
- * @param {RetentionOptions} [options]
226
- * @returns {RetentionPlan}
227
- */
228
134
  export function retainedConversationPlan(input, options = {}) {
229
135
  const configuredBudget = options.tokenBudget;
230
136
  const totalBudget = typeof configuredBudget === "number" &&
@@ -258,18 +164,6 @@ export function retainedConversationPlan(input, options = {}) {
258
164
  assistantEstimatedTokens: assistant.used,
259
165
  };
260
166
  }
261
- /**
262
- * @param {unknown[] | null | undefined} input
263
- * @param {RetentionOptions} [options]
264
- */
265
- export function retainedConversationInput(input, options = {}) {
266
- return retainedConversationPlan(input, options).items;
267
- }
268
- /** @param {unknown[] | null | undefined} items */
269
- export function hasRetainedCompactionInput(items) {
270
- return (items ?? []).some((item) => isRetainedClientItem(item) || isRetainedAssistantItem(item));
271
- }
272
- /** @param {Message | null | undefined} message */
273
167
  function hasCompactionId(source) {
274
168
  return (isCompactCheckpointSource(source) &&
275
169
  "compactionId" in source &&
@@ -301,7 +195,7 @@ export function assertSupportedCheckpointMessage(message) {
301
195
  export async function activeCompactionId(ctx, session) {
302
196
  if (!session)
303
197
  return undefined;
304
- /** @type {Set<string>} */ const ended = new Set();
198
+ const ended = new Set();
305
199
  const lease = await observeEvents(ctx, session);
306
200
  try {
307
201
  const events = lease.events;
@@ -328,8 +222,9 @@ export async function activeCompactionId(ctx, session) {
328
222
  * one, as developer/system or even as user text, would keep a stale full prompt (for example plan-mode
329
223
  * policy that has since been switched off) in front of the model after the compaction.
330
224
  *
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
225
+ * Only items traced to such snapshots or Pi tool-update notices (`supersededItemIndices`, absolute positions
226
+ * in `input`) are removed. Tool notices belong to the old series, whose declarations retention drops.
227
+ * Any other retained developer/system item is genuine client context and
333
228
  * stays. The ephemeral prelude is removed by the caller's slice, and the retention budget is computed
334
229
  * over what is actually kept.
335
230
  */
@@ -342,10 +237,6 @@ function dropSupersededItems(input, preludeCount, superseded) {
342
237
  }
343
238
  return input.slice(preludeCount).filter((_, offset) => !drop.has(preludeCount + offset));
344
239
  }
345
- /**
346
- * @param {CreateCheckpointOptions} options
347
- * @returns {Promise<NativeCheckpointV5>}
348
- */
349
240
  export async function createNativeCheckpointBlock({ ctx, session, route, result, input = [], ephemeralPreludeItemCount = 0, supersededItemIndices = [], imageMap, retentionOptions = {}, }) {
350
241
  const compactionId = await activeCompactionId(ctx, session);
351
242
  if (!compactionId) {
@@ -359,7 +250,6 @@ export async function createNativeCheckpointBlock({ ctx, session, route, result,
359
250
  throw Object.assign(new Error("Native compaction prelude provenance is invalid"), { code: "LCX_COMPACTION_PRELUDE_PROVENANCE_INVALID" });
360
251
  }
361
252
  const retention = retainedConversationPlan(dropSupersededItems(input, ephemeralPreludeItemCount, supersededItemIndices), retentionOptions);
362
- /** @type {NativeOutputItem[]} */
363
253
  const nativeOutput = persistNativeImageReferences([...retention.items, structuredClone(result.compaction)], imageMap ?? new Map());
364
254
  return {
365
255
  type: NATIVE_BLOCK_TYPE,
@@ -379,11 +269,6 @@ export async function createNativeCheckpointBlock({ ctx, session, route, result,
379
269
  createdAt: Date.now(),
380
270
  };
381
271
  }
382
- /**
383
- * @param {NativeCheckpointBlock} block
384
- * @param {unknown} usage
385
- * @returns {UnknownRecord[]}
386
- */
387
272
  export function nativeCheckpointChunks(block, usage) {
388
273
  const text = "LCX Native V2 checkpoint saved in the DSH session log.";
389
274
  return [
@@ -396,11 +281,6 @@ export function nativeCheckpointChunks(block, usage) {
396
281
  { type: "finish", reason: { kind: "stop" } },
397
282
  ];
398
283
  }
399
- /**
400
- * @param {Session | null | undefined} session
401
- * @param {string | null | undefined} compactionId
402
- * @returns {Promise<CompactionSummaryEvent | undefined>}
403
- */
404
284
  export async function compactionSummaryEvent(ctx, session, compactionId) {
405
285
  if (!session || !compactionId)
406
286
  return undefined;
@@ -421,11 +301,9 @@ export async function compactionSummaryEvent(ctx, session, compactionId) {
421
301
  }
422
302
  /**
423
303
  * rawOutput elements remain untrusted until stateFromSummaryEvent validates them.
424
- * @param {CompactionSummaryEvent | null | undefined} event
425
- * @returns {NativeCheckpointCandidate | undefined}
426
304
  */
427
305
  function isNativeCheckpointCandidate(value) {
428
- if (!isObject(value))
306
+ if (!isRecord(value))
429
307
  return false;
430
308
  return (value.type === NATIVE_BLOCK_TYPE && value.version === NATIVE_BLOCK_VERSION);
431
309
  }
@@ -441,21 +319,16 @@ function nativeBlockFromSummary(event) {
441
319
  return undefined;
442
320
  }
443
321
  function assertNoMigratedNativeBlock(raw) {
444
- if (raw?.some(value => isObject(value) && typeof value.type === "string" &&
322
+ if (raw?.some(value => isRecord(value) && typeof value.type === "string" &&
445
323
  value.type.startsWith(MIGRATED_NATIVE_BLOCK_PREFIX)))
446
324
  throw Object.assign(new Error("Unsupported LCX checkpoint format; start a new session"), {
447
325
  code: "LCX_CHECKPOINT_UNSUPPORTED",
448
326
  });
449
327
  }
450
- /** @param {unknown} value */
451
328
  function validateCount(value) {
452
329
  return (value === undefined ||
453
330
  (typeof value === "number" && Number.isSafeInteger(value) && value >= 0));
454
331
  }
455
- /**
456
- * @param {CompactionSummaryEvent | null | undefined} event
457
- * @returns {NativeCheckpointBlock | undefined}
458
- */
459
332
  export function stateFromSummaryEvent(event) {
460
333
  if (!event)
461
334
  return undefined;
@@ -481,12 +354,12 @@ export function stateFromSummaryEvent(event) {
481
354
  catch {
482
355
  return undefined;
483
356
  }
484
- const compactions = block.nativeOutput.filter((item) => isObject(item) &&
357
+ const compactions = block.nativeOutput.filter((item) => isRecord(item) &&
485
358
  item.type === "compaction" &&
486
359
  typeof item.encrypted_content === "string");
487
360
  if (compactions.length !== 1 || compactions[0].encrypted_content.trim().length === 0)
488
361
  return undefined;
489
- const compactionIndex = block.nativeOutput.findIndex((item) => isObject(item) && item.type === "compaction");
362
+ const compactionIndex = block.nativeOutput.findIndex((item) => isRecord(item) && item.type === "compaction");
490
363
  const prefix = compactionIndex >= 0 ? block.nativeOutput.slice(0, compactionIndex) : [];
491
364
  {
492
365
  const clients = prefix.filter(isRetainedClientItem).length;
@@ -525,10 +398,6 @@ export function stateFromSummaryEvent(event) {
525
398
  };
526
399
  return { ...base, type: NATIVE_BLOCK_TYPE, version: NATIVE_BLOCK_VERSION };
527
400
  }
528
- /**
529
- * @param {Session} session
530
- * @param {Message} message
531
- */
532
401
  export function checkpointStateForMessage(ctx, session, message) {
533
402
  assertSupportedCheckpointMessage(message);
534
403
  const id = compactCheckpointId(message);
@@ -539,28 +408,22 @@ export function checkpointStateForMessage(ctx, session, message) {
539
408
  async function checkpointStateForMessageAsync(ctx, session, id) {
540
409
  const event = await compactionSummaryEvent(ctx, session, id);
541
410
  const state = stateFromSummaryEvent(event);
542
- const hasNativeBlock = event?.data.rawOutput?.some(value => isObject(value) && typeof value.type === "string" &&
411
+ const hasNativeBlock = event?.data.rawOutput?.some(value => isRecord(value) && typeof value.type === "string" &&
543
412
  (value.type.startsWith("lcx-native-compaction-") || value.type.startsWith(MIGRATED_NATIVE_BLOCK_PREFIX)));
544
413
  if (hasNativeBlock && !state)
545
414
  throw Object.assign(new Error("Unsupported or invalid LCX checkpoint; start a new session"), { code: "LCX_CHECKPOINT_UNSUPPORTED" });
546
415
  return state;
547
416
  }
548
- /**
549
- * @param {NativeCheckpointBlock} state
550
- * @param {RouteIdentity} route
551
- * @param {unknown} ctx
552
- */
553
417
  export function stateRouteCompatible(state, route, ctx) {
554
418
  return routeCompatible(state, route, ctx);
555
419
  }
556
420
  const DSH_PROJECTION_UNAVAILABLE_PREFIX = 'session message projection "';
557
421
  const DSH_PROJECTION_UNAVAILABLE_SUFFIX = '" was removed or replaced; restore the session with its owning plugin';
558
422
  /**
559
- * DSH 0.1.6 attaches no error code or subclass to this failure and exposes no
423
+ * DSH attaches no error code or subclass to this failure and exposes no
560
424
  * public inventory of required or active projections, so message shape is the
561
425
  * only available signal. Both classes fail closed, so a misclassification
562
426
  * costs precision in the error code, not correctness.
563
- * @param {unknown} cause
564
427
  */
565
428
  function isMissingOrReplacedProjectionError(cause) {
566
429
  if (!(cause instanceof Error))
@@ -578,15 +441,12 @@ function checkpointHistoryReadError(cause) {
578
441
  }), { code: "LCX_CHECKPOINT_UNSUPPORTED" });
579
442
  }
580
443
  /**
581
- * DSH 0.1.6 derives a message only while every `SessionMessageProjection` the
444
+ * DSH derives a message only while every `SessionMessageProjection` the
582
445
  * durable log committed is still registered; an absent or replaced owner throws
583
446
  * instead of yielding pre-projection content. Reconstructing the shadowed
584
447
  * transcript without that owner would resurrect content a durable decision
585
448
  * (for example `image/offload`) removed, so this is a checkpoint
586
449
  * incompatibility rather than a recoverable read.
587
- * @param {Session} session
588
- * @param {number} seq
589
- * @returns {Message | undefined}
590
450
  */
591
451
  function eventMessage(session, events, seq) {
592
452
  if (!Number.isSafeInteger(seq) || seq < 0)
@@ -603,7 +463,6 @@ function eventMessage(session, events, seq) {
603
463
  throw checkpointHistoryReadError(cause);
604
464
  }
605
465
  }
606
- /** @param {Message} message */
607
466
  function estimateChars(message) {
608
467
  try {
609
468
  const encoded = JSON.stringify(message);
@@ -613,11 +472,6 @@ function estimateChars(message) {
613
472
  return undefined;
614
473
  }
615
474
  }
616
- /**
617
- * @param {Session} session
618
- * @param {string} compactionId
619
- * @returns {Promise<Message[]>}
620
- */
621
475
  async function expandedCheckpointMessages(ctx, session, compactionId) {
622
476
  const lease = await observeEvents(ctx, session);
623
477
  try {
@@ -663,20 +517,10 @@ async function expandedCheckpointMessages(ctx, session, compactionId) {
663
517
  lease[Symbol.dispose]();
664
518
  }
665
519
  }
666
- /**
667
- * @param {Session} session
668
- * @param {string} compactionId
669
- * @returns {Promise<Message[]>}
670
- */
671
520
  export async function shadowedMessagesForCheckpoint(ctx, session, compactionId) {
672
521
  return expandedCheckpointMessages(ctx, session, compactionId);
673
522
  }
674
- /**
675
- * @param {readonly Message[]} messages
676
- * @returns {Message[][]}
677
- */
678
523
  function groupMessages(messages) {
679
- /** @type {Message[][]} */
680
524
  const groups = [];
681
525
  for (let index = 0; index < messages.length; index += 1) {
682
526
  const message = messages[index];
@@ -731,19 +575,13 @@ function groupMessages(messages) {
731
575
  export function withoutSupersededPromptSnapshots(messages) {
732
576
  return messages.filter((message) => !(message.role === "system" && message.source?.kind === "system-prompt"));
733
577
  }
734
- /**
735
- * @param {Session} session
736
- * @param {string} compactionId
737
- * @param {{ maxChars?: number }} [options]
738
- * @returns {Promise<Message[]>}
739
- */
740
578
  export async function portableMessagesForCheckpoint(ctx, session, compactionId, options = {}) {
741
579
  const configuredMaxChars = options.maxChars;
742
580
  const maxChars = typeof configuredMaxChars === "number" &&
743
581
  Number.isSafeInteger(configuredMaxChars) &&
744
582
  configuredMaxChars > 0
745
583
  ? configuredMaxChars
746
- : 80_000;
584
+ : DEFAULTS.portableReplayMaxChars;
747
585
  const maxTokens = portableTokenCeiling(maxChars) ?? 1;
748
586
  // Superseded prompt snapshots are removed before grouping so they never consume the replay budget.
749
587
  const expanded = withoutSupersededPromptSnapshots(await shadowedMessagesForCheckpoint(ctx, session, compactionId));