@modelprofile.com/flexharness-agent 13.3.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.
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,
@@ -11,7 +11,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
11
11
  | A CLI command or background worker that investigates a task | `runAgent` runs several model/tool steps and closes its session when it finishes or fails. |
12
12
  | A support assistant or application copilot with follow-up questions | `AgentSession` keeps the conversation, serializes generations and exposes events for your UI or application. |
13
13
  | A job that must return an application-validated answer | `validateCompletion` can accept an answer or request a bounded correction. |
14
- | A workflow that reviews a draft before accepting it into future context | Transactional generations separate model execution from the host's acceptance decision. |
14
+ | A workflow that records a reviewed draft's outcome | Transactional generations separate execution from acceptance while retaining actual unsuccessful work truthfully. |
15
15
  | An application with its own storage, permissions or execution infrastructure | Supply tools, an event store and execution-context contracts while retaining control of those services. |
16
16
  | A browser assistant using an application-controlled model transport | The `/runner` entrypoint provides the same task loop without Node session dependencies. |
17
17
 
@@ -253,7 +253,7 @@ Validation retries retain the conversation and accumulate usage, steps and tool-
253
253
 
254
254
  ## Review a generation before accepting it
255
255
 
256
- A transactional generation gives the host an explicit acceptance boundary. This is useful when an application must review or durably stage an answer before including it in future model context.
256
+ A transactional generation gives the host an explicit acceptance boundary for reviewing or durably staging an answer. Acceptance records success; rejecting an answer does not erase the model/tool work that actually occurred.
257
257
 
258
258
  ```typescript
259
259
  export async function createReviewedDraft(
@@ -278,9 +278,9 @@ export async function createReviewedDraft(
278
278
  }
279
279
  ```
280
280
 
281
- The `review` callback belongs to your application. While awaiting acceptance, `candidate.messages` includes the candidate, but `getModelMessages()` excludes it from ordinary future context. Acceptance includes the generation; rejection keeps it in the canonical event history while excluding it from future context. Generation IDs identify transactions within a session; use a distinct ID for each new transaction.
281
+ The `review` callback belongs to your application. While awaiting acceptance, `candidate.messages` includes the candidate, but `getModelMessages()` excludes it from ordinary future context. Acceptance includes the generation as successful. Rejection retains actual model/tool output and its prompt and applied input in future context with a truthful rejected outcome marker. Unsuccessful generations without output remain excluded. Generation IDs identify transactions within a session; use a distinct ID for each new transaction.
282
282
 
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. Aborted and failed generations, and generations a restart interrupted, stay out of future context as before. `stop` requires a transactional generation.
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
285
  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
286
 
@@ -308,7 +308,7 @@ await generation;
308
308
  const unapplied = pendingInput.close(); // input the generation never took in
309
309
  ```
310
310
 
311
- The generation closes the queue when it ends, whether it completed, failed or was aborted. `close()` returns the inputs it never took in, the same list on every call once the generation has ended; input that arrives during the last model step is among them, and so is input the generation drained but could not record durably. After closing, `add()` throws `AgentPendingInputRejectedError` with reason `closed`, and a reused `inputId` is refused with reason `duplicate`. The caller decides what becomes of unapplied input, for example sending it as the next turn.
311
+ The generation closes the queue when it ends, whether it completed, failed or was aborted. `close()` returns the inputs it never took in, the same list on every call once the generation has ended; input that arrives during the last model step is among them, and so is input the generation drained but could not record durably. After closing, `add()` throws `AgentPendingInputRejectedError` with reason `closed`, and a reused `inputId` is refused with reason `duplicate`. The caller decides what becomes of unapplied input, for example explicitly sending it as the next turn. In FlexHarness, `keptInContext` reports canonical retention, not success: applied steers in retained unsuccessful history are not `unappliedSteerIds`; input never durably applied is listed, and all accepted steers are listed when the generation is not retained. Do not automatically resend retained input or replay tool effects. FlexHarness undo/redo hides/restores grouped unsuccessful history and its outcome markers; a new branch excludes the hidden history. This changes context, not external effects without a workspace reversion provider.
312
312
 
313
313
  ## Events, storage and context
314
314
 
@@ -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.
@@ -409,7 +409,7 @@ Tools and resource callbacks must observe their supplied abort signals. A model
409
409
 
410
410
  The runtime retries a model call that failed with a rate limit (429), an overloaded provider (529) or an unavailable one (503) at most 8 times, waiting for the provider's `retry-after` delay but at least the backoff that doubles from 2 s to 30 s. A requested delay beyond 60 s, or one that would take the call's retries past 150 s in total, fails the generation: a rate limit (429) as a `ModelLimitError` of kind `rate_limit` carrying that retry time, a 503 or 529 with the provider error. A `ModelLimitError` of kind `usage_limit`, which the provider adapters raise for a spent quota, is never retried. Completed tool results are preserved during a generation's retry sequence. A ledger reuses an already observed execution for the same tool-call identity. Applications still need their own idempotency and recovery rules for external side effects.
411
411
 
412
- `maxSteps` defaults to `20` and limits completed model steps per generation. Prompt-cache handling defaults to `cache: 'auto'`; use `cache: false` to disable the runtime's cache defaults, or pass an explicit cache policy (`ISmartAiCacheOptions` of `@modelprofile.com/flexharness-models`). On OpenAI a generation's `prompt_cache_key` is derived from its instructions and tool definitions, so sessions with one prefix share the provider's cache; `keyScope`, `keyBuckets` and `key` adjust it.
412
+ `maxSteps` has **no default limit**. It is an optional positive finite safe integer limiting completed model steps per generation; `0`, negatives, fractions, `NaN`, infinity and unsafe integers are invalid. Resolution precedence is prepared generation lease → per-generation option → session setting; only when all omit the cap is execution unbounded. Owner stops, aborts, permissions, real errors, usage accounting and cleanup remain effective without a cap. Prompt-cache handling defaults to `cache: 'auto'`; use `cache: false` to disable the runtime's cache defaults, or pass an explicit cache policy (`ISmartAiCacheOptions` of `@modelprofile.com/flexharness-models`). On OpenAI a generation's `prompt_cache_key` is derived from its instructions and tool definitions, so sessions with one prefix share the provider's cache; `keyScope`, `keyBuckets` and `key` adjust it.
413
413
 
414
414
  ## Portable runner in the browser
415
415
 
@@ -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 {}
@@ -268,7 +269,8 @@ export interface IAgentSessionOptions {
268
269
  /**
269
270
  * Maximum number of LLM↔tool round trips.
270
271
  * Each step may execute multiple tools in parallel.
271
- * Default: 20
272
+ * Omitted: no step limit.
273
+ * Explicit caps must be positive safe integers.
272
274
  */
273
275
  maxSteps?: number;
274
276
  /** Initial canonical events. */
@@ -281,11 +283,17 @@ export interface IAgentSessionOptions {
281
283
  contextBuilder?: TAgentContextBuilder;
282
284
  /** Explicit context compactor used by manual and event-retention compaction. */
283
285
  contextCompactor?: TAgentContextCompactor;
284
- /** Compact settled history before inference when model messages exceed this UTF-8 JSON byte budget.
285
- * Defaults to 256 KiB when a compactor is supplied; false disables proactive compaction.
286
- * 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.
287
291
  */
288
- 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;
289
297
  /** Optional bounded active-event policy. Requires contextCompactor and eventStore.archive. */
290
298
  eventRetention?: IAgentEventRetentionOptions;
291
299
  /** Maximum wait for each session change listener. Default: 30 seconds. */
@@ -410,9 +418,20 @@ export interface IAgentGenerationLease {
410
418
  isReadOnlyToolCall?: TAgentToolCallClassifier;
411
419
  providerOptions?: ProviderOptions;
412
420
  cache?: TAgentCacheSetting;
421
+ /** Optional positive safe integer step cap; no limit unless configured. */
413
422
  maxSteps?: number;
414
423
  /** Caps the output tokens of each model call of the generation; the provider's limit otherwise. */
415
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;
416
435
  /**
417
436
  * Must be safe to call repeatedly and concurrently after failure or timeout.
418
437
  * A timeout does not cancel the original close attempt, so a retry may overlap it.
@@ -469,7 +488,7 @@ export interface IAgentGenerateOptions {
469
488
  providerOptions?: ProviderOptions;
470
489
  /** Per-generation prompt-cache override. A prepared lease takes precedence. */
471
490
  cache?: TAgentCacheSetting;
472
- /** Maximum completed model steps for this generation. */
491
+ /** Optional positive safe integer cap on completed model steps; omitted means no limit. */
473
492
  maxSteps?: number;
474
493
  /** Cancels only this generation and its synchronous tool executions. */
475
494
  abort?: AbortSignal;
@@ -477,7 +496,7 @@ export interface IAgentGenerateOptions {
477
496
  * Stops a transactional generation the way a user stops a turn. It ends the generation like
478
497
  * `abort`, but the interrupted outcome records the stop: the text the running model step
479
498
  * streamed and the tool calls it issued are kept, and the generation stays in the model
480
- * context once its model produced output. An aborted or failed generation is not kept.
499
+ * context once its model produced output. Aborted and failed generations with model/tool output also stay in context.
481
500
  */
482
501
  stop?: AbortSignal;
483
502
  /** Opt-in transactional claim returned by beginGeneration(). */
@@ -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);
@@ -149,14 +149,7 @@ const isModelOutputEvent = (event: TAgentEvent): boolean =>
149
149
  || event.type === 'tool-result'
150
150
  || event.type === 'model-message';
151
151
 
152
- /**
153
- * Whether the events of a transactional generation are part of the model context. An accepted
154
- * generation is, and so is the generation that is executing. A generation its owner stopped
155
- * stays in the context once the model produced output in it: its prompt, the input it took in
156
- * while it ran and what the model produced before the stop. One stopped before any model output
157
- * left no trace in the conversation and is not shown, so its prompt can be sent again. Rejected
158
- * generations, and generations interrupted by an abort, a failure or a restart, are not shown.
159
- */
152
+ /** Accepted and active generations, and terminal generations with actual model/tool output. */
160
153
  const isModelVisibleTransaction = (
161
154
  transaction: IAgentGenerationTransaction,
162
155
  producedOutput: ReadonlySet<string>,
@@ -164,8 +157,7 @@ const isModelVisibleTransaction = (
164
157
  transaction.state === 'accepted'
165
158
  || transaction.state === 'execution-started'
166
159
  || (
167
- transaction.state === 'interrupted'
168
- && transaction.outcome?.stopped === true
160
+ (transaction.state === 'interrupted' || transaction.state === 'rejected')
169
161
  && transaction.executionStarted !== undefined
170
162
  && producedOutput.has(transaction.generationId)
171
163
  );
@@ -179,12 +171,7 @@ const generationsWithModelOutput = (events: readonly TAgentEvent[]): Set<string>
179
171
  return producedOutput;
180
172
  };
181
173
 
182
- /**
183
- * Whether the transactional generation `generationId` is part of the model context of later
184
- * generations, by the rule `filterModelVisibleAgentEvents` applies: it was accepted, is
185
- * executing, or was stopped by its owner after its model produced output. False for a
186
- * generation `events` holds no transaction of.
187
- */
174
+ /** Whether a generation contributes to later context, including unsuccessful work with output. */
188
175
  export const isGenerationInModelContext = (
189
176
  events: readonly TAgentEvent[],
190
177
  generationId: string,
@@ -230,7 +217,7 @@ export const filterModelVisibleAgentEvents = (
230
217
  }
231
218
  }
232
219
  const visibleEvents: TAgentEvent[] = [];
233
- /** Closes each tool call a stopped generation left open, right after the call. */
220
+ /** Closes each tool call an unsuccessful generation left open, right after the call. */
234
221
  const closeOpenToolCall = (toolCallId: string, toolName: string, source: TAgentEvent): void => {
235
222
  const key = `${source.generationId}\0${toolCallId}`;
236
223
  if (resultedToolCalls.has(key)) return;
@@ -238,7 +225,25 @@ export const filterModelVisibleAgentEvents = (
238
225
  visibleEvents.push(interruptedToolResult(toolCallId, toolName, source));
239
226
  };
240
227
  for (const event of events) {
241
- if (isControlEvent(event)) continue;
228
+ if (isControlEvent(event)) {
229
+ if (event.type === 'generation-outcome' && event.outcome !== 'accepted') {
230
+ const transaction = transactions.get(event.generationId);
231
+ if (transaction && isModelVisibleTransaction(transaction, producedOutput)) {
232
+ visibleEvents.push({
233
+ id: `${event.id}:model-outcome`,
234
+ timestamp: event.timestamp,
235
+ generationId: event.generationId,
236
+ type: 'user-message',
237
+ content: event.outcome === 'rejected'
238
+ ? '[Generation outcome: rejected. This turn did not complete successfully. Prior tool results describe actual work; do not assume it was undone or repeat its effects.]'
239
+ : event.stopped
240
+ ? '[Generation outcome: stopped by owner. Prior tool results describe actual work; unresolved effects remain unknown.]'
241
+ : '[Generation outcome: interrupted, not completed successfully. Prior tool results describe actual work; unresolved effects remain unknown.]',
242
+ });
243
+ }
244
+ }
245
+ continue;
246
+ }
242
247
  if (event.type === 'context-compaction' && event.archivedTransactions) {
243
248
  visibleEvents.push({ ...event, archivedTransactions: undefined });
244
249
  continue;
@@ -250,7 +255,7 @@ export const filterModelVisibleAgentEvents = (
250
255
  const transaction = transactions.get(event.generationId);
251
256
  if (transaction && !isModelVisibleTransaction(transaction, producedOutput)) continue;
252
257
  visibleEvents.push(event);
253
- if (transaction?.state !== 'interrupted') continue;
258
+ if (transaction?.state !== 'interrupted' && transaction?.state !== 'rejected') continue;
254
259
  if (event.type === 'tool-call' && event.providerExecuted !== true) {
255
260
  closeOpenToolCall(event.toolCallId, event.toolName, event);
256
261
  } else if (event.type === 'assistant-message' && Array.isArray(event.content)) {