@modelprofile.com/flexharness-agent 14.0.0 → 15.0.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.
@@ -12,6 +12,7 @@ import {
12
12
  type IGenerationBegunEvent,
13
13
  type IGenerationExecutionCompletedEvent,
14
14
  type IGenerationExecutionStartedEvent,
15
+ type IAgentContextUsage,
15
16
  type IGenerationOutcomeEvent,
16
17
  type IRuntimeEvent,
17
18
  type IToolCallEvent,
@@ -63,6 +64,13 @@ import { validateAgentEventSnapshot } from './smartagent.persistence.js';
63
64
  import { MAX_RETRY_ATTEMPTS, planModelCallRetry } from './smartagent.retry.js';
64
65
  import { endModelStreamAtAbort } from './smartagent.modelabort.js';
65
66
  import { AgentModelCallUsageRecorder } from './smartagent.usage.js';
67
+ import {
68
+ assertAgentContextCompactionSetting,
69
+ assertAgentContextTokens,
70
+ estimateAgentContextTokens,
71
+ resolveAgentContextCompactionPoint,
72
+ type TAgentContextCompactionPoint,
73
+ } from './smartagent.contextcompaction.js';
66
74
  import { AgentToolCallScheduler } from './smartagent.toolscheduler.js';
67
75
  import type { IAgentToolExecutionOptions } from './smartagent.toolscheduler.js';
68
76
  import type {
@@ -130,6 +138,8 @@ interface IEffectiveGenerationRuntime {
130
138
  maxOutputTokens?: number;
131
139
  /** The generation's cache setting gives this provider cache hints: its prefix may be read back. */
132
140
  cachesPrefix: boolean;
141
+ /** Where the generation compacts settled history before its first inference. */
142
+ contextCompactionPoint: TAgentContextCompactionPoint;
133
143
  }
134
144
 
135
145
  interface IGenerationBackgroundJob {
@@ -273,6 +283,9 @@ const parseToolInput = (input: unknown): unknown => {
273
283
  }
274
284
  };
275
285
 
286
+ const textEncoder = new TextEncoder();
287
+ const utf8JsonBytes = (value: unknown): number => textEncoder.encode(JSON.stringify(value)).byteLength;
288
+
276
289
  const errorToString = (error: unknown): string =>
277
290
  error instanceof Error ? error.message : String(error);
278
291
 
@@ -341,6 +354,11 @@ export class AgentSessionEngine implements IAgentSession {
341
354
  private readonly events: TAgentEvent[] = [];
342
355
  private readonly eventIds = new Set<string>();
343
356
  private readonly generationHandles = new Map<string, IAgentGenerationHandle>();
357
+ /**
358
+ * The latest usage reading of each open transactional generation, written onto its outcome. It
359
+ * lives as long as the generation's handle: its outcome commit or the session's close ends both.
360
+ */
361
+ private readonly generationContextUsage = new Map<string, IAgentContextUsage>();
344
362
  private readonly unresolvedLeaseCleanups = new Set<IGenerationLeaseCleanupOwnership>();
345
363
  private sequence = 0;
346
364
  private persistenceRevision = 0;
@@ -420,14 +438,14 @@ export class AgentSessionEngine implements IAgentSession {
420
438
  if (!Number.isSafeInteger(maxContextOverflowRetries) || maxContextOverflowRetries < 0) {
421
439
  throw new Error('maxContextOverflowRetries must be a non-negative integer.');
422
440
  }
423
- if (options.contextCompactionBytes !== undefined && options.contextCompactionBytes !== false
424
- && (!Number.isSafeInteger(options.contextCompactionBytes)
425
- || options.contextCompactionBytes < 1 || options.contextCompactionBytes > 32 * 1024 * 1024)) {
426
- throw new Error('contextCompactionBytes must be false or an integer from 1 through 33554432.');
427
- }
428
- if (typeof options.contextCompactionBytes === 'number' && !options.contextCompactor) {
429
- throw new Error('contextCompactionBytes requires a contextCompactor.');
441
+ if (options.contextCompaction !== undefined) {
442
+ assertAgentContextCompactionSetting(options.contextCompaction);
443
+ if (options.contextCompaction !== false && !options.contextCompactor) {
444
+ throw new Error('contextCompaction requires a contextCompactor.');
445
+ }
430
446
  }
447
+ assertAgentContextTokens(options.contextWindow, 'contextWindow');
448
+ assertAgentContextTokens(options.contextCompactionDefaultTokens, 'contextCompactionDefaultTokens');
431
449
  if (options.attachmentResolver !== undefined) assertAttachmentResolver(options.attachmentResolver);
432
450
  const changeListenerTimeoutMs = options.changeListenerTimeoutMs ?? 30_000;
433
451
  if (!Number.isSafeInteger(changeListenerTimeoutMs) || changeListenerTimeoutMs <= 0) {
@@ -732,6 +750,7 @@ export class AgentSessionEngine implements IAgentSession {
732
750
  this.eventIds.add(event.id);
733
751
  if (event.type === 'generation-outcome') {
734
752
  this.generationHandles.delete(event.generationId);
753
+ this.generationContextUsage.delete(event.generationId);
735
754
  }
736
755
  }
737
756
  if (notify && committedEvents.length > 0) {
@@ -936,12 +955,14 @@ export class AgentSessionEngine implements IAgentSession {
936
955
  const parent = transaction.executionCompleted
937
956
  ?? transaction.executionStarted
938
957
  ?? transaction.begun;
958
+ const contextUsage = this.generationContextUsage.get(generationId);
939
959
  this.commitEvent(createAgentEvent<IGenerationOutcomeEvent>({
940
960
  type: 'generation-outcome',
941
961
  generationId,
942
962
  outcome,
943
963
  reason,
944
964
  ...(stopped ? { stopped: true } : {}),
965
+ ...(contextUsage ? { contextUsage } : {}),
945
966
  parentIds: [parent.id],
946
967
  }));
947
968
  await this.flushPersistence();
@@ -985,7 +1006,7 @@ export class AgentSessionEngine implements IAgentSession {
985
1006
  undefined,
986
1007
  options.stopped === true,
987
1008
  );
988
- if (this.options.contextCompactor && this.options.contextCompactionBytes !== false
1009
+ if (this.options.contextCompactor
989
1010
  && this.options.eventStore?.archive
990
1011
  && getOpenAgentGenerationTransactions(this.events).length === 0
991
1012
  && getUncertainToolExecutionIntents(this.events).length === 0) {
@@ -1100,6 +1121,37 @@ export class AgentSessionEngine implements IAgentSession {
1100
1121
  : buildModelMessages(visibleEvents);
1101
1122
  }
1102
1123
 
1124
+ /**
1125
+ * The session's context in tokens. The latest provider usage reading counts while the events it
1126
+ * saw still build the same model messages and no compaction followed them; what came after it
1127
+ * is estimated. Without such a reading the whole context is estimated.
1128
+ */
1129
+ private measureContextTokens(): { tokens: number; basis: 'usage' | 'estimate' } {
1130
+ const totalBytes = utf8JsonBytes(this.getModelMessages());
1131
+ const reading = this.latestContextUsage();
1132
+ if (reading && !this.events.some((event) =>
1133
+ event.type === 'context-compaction' && event.sequence! > reading.throughSequence)) {
1134
+ const readingBytes = utf8JsonBytes(this.buildContext(
1135
+ this.events.filter((event) => event.sequence! <= reading.throughSequence),
1136
+ ));
1137
+ if (readingBytes === reading.contextBytes) {
1138
+ return {
1139
+ tokens: reading.inputTokens + estimateAgentContextTokens(totalBytes - reading.contextBytes),
1140
+ basis: 'usage',
1141
+ };
1142
+ }
1143
+ }
1144
+ return { tokens: estimateAgentContextTokens(totalBytes), basis: 'estimate' };
1145
+ }
1146
+
1147
+ private latestContextUsage(): IAgentContextUsage | undefined {
1148
+ for (let index = this.events.length - 1; index >= 0; index--) {
1149
+ const event = this.events[index];
1150
+ if (event.type === 'generation-outcome' && event.contextUsage) return event.contextUsage;
1151
+ }
1152
+ return undefined;
1153
+ }
1154
+
1103
1155
  public subscribe(listener: TAgentSessionChangeListener): () => void {
1104
1156
  if (this.closed) throw new Error('AgentSession is closed.');
1105
1157
  const existing = this.listeners.get(listener);
@@ -2029,6 +2081,21 @@ export class AgentSessionEngine implements IAgentSession {
2029
2081
  },
2030
2082
  ],
2031
2083
  });
2084
+ if (lease && !lease.model
2085
+ && (lease.contextWindow !== undefined || lease.contextCompactionDefaultTokens !== undefined)) {
2086
+ throw new Error('A generation lease states a context window only together with its model.');
2087
+ }
2088
+ // The window belongs to the model: a lease or generate options naming a model name its window.
2089
+ const windowSource = lease?.model ? lease : options.model ? undefined : this.options;
2090
+ const contextCompactionPoint = resolveAgentContextCompactionPoint({
2091
+ ...(windowSource?.contextWindow === undefined ? {} : { contextWindow: windowSource.contextWindow }),
2092
+ ...(windowSource?.contextCompactionDefaultTokens === undefined
2093
+ ? {}
2094
+ : { contextCompactionDefaultTokens: windowSource.contextCompactionDefaultTokens }),
2095
+ ...((lease?.contextCompaction ?? this.options.contextCompaction) === undefined
2096
+ ? {}
2097
+ : { setting: lease?.contextCompaction ?? this.options.contextCompaction }),
2098
+ });
2032
2099
  return {
2033
2100
  model: effectiveModel,
2034
2101
  system,
@@ -2039,6 +2106,7 @@ export class AgentSessionEngine implements IAgentSession {
2039
2106
  ...(maxOutputTokens === undefined ? {} : { maxOutputTokens }),
2040
2107
  cachesPrefix: messageCacheProvider !== undefined
2041
2108
  || plugins.getSmartAiCacheProviderOptions({ provider: model.provider, modelId: model.modelId, cache }) !== undefined,
2109
+ contextCompactionPoint,
2042
2110
  };
2043
2111
  }
2044
2112
 
@@ -2153,6 +2221,9 @@ export class AgentSessionEngine implements IAgentSession {
2153
2221
  let retriedMs = 0;
2154
2222
  let contextOverflowRetries = 0;
2155
2223
  let automaticCompactionChecked = false;
2224
+ // The context the current inference sends, for its usage reading; only a transactional
2225
+ // generation's reading persists, on its outcome.
2226
+ let inferenceContext: Omit<IAgentContextUsage, 'inputTokens'> | undefined;
2156
2227
  let totalInput = 0;
2157
2228
  let totalOutput = 0;
2158
2229
  let totalCacheRead = 0;
@@ -2676,11 +2747,10 @@ export class AgentSessionEngine implements IAgentSession {
2676
2747
  ...(attachmentDownload ? { experimental_download: attachmentDownload } : {}),
2677
2748
  prepareStep: async () => {
2678
2749
  await applyPendingInput();
2679
- if (!automaticCompactionChecked && this.options.contextCompactor
2680
- && this.options.contextCompactionBytes !== false) {
2750
+ const compactionPoint = runtime.contextCompactionPoint;
2751
+ if (!automaticCompactionChecked && this.options.contextCompactor && 'tokens' in compactionPoint) {
2681
2752
  automaticCompactionChecked = true;
2682
- const bytes = new TextEncoder().encode(JSON.stringify(this.getModelMessages())).byteLength;
2683
- if (bytes > (this.options.contextCompactionBytes ?? 256 * 1024)) {
2753
+ if (this.measureContextTokens().tokens >= compactionPoint.tokens) {
2684
2754
  // The turns' tools let the summary call read the cached prefix; without a
2685
2755
  // cache they would only add input.
2686
2756
  await this.performCompaction(
@@ -2696,7 +2766,11 @@ export class AgentSessionEngine implements IAgentSession {
2696
2766
  }
2697
2767
  }
2698
2768
  beginInference();
2699
- return { messages: this.buildContext(this.eventsByIds(latestInferenceVisibleIds)) };
2769
+ const messages = this.buildContext(this.eventsByIds(latestInferenceVisibleIds));
2770
+ inferenceContext = options.transaction && this.options.contextCompactor
2771
+ ? { throughSequence: this.sequence, contextBytes: utf8JsonBytes(messages) }
2772
+ : undefined;
2773
+ return { messages };
2700
2774
  },
2701
2775
  onError: ({ error }) => {
2702
2776
  streamError = error;
@@ -2706,6 +2780,12 @@ export class AgentSessionEngine implements IAgentSession {
2706
2780
  },
2707
2781
  onLanguageModelCallEnd: ({ modelId, usage }) => {
2708
2782
  modelCalls.end(modelId, usage);
2783
+ const inputTokens = usage.inputTokens;
2784
+ // A call that ends after its generation's outcome was committed has nothing to update.
2785
+ if (inferenceContext && this.generationHandles.has(generationId) && typeof inputTokens === 'number'
2786
+ && Number.isSafeInteger(inputTokens) && inputTokens >= 0) {
2787
+ this.generationContextUsage.set(generationId, { inputTokens, ...inferenceContext });
2788
+ }
2709
2789
  },
2710
2790
  repairToolCall: async ({ toolCall, tools: availableTools, error }) => {
2711
2791
  const lowerName = toolCall.toolName.toLowerCase();
@@ -3291,6 +3371,7 @@ export class AgentSessionEngine implements IAgentSession {
3291
3371
  }
3292
3372
  }
3293
3373
  this.generationHandles.clear();
3374
+ this.generationContextUsage.clear();
3294
3375
  try {
3295
3376
  while (this.notificationDispatches.size > 0) {
3296
3377
  await Promise.all(this.notificationDispatches);
package/ts_agent/index.ts CHANGED
@@ -27,6 +27,20 @@ export { ToolRegistry } from './smartagent.classes.toolregistry.js';
27
27
  export { AgentToolCallScheduler } from './smartagent.toolscheduler.js';
28
28
  export type { IAgentToolExecutionOptions } from './smartagent.toolscheduler.js';
29
29
  export { AgentModelCallUsageRecorder } from './smartagent.usage.js';
30
+ export {
31
+ AGENT_CONTEXT_COMPACTION_CEILING_PERCENT,
32
+ AGENT_CONTEXT_ESTIMATE_BYTES_PER_TOKEN,
33
+ assertAgentContextCompactionSetting,
34
+ estimateAgentContextTokens,
35
+ getAgentContextCompactionCeiling,
36
+ resolveAgentContextCompactionPoint,
37
+ } from './smartagent.contextcompaction.js';
38
+ export type {
39
+ IAgentContextCompactionInput,
40
+ TAgentContextCompactionOff,
41
+ TAgentContextCompactionPoint,
42
+ TAgentContextCompactionSetting,
43
+ } from './smartagent.contextcompaction.js';
30
44
  export { assertAttachmentResolver, createAttachmentDownload } from './smartagent.attachments.js';
31
45
  export { endModelStreamAtAbort, MODEL_ABORT_GRACE_MS } from './smartagent.modelabort.js';
32
46
  export type { IAgentModelCallUsageRecorderModel } from './smartagent.usage.js';
@@ -106,6 +120,7 @@ export type {
106
120
  IGenerationBegunEvent,
107
121
  IGenerationExecutionCompletedEvent,
108
122
  IGenerationExecutionStartedEvent,
123
+ IAgentContextUsage,
109
124
  IGenerationOutcomeEvent,
110
125
  IModelMessageEvent,
111
126
  IModelMessagesToEventsOptions,
@@ -367,7 +367,7 @@ The steps of one generation read each URL once; a read that fails fails the step
367
367
 
368
368
  - `contextBuilder({ events })` controls the model-message projection.
369
369
  - `contextCompactor(messages, events, { reason, abortSignal, reportUsage })` returns replacement model messages. Provide it to use `session.compact()` or automatic event retention. Report the usage of its model calls through `reportUsage`; see [What is counted](#what-is-counted).
370
- - A compactor also enables proactive compaction with reason `context-budget` before inference. `contextCompactionBytes` defaults to 256 KiB of UTF-8 JSON model messages, accepts 1 through 32 MiB, and may be `false` to disable it. Only settled history is covered, never the current unsettled generation. Budget compactions carry `automatic: true`; after transactional finalization their covered events are archived when the store supports it and no open transaction or uncertain tool intent remains. Manual compaction is not automatically archived.
370
+ - A compactor also enables proactive compaction with reason `context-budget` before a generation's first inference, once the context reaches its compaction point in tokens. The point's ceiling is 90% of the served context window of the generation's model: `contextWindow` on the generation lease that names the model, or on the session options for the session model. The default is the ceiling, or `contextCompactionDefaultTokens` when lower; `contextCompaction` chooses `{ tokens }` (clamped to the ceiling, unclamped without a window), `{ percent }` (an integer from 1 through 90 of the window; none without one) or `false`. A lease's `contextCompaction` takes precedence over the session's. `resolveAgentContextCompactionPoint()` states the point. The context counts the input tokens of the latest transactional generation outcome's `contextUsage` while the events that call saw still build the same model messages and no compaction followed, plus an estimate of 4 UTF-8 JSON bytes per token for what came after; otherwise the whole context is estimated. Only settled history is covered, never the current unsettled generation. Budget compactions carry `automatic: true`; after transactional finalization their covered events are archived when the store supports it and no open transaction or uncertain tool intent remains. Manual compaction is not automatically archived.
371
371
  - `eventRetention: { maxEvents }` triggers compaction and archival when the active event count exceeds the threshold. It also requires an event store with `archive()` support.
372
372
  - Context overflow invokes the configured compactor, or the `onContextOverflow(messages, { abortSignal, reportUsage })` handler. Without either, generation throws `ContextOverflowError`. `maxContextOverflowRetries` defaults to `3`.
373
373
  - Open transactions and uncertain tool intents constrain when compaction and archival can proceed. Resolve them before manual compaction.
@@ -0,0 +1,127 @@
1
+ /**
2
+ * The proactive compaction point of a session, in tokens.
3
+ *
4
+ * The ceiling is 90% of the served context window of the model a generation runs on: the window
5
+ * the provider serves by default, never an extended maximum. A catalog that states its own
6
+ * automatic compaction point lowers the default, never the ceiling.
7
+ */
8
+
9
+ /** The share of the served context window that no compaction point exceeds. */
10
+ export const AGENT_CONTEXT_COMPACTION_CEILING_PERCENT = 90;
11
+
12
+ /**
13
+ * UTF-8 JSON bytes the estimate counts as one token. The estimate is used only where no provider
14
+ * usage reading covers the context; see `IAgentContextUsage`.
15
+ */
16
+ export const AGENT_CONTEXT_ESTIMATE_BYTES_PER_TOKEN = 4;
17
+
18
+ /**
19
+ * A session's choice of its compaction point.
20
+ *
21
+ * - `{ tokens }`: a positive safe integer, clamped to the ceiling of the model in use. Without a
22
+ * known served window it applies unclamped.
23
+ * - `{ percent }`: an integer from 1 through 90 of the served window. Without a known served
24
+ * window there is no proactive compaction.
25
+ * - `false`: no proactive compaction.
26
+ *
27
+ * Omitted, the model's default applies: the catalog's automatic compaction point when it states
28
+ * one, at most the ceiling, otherwise the ceiling itself.
29
+ */
30
+ export type TAgentContextCompactionSetting =
31
+ | { readonly tokens: number }
32
+ | { readonly percent: number }
33
+ | false;
34
+
35
+ /** Why a generation has no proactive compaction point. */
36
+ export type TAgentContextCompactionOff = 'disabled' | 'no-context-window';
37
+
38
+ /** The compaction point of a generation as resolved for its model. */
39
+ export type TAgentContextCompactionPoint =
40
+ | { readonly tokens: number }
41
+ | { readonly off: TAgentContextCompactionOff };
42
+
43
+ /** What the model of a generation states about its context, and the session's setting. */
44
+ export interface IAgentContextCompactionInput {
45
+ /** The served context window in tokens. */
46
+ contextWindow?: number;
47
+ /** The catalog's own automatic compaction point in tokens, when it states one. */
48
+ contextCompactionDefaultTokens?: number;
49
+ /** The session's setting; omitted for the model's default. */
50
+ setting?: TAgentContextCompactionSetting;
51
+ }
52
+
53
+ const isPositiveTokenCount = (value: unknown): value is number =>
54
+ typeof value === 'number' && Number.isSafeInteger(value) && value >= 1;
55
+
56
+ /** Throws unless `value` is a valid `TAgentContextCompactionSetting`. `path` names it in the message. */
57
+ export function assertAgentContextCompactionSetting(
58
+ value: unknown,
59
+ path = 'contextCompaction',
60
+ ): asserts value is TAgentContextCompactionSetting {
61
+ if (value === false) return;
62
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) {
63
+ throw new Error(`${path} must be false, { tokens } or { percent }.`);
64
+ }
65
+ const keys = Object.keys(value);
66
+ if (keys.length !== 1 || (keys[0] !== 'tokens' && keys[0] !== 'percent')) {
67
+ throw new Error(`${path} must be false, { tokens } or { percent }.`);
68
+ }
69
+ const record = value as Record<string, unknown>;
70
+ if (keys[0] === 'tokens') {
71
+ if (!isPositiveTokenCount(record.tokens)) throw new Error(`${path}.tokens must be a positive integer.`);
72
+ return;
73
+ }
74
+ const percent = record.percent;
75
+ if (
76
+ typeof percent !== 'number' || !Number.isInteger(percent)
77
+ || percent < 1 || percent > AGENT_CONTEXT_COMPACTION_CEILING_PERCENT
78
+ ) {
79
+ throw new Error(`${path}.percent must be an integer from 1 through ${AGENT_CONTEXT_COMPACTION_CEILING_PERCENT}.`);
80
+ }
81
+ }
82
+
83
+ /** Throws unless `value` is a positive token count or undefined. */
84
+ export function assertAgentContextTokens(value: unknown, path: string): asserts value is number | undefined {
85
+ if (value !== undefined && !isPositiveTokenCount(value)) {
86
+ throw new Error(`${path} must be a positive integer.`);
87
+ }
88
+ }
89
+
90
+ const shareOf = (contextWindow: number, percent: number): number =>
91
+ Math.max(1, Math.floor(contextWindow * percent / 100));
92
+
93
+ /** The highest compaction point of a served window: 90% of it. */
94
+ export function getAgentContextCompactionCeiling(contextWindow: number): number {
95
+ assertAgentContextTokens(contextWindow, 'contextWindow');
96
+ return shareOf(contextWindow, AGENT_CONTEXT_COMPACTION_CEILING_PERCENT);
97
+ }
98
+
99
+ /**
100
+ * The compaction point a generation uses. Pure: a host may call it to show the point a session
101
+ * would have on a model before any run.
102
+ */
103
+ export function resolveAgentContextCompactionPoint(
104
+ input: IAgentContextCompactionInput,
105
+ ): TAgentContextCompactionPoint {
106
+ const { contextWindow, contextCompactionDefaultTokens, setting } = input;
107
+ assertAgentContextTokens(contextWindow, 'contextWindow');
108
+ assertAgentContextTokens(contextCompactionDefaultTokens, 'contextCompactionDefaultTokens');
109
+ if (setting !== undefined) assertAgentContextCompactionSetting(setting);
110
+ if (setting === false) return { off: 'disabled' };
111
+ if (setting !== undefined && 'tokens' in setting) {
112
+ return { tokens: contextWindow === undefined
113
+ ? setting.tokens
114
+ : Math.min(setting.tokens, getAgentContextCompactionCeiling(contextWindow)) };
115
+ }
116
+ if (contextWindow === undefined) return { off: 'no-context-window' };
117
+ if (setting !== undefined) return { tokens: shareOf(contextWindow, setting.percent) };
118
+ const ceiling = getAgentContextCompactionCeiling(contextWindow);
119
+ return { tokens: contextCompactionDefaultTokens === undefined
120
+ ? ceiling
121
+ : Math.min(contextCompactionDefaultTokens, ceiling) };
122
+ }
123
+
124
+ /** The estimated tokens of `bytes` UTF-8 JSON bytes. */
125
+ export function estimateAgentContextTokens(bytes: number): number {
126
+ return Math.ceil(Math.max(0, bytes) / AGENT_CONTEXT_ESTIMATE_BYTES_PER_TOKEN);
127
+ }
@@ -113,6 +113,22 @@ export interface IGenerationOutcomeEvent extends IAgentEventBase {
113
113
  * stays in the model context.
114
114
  */
115
115
  stopped?: boolean;
116
+ /** The provider's usage reading of the generation's last model call that reported one. */
117
+ contextUsage?: IAgentContextUsage;
118
+ }
119
+
120
+ /**
121
+ * How large one model call's context was, as its provider reported it. It measures the session's
122
+ * context as long as the events it saw still build the same model messages and no compaction
123
+ * followed them.
124
+ */
125
+ export interface IAgentContextUsage {
126
+ /** Input tokens the provider reported for the call, cache reads and writes included. */
127
+ inputTokens: number;
128
+ /** The `sequence` of the last event the call's input could see. */
129
+ throughSequence: number;
130
+ /** UTF-8 JSON bytes of the model messages the call's input carried. */
131
+ contextBytes: number;
116
132
  }
117
133
 
118
134
  export interface IToolExecutionIntentEvent extends IAgentEventBase {
@@ -21,6 +21,7 @@ import type {
21
21
  import type { IAgentEventArchive, IAgentEventStore } from './smartagent.persistence.js';
22
22
  import type { AgentPendingInputQueue, IAgentAppliedInput } from './smartagent.pendinginput.js';
23
23
  import type { IAgentRetryEvent } from './smartagent.retry.js';
24
+ import type { TAgentContextCompactionSetting } from './smartagent.contextcompaction.js';
24
25
 
25
26
  export type { ProviderOptions, ISmartAiCacheDispatch, TSmartAiCacheBudgetBasis };
26
27
  export interface IAgentCacheOptions extends ISmartAiCacheOptions {}
@@ -282,11 +283,17 @@ export interface IAgentSessionOptions {
282
283
  contextBuilder?: TAgentContextBuilder;
283
284
  /** Explicit context compactor used by manual and event-retention compaction. */
284
285
  contextCompactor?: TAgentContextCompactor;
285
- /** Compact settled history before inference when model messages exceed this UTF-8 JSON byte budget.
286
- * Defaults to 256 KiB when a compactor is supplied; false disables proactive compaction.
287
- * The current unsettled generation is never summarized or archived.
286
+ /**
287
+ * Compacts settled history before a generation's first inference once the context reaches the
288
+ * compaction point, in tokens; see `TAgentContextCompactionSetting`. Requires a
289
+ * `contextCompactor`; omitted, the model's default applies. A generation lease's setting takes
290
+ * precedence. The current unsettled generation is never summarized or archived.
288
291
  */
289
- contextCompactionBytes?: number | false;
292
+ contextCompaction?: TAgentContextCompactionSetting;
293
+ /** The served context window of `model` in tokens; a generation lease's window takes precedence. */
294
+ contextWindow?: number;
295
+ /** The catalog's automatic compaction point of `model` in tokens; a lease's value takes precedence. */
296
+ contextCompactionDefaultTokens?: number;
290
297
  /** Optional bounded active-event policy. Requires contextCompactor and eventStore.archive. */
291
298
  eventRetention?: IAgentEventRetentionOptions;
292
299
  /** Maximum wait for each session change listener. Default: 30 seconds. */
@@ -415,6 +422,16 @@ export interface IAgentGenerationLease {
415
422
  maxSteps?: number;
416
423
  /** Caps the output tokens of each model call of the generation; the provider's limit otherwise. */
417
424
  maxOutputTokens?: number;
425
+ /**
426
+ * The served context window of the lease's model in tokens: the window the provider serves by
427
+ * default, never an extended maximum. Stated together with `model`; a lease with a model and
428
+ * no window has no known window.
429
+ */
430
+ contextWindow?: number;
431
+ /** The catalog's automatic compaction point of the lease's model in tokens, when it states one. */
432
+ contextCompactionDefaultTokens?: number;
433
+ /** The compaction setting of this generation; takes precedence over the session's. */
434
+ contextCompaction?: TAgentContextCompactionSetting;
418
435
  /**
419
436
  * Must be safe to call repeatedly and concurrently after failure or timeout.
420
437
  * A timeout does not cancel the original close attempt, so a retry may overlap it.
@@ -510,6 +510,15 @@ const assertAgentEvent: (
510
510
  if (eventValue.stopped !== undefined && (
511
511
  eventValue.stopped !== true || eventValue.outcome !== 'interrupted'
512
512
  )) validationError(`${eventPath}.stopped`, 'is only valid as true on an interrupted outcome.');
513
+ if (eventValue.contextUsage !== undefined) {
514
+ assertRecord(eventValue.contextUsage, `${eventPath}.contextUsage`);
515
+ for (const key of ['inputTokens', 'throughSequence', 'contextBytes'] as const) {
516
+ const count = eventValue.contextUsage[key];
517
+ if (typeof count !== 'number' || !Number.isSafeInteger(count) || count < 0) {
518
+ validationError(`${eventPath}.contextUsage.${key}`, 'must be a non-negative integer.');
519
+ }
520
+ }
521
+ }
513
522
  break;
514
523
  case 'tool-execution-intent':
515
524
  assertRequiredGenerationId(eventValue, eventPath);