Merge remote-tracking branch 'origin/token-meter-service' into compact-post-step-overflow-recovery

# Conflicts: # docs/core-data-structures/compaction.md # docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml # docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.md # docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md # docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md # examples/coding-agent/cordis.yml # packages/compact/compact-basic/README.md # packages/compact/compact-basic/src/automatic.ts # packages/compact/compact-basic/src/config.ts # packages/compact/compact-basic/src/index.ts # packages/compact/compact-basic/tests/compact-basic.spec.ts
2026-08-15 21:04:50 +00:00 · 2026-07-16 16:18:16 +08:00
parent d027ea0d10 c3ddbde3c9
commit 5ff491e3a2
36 changed files with 939 additions and 1292 deletions
--- a/packages/compact/compact-basic/src/config.ts
+++ b/packages/compact/compact-basic/src/config.ts
@@ -1,65 +1,75 @@
 /**
- * Runtime defaulting and per-model policy validation for compact-basic.
+ * Runtime defaulting and policy validation for compact-basic.
 *
 * @module @deepseek-ai/dsh-compact-basic/config
 */

 import { deepFreeze } from '@deepseek-ai/dsh-llm'
-import type { ModelTokenMeter, TokenMeterService } from '@deepseek-ai/dsh-token-meter'
-import type {
-  BasicCompactConfig,
-  ModelCompactConfig,
-  ResolvedConfig,
-  ResolvedModelCompactConfig,
-} from './types.ts'
+import type { TokenMeterService } from '@deepseek-ai/dsh-token-meter'
+import type { BasicCompactConfig, ResolvedConfig } from './types.ts'

-/** Default request-pressure fraction for every metered model. */
+/** Default request-pressure fraction of the token meter's context window. */
 const DEFAULT_THRESHOLD_RATIO = 0.8

-/** Default verbatim-tail fraction of a model's context window. */
+/** Default verbatim-tail fraction of the token meter's context window. */
 const DEFAULT_RETAIN_RATIO = 0.16

+/** Complete public configuration key set. */
+const BASIC_COMPACT_CONFIG_KEYS: ReadonlySet<string> = new Set([
+  'thresholdRatio',
+  'retainTokens',
+  'summarizationModel',
+  'maxTokens',
+  'compactionRetries',
+  'maxOverflowRetries',
+  'auto',
+])
+
+/** Reject stale or misspelled keys before defaults can hide them. */
+function validateConfigKeys(config: BasicCompactConfig): void {
+  for (const key of Object.keys(config)) {
+    if (!BASIC_COMPACT_CONFIG_KEYS.has(key)) {
+      throw new Error(
+        `BasicCompactConfig: unknown key "${key}" `
+        + '(allowed: thresholdRatio, retainTokens, summarizationModel, maxTokens, '
+        + 'compactionRetries, maxOverflowRetries, auto)',
+      )
+    }
+  }
+}
+
 /**
- * Resolve common defaults and validate every named model override.
+ * Resolve defaults and validate the service-wide compaction policy.
 * @param config - raw compact-basic configuration.
- * @param tokenMeter - owning meter service used to reject unknown override names.
- * @returns a detached deeply immutable top-level configuration.
+ * @param tokenMeter - token meter supplying the context capacity.
+ * @returns a detached deeply immutable configuration.
 */
 export function resolveConfig(
  config: BasicCompactConfig = {},
  tokenMeter: TokenMeterService,
 ): ResolvedConfig {
-  const configuredModels: unknown = config.models
-  const models = configuredModels === undefined ? {} : configuredModels
-  if (typeof models !== 'object' || models === null || Array.isArray(models)) {
-    throw new Error('BasicCompactConfig: models must be an object')
-  }
-
-  const detachedModels: Record<string, ModelCompactConfig> = {}
-  for (const [model, override] of Object.entries(models as Record<string, unknown>)) {
-    if (typeof override !== 'object' || override === null || Array.isArray(override)) {
-      throw new Error(`BasicCompactConfig: models.${model} must be an object`)
-    }
-    const meter = tokenMeter.resolve(model)
-    detachedModels[model] = { ...override as ModelCompactConfig }
-    resolveModelConfig({
-      models: detachedModels,
-      summarizationModel: '',
-      maxTokens: 8192,
-      compactionRetries: 1,
-      maxOverflowRetries: 1,
-      auto: true,
-    }, meter)
-  }
-
+  validateConfigKeys(config)
+  const thresholdRatio = config.thresholdRatio ?? DEFAULT_THRESHOLD_RATIO
+  const retainTokens = config.retainTokens
+    ?? Math.floor(tokenMeter.contextWindow * DEFAULT_RETAIN_RATIO)
  const resolved: ResolvedConfig = {
-    models: detachedModels,
+    thresholdRatio,
+    retainTokens,
    summarizationModel: config.summarizationModel ?? '',
    maxTokens: config.maxTokens ?? 8192,
    compactionRetries: config.compactionRetries ?? 1,
    maxOverflowRetries: config.maxOverflowRetries ?? 1,
    auto: config.auto ?? true,
  }
+
+  assertRatio('thresholdRatio', resolved.thresholdRatio)
+  assertNonNegativeInteger('retainTokens', resolved.retainTokens)
+  const thresholdTokens = Math.floor(tokenMeter.contextWindow * resolved.thresholdRatio)
+  if (resolved.retainTokens >= thresholdTokens) {
+    throw new Error(
+      `BasicCompactConfig: retainTokens (${resolved.retainTokens}) must be less than threshold tokens ${thresholdTokens}`,
+    )
+  }
  assertPositiveInteger('maxTokens', resolved.maxTokens)
  assertNonNegativeInteger('compactionRetries', resolved.compactionRetries)
  assertNonNegativeInteger('maxOverflowRetries', resolved.maxOverflowRetries)
@@ -69,36 +79,7 @@ export function resolveConfig(
  if (typeof resolved.auto !== 'boolean') {
    throw new Error('BasicCompactConfig: auto must be a boolean')
  }
-  return deepFreeze(structuredClone(resolved))
-}
-
-/**
- * Resolve one effective model's default policy plus optional field overrides.
- * @param config - validated compact-basic configuration.
- * @param meter - effective model's token-meter handle and context capacity.
- * @returns a detached immutable model policy.
- */
-export function resolveModelConfig(
-  config: ResolvedConfig,
-  meter: ModelTokenMeter,
-): ResolvedModelCompactConfig {
-  const override = config.models[meter.model]
-  const thresholdRatio = override?.thresholdRatio ?? DEFAULT_THRESHOLD_RATIO
-  const retainTokens = override?.retainTokens ?? Math.floor(meter.contextWindow * DEFAULT_RETAIN_RATIO)
-  assertRatio(`models.${meter.model}.thresholdRatio`, thresholdRatio)
-  assertNonNegativeInteger(`models.${meter.model}.retainTokens`, retainTokens)
-  const thresholdTokens = Math.floor(meter.contextWindow * thresholdRatio)
-  if (retainTokens >= thresholdTokens) {
-    throw new Error(
-      `BasicCompactConfig: models.${meter.model}.retainTokens (${retainTokens}) must be less than threshold tokens ${thresholdTokens}`,
-    )
-  }
-  return deepFreeze({
-    model: meter.model,
-    contextWindow: meter.contextWindow,
-    thresholdRatio,
-    retainTokens,
-  })
+  return deepFreeze(resolved)
 }

 function assertPositiveInteger(name: string, value: number): void {
--- a/packages/compact/compact-basic/src/index.ts
+++ b/packages/compact/compact-basic/src/index.ts
@@ -11,34 +11,21 @@ import type { CompactionResult, CompactionTrigger } from '@deepseek-ai/dsh-compa
 import type { Session } from '@deepseek-ai/dsh-session'
 import { CONTEXT_WINDOW_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import {
-  TOKEN_METER_MODEL_UNCONFIGURED,
-  TokenMeterError,
-} from '@deepseek-ai/dsh-token-meter'
-import type { ModelTokenMeter } from '@deepseek-ai/dsh-token-meter'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { resolveConfig, resolveModelConfig } from './config.ts'
+import { resolveConfig } from './config.ts'
 import { compactSurfaceRegion, selectCompactableRange } from './region.ts'
 import { summarizeWithLlm } from './summarizer.ts'
 import type {
  BasicCompactConfig,
  ResolvedConfig,
-  ResolvedModelCompactConfig,
 } from './types.ts'

-export { resolveConfig, resolveModelConfig } from './config.ts'
+export { resolveConfig } from './config.ts'
 export type {
  BasicCompactConfig,
-  ModelCompactConfig,
  ResolvedConfig,
-  ResolvedModelCompactConfig,
 } from './types.ts'

-/** Resolve the latest actual routed model, then the agent's configured fallback. */
-function effectiveModel(agent: Agent): string | undefined {
-  return agent.session.requestHeader()?.config.model ?? agent.options.model
-}
-
 /** Resolve the exact model durably routed for the latest provider request. */
 function routedModel(session: Session): string | undefined {
  const model = session.requestHeader()?.config.model
@@ -50,17 +37,15 @@ function routedModel(session: Session): string | undefined {
 * retention, provenance, and summary-convergence pricing.
 *
 * `summarize()` is the sole subclass customization hook; the replay and durable
- * mutation strategy stays fixed so every pricing decision uses one effective
- * conversation-model meter.
+ * mutation strategy stays fixed so every pricing decision uses the singleton
+ * token meter.
 */
 export class BasicCompactService extends CompactService {
  static inject = ['llm', 'tokenMeter']

  static Config: z<BasicCompactConfig> = z.object({
-    models: z.dict(z.object({
-      thresholdRatio: z.number(),
-      retainTokens: z.number().step(1),
-    })),
+    thresholdRatio: z.number().default(0.8),
+    retainTokens: z.number().step(1),
    summarizationModel: z.string().default(''),
    maxTokens: z.number().step(1).min(1).default(8192),
    compactionRetries: z.number().step(1).min(0).default(1),
@@ -68,11 +53,9 @@ export class BasicCompactService extends CompactService {
    auto: z.boolean().default(true),
  })

-  /** Resolved and validated common configuration plus named partial overrides. */
+  /** Resolved and validated compaction configuration. */
  readonly config: ResolvedConfig

-  private readonly modelConfigs = new Map<string, ResolvedModelCompactConfig>()
-
  constructor(ctx: Context, config: BasicCompactConfig = {}) {
    super(ctx)
    this.config = resolveConfig(config, ctx.tokenMeter)
@@ -105,10 +88,6 @@ export class BasicCompactService extends CompactService {
        const result = await this.compactIfNeeded(agent, 'pressure', signal)
        if (result !== null) logResult(result, 'post-step pressure')
      } catch (error: unknown) {
-        // A named routed model without a meter profile is configuration failure,
-        // not an optional operational compaction miss.
-        if (error instanceof TokenMeterError
-          && error.code === TOKEN_METER_MODEL_UNCONFIGURED) throw error
        const message = error instanceof Error ? error.message : String(error)
        ctx.logger.warn(`post-step compaction failed: ${message}; continuing the turn`)
      }
@@ -157,7 +136,7 @@ export class BasicCompactService extends CompactService {

  /**
   * Compact for replayed post-step pressure or one provider-confirmed context
-   * overflow. Both triggers price the latest durable routed request model;
+   * overflow. Both triggers price the latest durable routed request envelope;
   * overflow bypasses the normal threshold and retained-tail policy so it can
   * force one useful balanced reduction.
   * @param agent - agent whose latest durable routed request is measured.
@@ -172,28 +151,21 @@ export class BasicCompactService extends CompactService {
  ): Promise<CompactionResult | null> {
    const model = routedModel(agent.session)
    if (model === undefined) return null
-    const meter = this.ctx.tokenMeter.resolve(model)
-    const policy = this._modelConfig(meter)
+    const meter = this.ctx.tokenMeter
    if (trigger === 'context-overflow') {
-      const surface = meter.measureSurface(agent.session)
-      const range = selectCompactableRange(agent.session, surface, 0)
+      const measurement = meter.measure(agent.session)
+      const range = selectCompactableRange(agent.session, measurement, 0)
      if (range === null) return null
      return this.compactRegion(agent.session, range.start, range.end, agent, signal)
    }

-    const threshold = Math.floor(policy.contextWindow * policy.thresholdRatio)
+    const threshold = Math.floor(meter.contextWindow * this.config.thresholdRatio)
    let measurement = meter.measure(agent.session)
    if (measurement.totalTokens < threshold) return null

    let result: CompactionResult | null = null
    for (let attempt = 0; attempt <= this.config.compactionRetries; attempt += 1) {
-      const surface = meter.measureSurface(agent.session)
-      if (surface.logRevision !== measurement.logRevision) {
-        throw new Error(
-          `compaction: pressure revision ${measurement.logRevision} does not match surface revision ${surface.logRevision}`,
-        )
-      }
-      const range = selectCompactableRange(agent.session, surface, policy.retainTokens)
+      const range = selectCompactableRange(agent.session, measurement, this.config.retainTokens)
      if (range === null) {
        /* v8 ignore else -- concrete replacement preserves a compactable checkpoint; subclass hooks cannot mutate it. */
        if (result === null) return null
@@ -213,12 +185,12 @@ export class BasicCompactService extends CompactService {

  /**
   * Compact one inclusive positional surface range using the effective
-   * conversation model for all retention and shrink pricing. Reject an agent
-   * that does not own the exact target before any resolution or mutation.
+   * token meter for all retention and shrink pricing. Reject an agent that does
+   * not own the exact target before any mutation.
   * @param session - session whose surface is mutated; must equal `agent.session`.
   * @param start - inclusive first surface-node seq.
   * @param end - inclusive last surface-node seq.
-   * @param agent - owner of the target session, used by the summarizer and model resolver.
+   * @param agent - owner of the target session, used by the summarizer.
   * @param signal - optional summarization cancellation signal.
   * @returns the successful durable compaction result.
   */
@@ -232,27 +204,11 @@ export class BasicCompactService extends CompactService {
    if (session !== agent.session) {
      throw new Error('compactRegion: agent.session must be the exact target session')
    }
-    const model = effectiveModel(agent)
-    if (model === undefined || model.length === 0) {
-      throw new Error('compactRegion: no routed or configured conversation model is available for token pricing')
-    }
-    const meter = this.ctx.tokenMeter.resolve(model)
-    this._modelConfig(meter)
    return compactSurfaceRegion({
-      meter,
+      meter: this.ctx.tokenMeter,
      summarize: (text, owner, abort) => this.summarize(text, owner, abort),
    }, session, start, end, agent, signal)
  }
-
-  /** Resolve and memoize one lazy default/override model policy. */
-  private _modelConfig(meter: ModelTokenMeter): ResolvedModelCompactConfig {
-    let modelConfig = this.modelConfigs.get(meter.model)
-    if (modelConfig === undefined) {
-      modelConfig = resolveModelConfig(this.config, meter)
-      this.modelConfigs.set(meter.model, modelConfig)
-    }
-    return modelConfig
-  }
 }

 export default BasicCompactService
--- a/packages/compact/compact-basic/src/region.ts
+++ b/packages/compact/compact-basic/src/region.ts
@@ -10,14 +10,14 @@ import {
  toolPairingBalancedBefore,
 } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult } from '@deepseek-ai/dsh-compact'
-import type { ModelTokenMeter, TokenSurfaceMeasurement } from '@deepseek-ai/dsh-token-meter'
+import type { TokenMeasurement, TokenMeterService } from '@deepseek-ai/dsh-token-meter'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { frameSummary } from './summarizer.ts'
 import type { SummaryResult } from './summarizer.ts'

 interface RegionDependencies {
-  readonly meter: ModelTokenMeter
+  readonly meter: TokenMeterService
  summarize(text: string, agent: Agent, signal?: AbortSignal): Promise<SummaryResult>
 }

@@ -25,16 +25,16 @@ interface RegionDependencies {
 * Resolve the next head-anchored range while retaining a priced recent tail
 * and never splitting an assistant tool-call/result pair.
 * @param session - session supplying authoritative current surface positions.
- * @param pricedSurface - same-revision surface measurement from the conversation meter.
+ * @param measurement - unified pressure and surface measurement from the conversation meter.
 * @param retainTokens - minimum recent tail budget retained verbatim.
 * @returns the inclusive positional seq range to compact, or `null`.
 */
 export function selectCompactableRange(
  session: Session,
-  pricedSurface: TokenSurfaceMeasurement,
+  measurement: TokenMeasurement,
  retainTokens: number,
 ): { start: number; end: number } | null {
-  const pricedNodes = pricedSurface.nodes
+  const pricedNodes = measurement.nodes
  if (pricedNodes.length === 0) return null

  const surfaceNodes = session.surface.nodes
@@ -115,8 +115,8 @@ export async function compactSurfaceRegion(
  try {
    // Capture after the lock event so any later durable append, including a
    // log-only one, invalidates the async selection before replacement.
-    const lockedSurface = dependencies.meter.measureSurface(session)
-    const selected = lockedSurface.nodes.slice(startIdx, endIdx + 1)
+    const lockedMeasurement = dependencies.meter.measure(session)
+    const selected = lockedMeasurement.nodes.slice(startIdx, endIdx + 1)
    if (selected.length !== shadowedSeqs.length
      || selected.some((node, index) => node.seq !== shadowedSeqs[index])) {
      throw new Error('compaction: selected surface changed before summarization began')
@@ -125,8 +125,8 @@ export async function compactSurfaceRegion(
    const text = renderTranscript(session.events, shadowedSeqs)
    const { summary, model, maxTokens } = await dependencies.summarize(text, agent, signal)

-    const currentSurface = dependencies.meter.measureSurface(session)
-    if (currentSurface.logRevision !== lockedSurface.logRevision) {
+    const currentMeasurement = dependencies.meter.measure(session)
+    if (currentMeasurement.logRevision !== lockedMeasurement.logRevision) {
      throw new Error('compaction: session log changed during summarization')
    }
    const framedSummary = frameSummary(summary)
--- a/packages/compact/compact-basic/src/types.ts
+++ b/packages/compact/compact-basic/src/types.ts
@@ -4,18 +4,12 @@
 * @module @deepseek-ai/dsh-compact-basic/types
 */

-/** Optional pressure and retention policy for one metered model. */
-export interface ModelCompactConfig {
-  /** Compact at this fraction of the model's configured context window. Defaults to `0.8`. */
+/** Basic compaction configuration; every common field has a deployment default. */
+export interface BasicCompactConfig {
+  /** Compact at this fraction of the token meter's context window. Defaults to `0.8`. */
  thresholdRatio?: number
  /** Recent surface tokens retained verbatim. Defaults to `floor(contextWindow * 0.16)`. */
  retainTokens?: number
-}
-
-/** Basic compaction configuration; every common field has a deployment default. */
-export interface BasicCompactConfig {
-  /** Field-wise pressure/retention overrides keyed by configured token-meter model name. */
-  models?: Record<string, ModelCompactConfig>
  /** Summary model; `''` resolves the latest routed model, then `AgentOptions.model`. Defaults to `''`. */
  summarizationModel?: string
  /** Provider generation cap for summarization. Defaults to `8192`. */
@@ -28,20 +22,13 @@ export interface BasicCompactConfig {
  auto?: boolean
 }

-/** Validated top-level defaults plus detached per-model partial overrides. */
+/** Validated and detached compaction configuration. */
 export interface ResolvedConfig {
-  readonly models: Readonly<Record<string, Readonly<ModelCompactConfig>>>
+  readonly thresholdRatio: number
+  readonly retainTokens: number
  readonly summarizationModel: string
  readonly maxTokens: number
  readonly compactionRetries: number
  readonly maxOverflowRetries: number
  readonly auto: boolean
 }
-
-/** Fully resolved pressure/retention policy for one effective model. */
-export interface ResolvedModelCompactConfig {
-  readonly model: string
-  readonly contextWindow: number
-  readonly thresholdRatio: number
-  readonly retainTokens: number
-}