@modelprofile.com/flexharness 16.3.0 → 16.4.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.
Files changed (41) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/classes.flexharness.core.d.ts +6 -0
  3. package/dist_ts/classes.flexharness.core.js +28 -15
  4. package/dist_ts/classes.flexharness.d.ts +6 -1
  5. package/dist_ts/classes.flexharness.js +8 -1
  6. package/dist_ts/classes.flexharness.projects.d.ts +10 -0
  7. package/dist_ts/classes.flexharness.projects.js +48 -21
  8. package/dist_ts/classes.flexharness.prompts.js +5 -3
  9. package/dist_ts/classes.flexharness.runs.js +6 -3
  10. package/dist_ts/classes.flexharness.sessions.d.ts +8 -1
  11. package/dist_ts/classes.flexharness.sessions.js +30 -20
  12. package/dist_ts/index.d.ts +1 -1
  13. package/dist_ts/index.js +2 -2
  14. package/dist_ts/interfaces.d.ts +42 -0
  15. package/dist_ts/interfaces.flexharness.d.ts +8 -0
  16. package/dist_ts/interfaces.js +1 -1
  17. package/dist_ts/utils.json.d.ts +21 -1
  18. package/dist_ts/utils.json.js +432 -191
  19. package/dist_ts/utils.projectionchange.d.ts +12 -2
  20. package/dist_ts/utils.projectionchange.js +41 -22
  21. package/dist_ts/utils.transfer.d.ts +15 -1
  22. package/dist_ts/utils.transfer.js +55 -7
  23. package/dist_ts/utils.validation.d.ts +3 -1
  24. package/dist_ts/utils.validation.js +19 -1
  25. package/package.json +3 -3
  26. package/readme.md +32 -4
  27. package/ts/00_commitinfo_data.ts +1 -1
  28. package/ts/classes.flexharness.core.ts +29 -20
  29. package/ts/classes.flexharness.projects.ts +57 -29
  30. package/ts/classes.flexharness.prompts.ts +4 -2
  31. package/ts/classes.flexharness.runs.ts +5 -2
  32. package/ts/classes.flexharness.sessions.ts +49 -19
  33. package/ts/classes.flexharness.ts +13 -0
  34. package/ts/index.ts +1 -0
  35. package/ts/interfaces.flexharness.ts +5 -0
  36. package/ts/interfaces.ts +59 -0
  37. package/ts/readme.md +32 -4
  38. package/ts/utils.json.ts +521 -198
  39. package/ts/utils.projectionchange.ts +62 -26
  40. package/ts/utils.transfer.ts +68 -6
  41. package/ts/utils.validation.ts +19 -0
@@ -8,10 +8,11 @@ import type {
8
8
  TFlexProjectionSnapshot,
9
9
  } from './interfaces.js';
10
10
  import {
11
- assertFlexProjectionSnapshot,
12
11
  assertJsonSerializable,
12
+ assertProjectionSnapshotEntries,
13
13
  cloneSerializable,
14
14
  deepFreeze,
15
+ type IKeptProjectionEntries,
15
16
  } from './utils.json.js';
16
17
  import { assertExactKeys, assertRecord } from './utils.storecodecs.js';
17
18
  import { validateExpectedRevision } from './utils.storerules.js';
@@ -65,19 +66,60 @@ export function assertFlexProjectionChange(value: unknown): asserts value is IFl
65
66
  assertListChange(value.reversionSegments, '$change.reversionSegments');
66
67
  }
67
68
 
69
+ /** A list a list change made, and how many of its entries it kept from the stored list. */
70
+ interface IAppliedListChange<TItem> {
71
+ entries: TItem[];
72
+ kept: number;
73
+ }
74
+
68
75
  function applyListChange<TItem>(
69
76
  stored: readonly TItem[],
70
77
  change: IFlexListChange<TItem>,
71
78
  path: string,
72
- ): TItem[] {
79
+ ): IAppliedListChange<TItem> {
73
80
  if (change.end > stored.length) {
74
81
  throw new FlexHarnessStoreFormatError(
75
82
  `${path} keeps entries up to ${change.end}, but the store holds ${stored.length}.`,
76
83
  );
77
84
  }
78
- const next = stored.slice(change.start, change.end);
79
- for (const item of change.items) next.push(item);
80
- return next;
85
+ const entries = stored.slice(change.start, change.end);
86
+ const kept = entries.length;
87
+ for (const item of change.items) entries.push(item);
88
+ return { entries, kept };
89
+ }
90
+
91
+ /** The snapshot a change makes, and how many entries of each list it kept from the stored one. */
92
+ interface IAppliedProjectionChange {
93
+ snapshot: IFlexProjectionSnapshotCurrent;
94
+ kept: IKeptProjectionEntries;
95
+ }
96
+
97
+ function applyProjectionChange(
98
+ stored: TFlexProjectionSnapshot | undefined,
99
+ change: IFlexProjectionChange,
100
+ ): IAppliedProjectionChange {
101
+ const lists = stored?.schemaVersion === 3 ? stored : undefined;
102
+ const messages = applyListChange(lists?.messages ?? [], change.messages, '$change.messages');
103
+ const reversionSegments = applyListChange(
104
+ lists?.reversionSegments ?? [],
105
+ change.reversionSegments,
106
+ '$change.reversionSegments',
107
+ );
108
+ return {
109
+ snapshot: {
110
+ schemaVersion: 3,
111
+ revision: change.revision,
112
+ ...(change.metrics === undefined ? {} : { metrics: change.metrics }),
113
+ messages: messages.entries,
114
+ stagedTerminals: change.stagedTerminals,
115
+ reversionSegments: reversionSegments.entries,
116
+ revertCursor: change.revertCursor,
117
+ excludedRunIds: change.excludedRunIds,
118
+ ...(change.pendingReversion === undefined ? {} : { pendingReversion: change.pendingReversion }),
119
+ pendingReversionReleases: change.pendingReversionReleases,
120
+ },
121
+ kept: { messages: messages.kept, reversionSegments: reversionSegments.kept },
122
+ };
81
123
  }
82
124
 
83
125
  /**
@@ -85,29 +127,14 @@ function applyListChange<TItem>(
85
127
  * modified. A stored projection of an older schema offers no entries to keep, so only whole
86
128
  * lists apply to it. It rejects a change that keeps entries the stored lists lack; the change's
87
129
  * form is `assertFlexProjectionChange`'s to check and the result's content
88
- * `assertFlexProjectionSnapshot`'s.
130
+ * `assertFlexProjectionSnapshot`'s. `createChangedProjectionSnapshot` applies and validates in
131
+ * one step that costs what the change carries.
89
132
  */
90
133
  export function applyFlexProjectionChange(
91
134
  stored: TFlexProjectionSnapshot | undefined,
92
135
  change: IFlexProjectionChange,
93
136
  ): IFlexProjectionSnapshotCurrent {
94
- const lists = stored?.schemaVersion === 3 ? stored : undefined;
95
- return {
96
- schemaVersion: 3,
97
- revision: change.revision,
98
- ...(change.metrics === undefined ? {} : { metrics: change.metrics }),
99
- messages: applyListChange(lists?.messages ?? [], change.messages, '$change.messages'),
100
- stagedTerminals: change.stagedTerminals,
101
- reversionSegments: applyListChange(
102
- lists?.reversionSegments ?? [],
103
- change.reversionSegments,
104
- '$change.reversionSegments',
105
- ),
106
- revertCursor: change.revertCursor,
107
- excludedRunIds: change.excludedRunIds,
108
- ...(change.pendingReversion === undefined ? {} : { pendingReversion: change.pendingReversion }),
109
- pendingReversionReleases: change.pendingReversionReleases,
110
- };
137
+ return applyProjectionChange(stored, change).snapshot;
111
138
  }
112
139
 
113
140
  /** A copy of a change a store was asked to save at `expectedRevision`, after checking its form. */
@@ -125,14 +152,23 @@ export function validateProjectionChangeSave(
125
152
  return cloneSerializable(change);
126
153
  }
127
154
 
128
- /** The snapshot `change` makes of a stored projection, validated in full for `sessionId`. */
155
+ /**
156
+ * The snapshot `change` makes of a stored projection, validated for `sessionId`. For any `stored`
157
+ * that `assertFlexProjectionSnapshot(stored, sessionId)` accepted or this function returned, it
158
+ * throws exactly when `assertFlexProjectionSnapshot(applyFlexProjectionChange(stored, change),
159
+ * sessionId)` throws, and otherwise returns that snapshot. Its work is what the change carries:
160
+ * the change's own entries and other fields are validated in full, and the stored entries it
161
+ * keeps are read only for their identities (message, run, event and capture IDs, roles and
162
+ * statuses), in one pass that relates every entry to the others. Precondition: the stored
163
+ * entries were not modified after their validation; FlexHarness freezes the ones it saved.
164
+ */
129
165
  export function createChangedProjectionSnapshot(
130
166
  stored: TFlexProjectionSnapshot | undefined,
131
167
  change: IFlexProjectionChange,
132
168
  sessionId: string,
133
169
  ): IFlexProjectionSnapshotCurrent {
134
- const snapshot = applyFlexProjectionChange(stored, change);
135
- assertFlexProjectionSnapshot(snapshot, sessionId);
170
+ const { snapshot, kept } = applyProjectionChange(stored, change);
171
+ assertProjectionSnapshotEntries(snapshot, kept, sessionId);
136
172
  return snapshot;
137
173
  }
138
174
 
@@ -7,11 +7,12 @@ import type {
7
7
  IFlexUsage,
8
8
  TFlexAgentRunResult,
9
9
  TFlexAttachmentSource,
10
+ TFlexMessageMetadata,
10
11
  TFlexPromptPart,
11
12
  } from './interfaces.js';
12
13
  import { cloneSerializable, deepFreeze } from './utils.json.js';
13
14
  import { isAttachmentReference } from './utils.prompt.js';
14
- import { validateIdentifier } from './utils.validation.js';
15
+ import { normalizePinnedContext, validateIdentifier } from './utils.validation.js';
15
16
 
16
17
  export interface IRunResultProjection {
17
18
  text: string;
@@ -104,6 +105,9 @@ export function normalizeResolvedModel(resolvedModel: IFlexResolvedModel): IFlex
104
105
  ...(resolvedModel.contextCompactionDefaultTokens === undefined
105
106
  ? {}
106
107
  : { contextCompactionDefaultTokens: resolvedModel.contextCompactionDefaultTokens }),
108
+ ...(resolvedModel.pinnedContext === undefined
109
+ ? {}
110
+ : { pinnedContext: normalizePinnedContext(resolvedModel.pinnedContext) }),
107
111
  };
108
112
  }
109
113
 
@@ -185,7 +189,18 @@ export function describeAttachment(
185
189
  };
186
190
  }
187
191
 
192
+ /** A transfer projection and the UTF-8 bytes of its JSON encoding. */
193
+ export interface ISizedTransferMessage<TMessage> {
194
+ message: TMessage;
195
+ bytes: number;
196
+ }
197
+
188
198
  export function createBoundedTransferMessage(message: IFlexMessage): IFlexMessage {
199
+ return sizeBoundedTransferMessage(message).message;
200
+ }
201
+
202
+ /** {@link createBoundedTransferMessage}, with the size of the projection it already measured. */
203
+ export function sizeBoundedTransferMessage(message: IFlexMessage): ISizedTransferMessage<IFlexMessage> {
189
204
  const projected = cloneSerializable(message);
190
205
  requireTransferIdentifier(projected.messageId, 'messageId');
191
206
  requireTransferIdentifier(projected.sessionId, 'sessionId');
@@ -215,15 +230,62 @@ export function createBoundedTransferMessage(message: IFlexMessage): IFlexMessag
215
230
  if (part.name !== undefined) part.name = truncateUtf8(part.name, maxTransferMetadataBytes);
216
231
  }
217
232
  }
218
- if (jsonBytes(projected) > maxTransferMessageBytes) {
233
+ let bytes = jsonBytes(projected);
234
+ if (bytes > maxTransferMessageBytes) {
219
235
  projected.parts = [{
220
236
  partId: 'transfer-elided',
221
237
  type: 'text',
222
238
  text: '[elided: message exceeds the transfer budget]',
223
239
  }];
240
+ bytes = jsonBytes(projected);
241
+ if (bytes > maxTransferMessageBytes) {
242
+ throw new FlexHarnessValidationError('Stored message metadata exceeds the transfer limit.');
243
+ }
224
244
  }
225
- if (jsonBytes(projected) > maxTransferMessageBytes) {
226
- throw new FlexHarnessValidationError('Stored message metadata exceeds the transfer limit.');
227
- }
228
- return projected;
245
+ return { message: projected, bytes };
246
+ }
247
+
248
+ /** A message's {@link TFlexMessageMetadata}, bounded like the transfer message, and its size. */
249
+ export function sizeTransferMessageMetadata(message: IFlexMessage): ISizedTransferMessage<TFlexMessageMetadata> {
250
+ requireTransferIdentifier(message.messageId, 'messageId');
251
+ requireTransferIdentifier(message.sessionId, 'sessionId');
252
+ requireTransferIdentifier(message.runId, 'runId');
253
+ if (message.steerId !== undefined) requireTransferIdentifier(message.steerId, 'steerId');
254
+ if (message.promptId !== undefined) requireTransferIdentifier(message.promptId, 'promptId');
255
+ const metadata: TFlexMessageMetadata = {
256
+ messageId: message.messageId,
257
+ sessionId: message.sessionId,
258
+ runId: message.runId,
259
+ role: message.role,
260
+ status: message.status,
261
+ createdAt: truncateUtf8(message.createdAt, 128),
262
+ ...(message.completedAt === undefined ? {} : { completedAt: truncateUtf8(message.completedAt, 128) }),
263
+ ...(message.steerId === undefined ? {} : { steerId: message.steerId }),
264
+ ...(message.promptId === undefined ? {} : { promptId: message.promptId }),
265
+ ...(message.keptInContext === undefined ? {} : { keptInContext: message.keptInContext }),
266
+ ...(message.undone === undefined ? {} : { undone: message.undone }),
267
+ ...(message.cacheWarm === undefined ? {} : { cacheWarm: message.cacheWarm }),
268
+ };
269
+ return { message: metadata, bytes: jsonBytes(metadata) };
270
+ }
271
+
272
+ const messagePageEnvelopeBytes = Buffer.byteLength('{"messages":[],"startIndex":}', 'utf8');
273
+ const messagePageCursorMemberBytes = Buffer.byteLength(',"nextCursor":', 'utf8');
274
+
275
+ /**
276
+ * The UTF-8 bytes of a message page's JSON encoding, `{"messages":[…],"startIndex":…,"nextCursor":…}`,
277
+ * from the summed encoded sizes of its messages: exactly what `jsonBytes` of the page returns.
278
+ */
279
+ export function messagePageBytes(
280
+ messageBytes: number,
281
+ messageCount: number,
282
+ startIndex: number,
283
+ nextCursor: string | undefined,
284
+ ): number {
285
+ return messagePageEnvelopeBytes
286
+ + messageBytes
287
+ + Math.max(0, messageCount - 1)
288
+ + String(startIndex).length
289
+ // A cursor is base64url, which JSON encodes without escapes.
290
+ + (nextCursor === undefined ? 0 : messagePageCursorMemberBytes + nextCursor.length + 2);
229
291
  }
@@ -11,6 +11,7 @@ import type {
11
11
  IFlexCreateProjectTaskInput,
12
12
  IFlexDeleteSessionGenerationCohortInput,
13
13
  IFlexErrorInfo,
14
+ IFlexPinnedContext,
14
15
  IFlexPromptOptions,
15
16
  IFlexSessionGenerationCohortEntry,
16
17
  IFlexSlashCommandExecutionOptions,
@@ -24,6 +25,7 @@ import type {
24
25
  const maxProjectedErrorNameBytes = 128;
25
26
  const maxProjectedErrorMessageBytes = 2048;
26
27
  const maxProjectedErrorCodeBytes = 128;
28
+ const maxPinnedContextIdBytes = 512;
27
29
  const controlCharacterPattern = /[\u0000-\u001f\u007f]/u;
28
30
  const configurationControlCharacterPattern = /[\u0000-\u001f\u007f-\u009f]/u;
29
31
  const unpairedSurrogatePattern = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u;
@@ -50,6 +52,23 @@ export function validateIdentifier(value: string, name: string): void {
50
52
  }
51
53
  }
52
54
 
55
+ /** A copy of a resolved model's pinned context, checked: see `IFlexPinnedContext`. */
56
+ export function normalizePinnedContext(value: IFlexPinnedContext): IFlexPinnedContext {
57
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
58
+ throw new FlexHarnessValidationError('The resolved model\'s pinnedContext must be an object.');
59
+ }
60
+ const unknownKey = Object.keys(value).find((key) => !['id', 'revision', 'text'].includes(key));
61
+ if (unknownKey !== undefined) {
62
+ throw new FlexHarnessValidationError(`The resolved model's pinnedContext has an unknown field "${unknownKey}".`);
63
+ }
64
+ validateUtf8String(value.id, 'pinnedContext id', maxPinnedContextIdBytes, true);
65
+ if (!Number.isSafeInteger(value.revision) || value.revision < 0) {
66
+ throw new FlexHarnessValidationError('pinnedContext revision must be a non-negative safe integer.');
67
+ }
68
+ if (typeof value.text !== 'string') throw new FlexHarnessValidationError('pinnedContext text must be a string.');
69
+ return { id: value.id, revision: value.revision, text: value.text };
70
+ }
71
+
53
72
  export function validateUtf8String(
54
73
  value: unknown,
55
74
  name: string,