@modelprofile.com/flexharness-agent 14.0.0 → 16.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.
- package/dist_ts_agent/classes.sessionengine.d.ts +16 -2
- package/dist_ts_agent/classes.sessionengine.js +97 -23
- package/dist_ts_agent/index.d.ts +4 -2
- package/dist_ts_agent/index.js +2 -1
- package/dist_ts_agent/smartagent.contextcompaction.d.ts +61 -0
- package/dist_ts_agent/smartagent.contextcompaction.js +81 -0
- package/dist_ts_agent/smartagent.events.d.ts +15 -0
- package/dist_ts_agent/smartagent.events.js +1 -1
- package/dist_ts_agent/smartagent.interfaces.d.ts +26 -4
- package/dist_ts_agent/smartagent.interfaces.js +1 -1
- package/dist_ts_agent/smartagent.persistence.js +10 -1
- package/package.json +2 -2
- package/readme.md +9 -1
- package/ts_agent/classes.sessionengine.ts +112 -19
- package/ts_agent/index.ts +16 -0
- package/ts_agent/readme.md +9 -1
- package/ts_agent/smartagent.contextcompaction.ts +127 -0
- package/ts_agent/smartagent.events.ts +16 -0
- package/ts_agent/smartagent.interfaces.ts +27 -4
- package/ts_agent/smartagent.persistence.ts +9 -0
|
@@ -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,
|
|
@@ -39,7 +40,7 @@ import {
|
|
|
39
40
|
type IAgentCompactOptions,
|
|
40
41
|
type IAgentBeginGenerationOptions,
|
|
41
42
|
type IAgentFinalizeGenerationOptions,
|
|
42
|
-
type
|
|
43
|
+
type IAgentContinuationSession,
|
|
43
44
|
type IAgentSessionAbortOptions,
|
|
44
45
|
type IAgentSessionChange,
|
|
45
46
|
type IAgentSessionOptions,
|
|
@@ -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
|
|
|
@@ -336,11 +349,16 @@ const recordToolCall = (
|
|
|
336
349
|
toolCallIndexes.set(toolCallId, toolCalls.length - 1);
|
|
337
350
|
};
|
|
338
351
|
|
|
339
|
-
export class AgentSessionEngine implements
|
|
352
|
+
export class AgentSessionEngine implements IAgentContinuationSession {
|
|
340
353
|
private readonly options: IAgentSessionOptions;
|
|
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.
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
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) {
|
|
@@ -849,6 +868,17 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
849
868
|
public beginGeneration(
|
|
850
869
|
content: TAgentPrompt,
|
|
851
870
|
options: IAgentBeginGenerationOptions = {},
|
|
871
|
+
): Promise<IAgentGenerationHandle> {
|
|
872
|
+
return this.beginGenerationTransaction(content, options);
|
|
873
|
+
}
|
|
874
|
+
|
|
875
|
+
public beginContinuation(options: IAgentBeginGenerationOptions = {}): Promise<IAgentGenerationHandle> {
|
|
876
|
+
return this.beginGenerationTransaction(undefined, options);
|
|
877
|
+
}
|
|
878
|
+
|
|
879
|
+
private beginGenerationTransaction(
|
|
880
|
+
content: TAgentPrompt | undefined,
|
|
881
|
+
options: IAgentBeginGenerationOptions,
|
|
852
882
|
): Promise<IAgentGenerationHandle> {
|
|
853
883
|
return this.queueExclusive(async () => {
|
|
854
884
|
await this.flushPersistence();
|
|
@@ -864,7 +894,9 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
864
894
|
&& event.generationId === generationId
|
|
865
895
|
&& event.causationId === existingTransaction.begun.id);
|
|
866
896
|
const handle = this.generationHandles.get(generationId);
|
|
867
|
-
if (handle &&
|
|
897
|
+
if (handle && (content === undefined
|
|
898
|
+
? existingMessage === undefined
|
|
899
|
+
: existingMessage && this.platform.isDeepEqual(existingMessage.content, content))) {
|
|
868
900
|
return handle;
|
|
869
901
|
}
|
|
870
902
|
throw new Error(
|
|
@@ -888,14 +920,13 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
888
920
|
claimTokenDigest,
|
|
889
921
|
parentIds: priorEvent ? [priorEvent.id] : undefined,
|
|
890
922
|
});
|
|
891
|
-
|
|
923
|
+
this.commitEvents(content === undefined ? [begun] : [begun, createAgentEvent<IUserMessageEvent>({
|
|
892
924
|
type: 'user-message',
|
|
893
925
|
content,
|
|
894
926
|
generationId,
|
|
895
927
|
causationId: begun.id,
|
|
896
928
|
parentIds: [begun.id],
|
|
897
|
-
});
|
|
898
|
-
this.commitEvents([begun, userMessage]);
|
|
929
|
+
})]);
|
|
899
930
|
const handle = Object.freeze({ generationId, claimToken });
|
|
900
931
|
this.generationHandles.set(generationId, handle);
|
|
901
932
|
await this.flushPersistence();
|
|
@@ -936,12 +967,14 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
936
967
|
const parent = transaction.executionCompleted
|
|
937
968
|
?? transaction.executionStarted
|
|
938
969
|
?? transaction.begun;
|
|
970
|
+
const contextUsage = this.generationContextUsage.get(generationId);
|
|
939
971
|
this.commitEvent(createAgentEvent<IGenerationOutcomeEvent>({
|
|
940
972
|
type: 'generation-outcome',
|
|
941
973
|
generationId,
|
|
942
974
|
outcome,
|
|
943
975
|
reason,
|
|
944
976
|
...(stopped ? { stopped: true } : {}),
|
|
977
|
+
...(contextUsage ? { contextUsage } : {}),
|
|
945
978
|
parentIds: [parent.id],
|
|
946
979
|
}));
|
|
947
980
|
await this.flushPersistence();
|
|
@@ -985,7 +1018,7 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
985
1018
|
undefined,
|
|
986
1019
|
options.stopped === true,
|
|
987
1020
|
);
|
|
988
|
-
if (this.options.contextCompactor
|
|
1021
|
+
if (this.options.contextCompactor
|
|
989
1022
|
&& this.options.eventStore?.archive
|
|
990
1023
|
&& getOpenAgentGenerationTransactions(this.events).length === 0
|
|
991
1024
|
&& getUncertainToolExecutionIntents(this.events).length === 0) {
|
|
@@ -1100,6 +1133,37 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
1100
1133
|
: buildModelMessages(visibleEvents);
|
|
1101
1134
|
}
|
|
1102
1135
|
|
|
1136
|
+
/**
|
|
1137
|
+
* The session's context in tokens. The latest provider usage reading counts while the events it
|
|
1138
|
+
* saw still build the same model messages and no compaction followed them; what came after it
|
|
1139
|
+
* is estimated. Without such a reading the whole context is estimated.
|
|
1140
|
+
*/
|
|
1141
|
+
private measureContextTokens(): { tokens: number; basis: 'usage' | 'estimate' } {
|
|
1142
|
+
const totalBytes = utf8JsonBytes(this.getModelMessages());
|
|
1143
|
+
const reading = this.latestContextUsage();
|
|
1144
|
+
if (reading && !this.events.some((event) =>
|
|
1145
|
+
event.type === 'context-compaction' && event.sequence! > reading.throughSequence)) {
|
|
1146
|
+
const readingBytes = utf8JsonBytes(this.buildContext(
|
|
1147
|
+
this.events.filter((event) => event.sequence! <= reading.throughSequence),
|
|
1148
|
+
));
|
|
1149
|
+
if (readingBytes === reading.contextBytes) {
|
|
1150
|
+
return {
|
|
1151
|
+
tokens: reading.inputTokens + estimateAgentContextTokens(totalBytes - reading.contextBytes),
|
|
1152
|
+
basis: 'usage',
|
|
1153
|
+
};
|
|
1154
|
+
}
|
|
1155
|
+
}
|
|
1156
|
+
return { tokens: estimateAgentContextTokens(totalBytes), basis: 'estimate' };
|
|
1157
|
+
}
|
|
1158
|
+
|
|
1159
|
+
private latestContextUsage(): IAgentContextUsage | undefined {
|
|
1160
|
+
for (let index = this.events.length - 1; index >= 0; index--) {
|
|
1161
|
+
const event = this.events[index];
|
|
1162
|
+
if (event.type === 'generation-outcome' && event.contextUsage) return event.contextUsage;
|
|
1163
|
+
}
|
|
1164
|
+
return undefined;
|
|
1165
|
+
}
|
|
1166
|
+
|
|
1103
1167
|
public subscribe(listener: TAgentSessionChangeListener): () => void {
|
|
1104
1168
|
if (this.closed) throw new Error('AgentSession is closed.');
|
|
1105
1169
|
const existing = this.listeners.get(listener);
|
|
@@ -2029,6 +2093,21 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
2029
2093
|
},
|
|
2030
2094
|
],
|
|
2031
2095
|
});
|
|
2096
|
+
if (lease && !lease.model
|
|
2097
|
+
&& (lease.contextWindow !== undefined || lease.contextCompactionDefaultTokens !== undefined)) {
|
|
2098
|
+
throw new Error('A generation lease states a context window only together with its model.');
|
|
2099
|
+
}
|
|
2100
|
+
// The window belongs to the model: a lease or generate options naming a model name its window.
|
|
2101
|
+
const windowSource = lease?.model ? lease : options.model ? undefined : this.options;
|
|
2102
|
+
const contextCompactionPoint = resolveAgentContextCompactionPoint({
|
|
2103
|
+
...(windowSource?.contextWindow === undefined ? {} : { contextWindow: windowSource.contextWindow }),
|
|
2104
|
+
...(windowSource?.contextCompactionDefaultTokens === undefined
|
|
2105
|
+
? {}
|
|
2106
|
+
: { contextCompactionDefaultTokens: windowSource.contextCompactionDefaultTokens }),
|
|
2107
|
+
...((lease?.contextCompaction ?? this.options.contextCompaction) === undefined
|
|
2108
|
+
? {}
|
|
2109
|
+
: { setting: lease?.contextCompaction ?? this.options.contextCompaction }),
|
|
2110
|
+
});
|
|
2032
2111
|
return {
|
|
2033
2112
|
model: effectiveModel,
|
|
2034
2113
|
system,
|
|
@@ -2039,6 +2118,7 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
2039
2118
|
...(maxOutputTokens === undefined ? {} : { maxOutputTokens }),
|
|
2040
2119
|
cachesPrefix: messageCacheProvider !== undefined
|
|
2041
2120
|
|| plugins.getSmartAiCacheProviderOptions({ provider: model.provider, modelId: model.modelId, cache }) !== undefined,
|
|
2121
|
+
contextCompactionPoint,
|
|
2042
2122
|
};
|
|
2043
2123
|
}
|
|
2044
2124
|
|
|
@@ -2153,6 +2233,9 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
2153
2233
|
let retriedMs = 0;
|
|
2154
2234
|
let contextOverflowRetries = 0;
|
|
2155
2235
|
let automaticCompactionChecked = false;
|
|
2236
|
+
// The context the current inference sends, for its usage reading; only a transactional
|
|
2237
|
+
// generation's reading persists, on its outcome.
|
|
2238
|
+
let inferenceContext: Omit<IAgentContextUsage, 'inputTokens'> | undefined;
|
|
2156
2239
|
let totalInput = 0;
|
|
2157
2240
|
let totalOutput = 0;
|
|
2158
2241
|
let totalCacheRead = 0;
|
|
@@ -2676,11 +2759,10 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
2676
2759
|
...(attachmentDownload ? { experimental_download: attachmentDownload } : {}),
|
|
2677
2760
|
prepareStep: async () => {
|
|
2678
2761
|
await applyPendingInput();
|
|
2679
|
-
|
|
2680
|
-
|
|
2762
|
+
const compactionPoint = runtime.contextCompactionPoint;
|
|
2763
|
+
if (!automaticCompactionChecked && this.options.contextCompactor && 'tokens' in compactionPoint) {
|
|
2681
2764
|
automaticCompactionChecked = true;
|
|
2682
|
-
|
|
2683
|
-
if (bytes > (this.options.contextCompactionBytes ?? 256 * 1024)) {
|
|
2765
|
+
if (this.measureContextTokens().tokens >= compactionPoint.tokens) {
|
|
2684
2766
|
// The turns' tools let the summary call read the cached prefix; without a
|
|
2685
2767
|
// cache they would only add input.
|
|
2686
2768
|
await this.performCompaction(
|
|
@@ -2696,7 +2778,11 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
2696
2778
|
}
|
|
2697
2779
|
}
|
|
2698
2780
|
beginInference();
|
|
2699
|
-
|
|
2781
|
+
const messages = this.buildContext(this.eventsByIds(latestInferenceVisibleIds));
|
|
2782
|
+
inferenceContext = options.transaction && this.options.contextCompactor
|
|
2783
|
+
? { throughSequence: this.sequence, contextBytes: utf8JsonBytes(messages) }
|
|
2784
|
+
: undefined;
|
|
2785
|
+
return { messages };
|
|
2700
2786
|
},
|
|
2701
2787
|
onError: ({ error }) => {
|
|
2702
2788
|
streamError = error;
|
|
@@ -2706,6 +2792,12 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
2706
2792
|
},
|
|
2707
2793
|
onLanguageModelCallEnd: ({ modelId, usage }) => {
|
|
2708
2794
|
modelCalls.end(modelId, usage);
|
|
2795
|
+
const inputTokens = usage.inputTokens;
|
|
2796
|
+
// A call that ends after its generation's outcome was committed has nothing to update.
|
|
2797
|
+
if (inferenceContext && this.generationHandles.has(generationId) && typeof inputTokens === 'number'
|
|
2798
|
+
&& Number.isSafeInteger(inputTokens) && inputTokens >= 0) {
|
|
2799
|
+
this.generationContextUsage.set(generationId, { inputTokens, ...inferenceContext });
|
|
2800
|
+
}
|
|
2709
2801
|
},
|
|
2710
2802
|
repairToolCall: async ({ toolCall, tools: availableTools, error }) => {
|
|
2711
2803
|
const lowerName = toolCall.toolName.toLowerCase();
|
|
@@ -3291,6 +3383,7 @@ export class AgentSessionEngine implements IAgentSession {
|
|
|
3291
3383
|
}
|
|
3292
3384
|
}
|
|
3293
3385
|
this.generationHandles.clear();
|
|
3386
|
+
this.generationContextUsage.clear();
|
|
3294
3387
|
try {
|
|
3295
3388
|
while (this.notificationDispatches.size > 0) {
|
|
3296
3389
|
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';
|
|
@@ -65,6 +79,7 @@ export type {
|
|
|
65
79
|
IAgentRunOptions,
|
|
66
80
|
IAgentRunResult,
|
|
67
81
|
IAgentSession,
|
|
82
|
+
IAgentContinuationSession,
|
|
68
83
|
IAgentSessionAbortOptions,
|
|
69
84
|
IAgentSessionChange,
|
|
70
85
|
IAgentSessionOptions,
|
|
@@ -106,6 +121,7 @@ export type {
|
|
|
106
121
|
IGenerationBegunEvent,
|
|
107
122
|
IGenerationExecutionCompletedEvent,
|
|
108
123
|
IGenerationExecutionStartedEvent,
|
|
124
|
+
IAgentContextUsage,
|
|
109
125
|
IGenerationOutcomeEvent,
|
|
110
126
|
IModelMessageEvent,
|
|
111
127
|
IModelMessagesToEventsOptions,
|
package/ts_agent/readme.md
CHANGED
|
@@ -282,6 +282,14 @@ The `review` callback belongs to your application. While awaiting acceptance, `c
|
|
|
282
282
|
|
|
283
283
|
`generate({ transaction, stop })` takes a second signal for the owner's stop, the way a user stops a turn. It ends the generation like `abort`, but the interrupted outcome records the stop (`stopped: true`, also accepted by `finalizeGeneration(transaction, 'interrupted', { stopped: true })` for a generation stopped after its execution completed). A stopped generation stays in future context once its model produced output: its prompt, the input it took in, the text its running model step streamed and the tool calls it issued. Each tool call without a recorded result is closed with an error result saying its effect is unknown, so the next request is well-formed for every provider. A generation stopped before any model output leaves no trace, so its prompt can be sent again without appearing twice. `isGenerationInModelContext(events, generationId)` applies the same rule to a list of events, for a caller that needs to know whether a finished generation stayed in context. The same retention rule applies to aborted, failed, rejected and restart-interrupted generations once execution produced model/tool output, including recorded partial inference output. Model-visible outcome markers distinguish rejected, interrupted and stopped-by-owner work from successful completion. Synthetic unknown-effect results only close the model protocol: they are not evidence that an external effect happened or did not happen, and never trigger automatic tool replay. `stop` requires a transactional generation.
|
|
284
284
|
|
|
285
|
+
`beginContinuation({ generationId })` on the built-in `AgentSession` claims a generation
|
|
286
|
+
without appending a user message, through the same transactional execution, scheduling
|
|
287
|
+
and finalization. It writes only the existing `generation-begun` event; no event schema
|
|
288
|
+
changes. The managing harness owns validation that an unanswered turn exists.
|
|
289
|
+
`IAgentContinuationSession` extends `IAgentSession` with this additional capability;
|
|
290
|
+
`IAgentSession.beginGeneration(content: TAgentPrompt, options?)` keeps its existing
|
|
291
|
+
contract, so existing session implementers do not need to support missing input.
|
|
292
|
+
|
|
285
293
|
Closing a session or restoring a stored session interrupts unfinished transactions. Restoration does not automatically rerun them. Persisted transactions require an event store; without one, transactions are process-local.
|
|
286
294
|
|
|
287
295
|
A rejected generation does not roll back external tool effects. The runtime records transactional tool-execution intents and results. If a crash leaves an intent without a known result, inspect `listUncertainToolExecutions()` and reconcile the external operation through `reconcileToolExecution()` before treating its outcome as known. This is not a general exactly-once guarantee for external services.
|
|
@@ -367,7 +375,7 @@ The steps of one generation read each URL once; a read that fails fails the step
|
|
|
367
375
|
|
|
368
376
|
- `contextBuilder({ events })` controls the model-message projection.
|
|
369
377
|
- `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. `
|
|
378
|
+
- 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
379
|
- `eventRetention: { maxEvents }` triggers compaction and archival when the active event count exceeds the threshold. It also requires an event store with `archive()` support.
|
|
372
380
|
- Context overflow invokes the configured compactor, or the `onContextOverflow(messages, { abortSignal, reportUsage })` handler. Without either, generation throws `ContextOverflowError`. `maxContextOverflowRetries` defaults to `3`.
|
|
373
381
|
- 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
|
-
/**
|
|
286
|
-
*
|
|
287
|
-
*
|
|
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
|
-
|
|
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.
|
|
@@ -612,6 +629,12 @@ export interface IAgentSession {
|
|
|
612
629
|
close(): Promise<void>;
|
|
613
630
|
}
|
|
614
631
|
|
|
632
|
+
/** Additional capability implemented by built-in sessions; existing IAgentSession implementers are unchanged. */
|
|
633
|
+
export interface IAgentContinuationSession extends IAgentSession {
|
|
634
|
+
/** Claims a generation from existing context without appending a user message. */
|
|
635
|
+
beginContinuation(options?: IAgentBeginGenerationOptions): Promise<IAgentGenerationHandle>;
|
|
636
|
+
}
|
|
637
|
+
|
|
615
638
|
export class ContextOverflowError extends Error {
|
|
616
639
|
constructor(message = 'Agent context limit reached and no onContextOverflow handler provided') {
|
|
617
640
|
super(message);
|
|
@@ -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);
|