@modelprofile.com/flexharness 16.2.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.
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts/classes.flexharness.core.d.ts +6 -0
- package/dist_ts/classes.flexharness.core.js +28 -15
- package/dist_ts/classes.flexharness.d.ts +6 -1
- package/dist_ts/classes.flexharness.js +8 -1
- package/dist_ts/classes.flexharness.projects.d.ts +10 -0
- package/dist_ts/classes.flexharness.projects.js +48 -21
- package/dist_ts/classes.flexharness.prompts.js +5 -3
- package/dist_ts/classes.flexharness.runs.js +6 -3
- package/dist_ts/classes.flexharness.sessions.d.ts +8 -1
- package/dist_ts/classes.flexharness.sessions.js +30 -20
- package/dist_ts/index.d.ts +1 -1
- package/dist_ts/index.js +2 -2
- package/dist_ts/interfaces.d.ts +42 -0
- package/dist_ts/interfaces.flexharness.d.ts +8 -0
- package/dist_ts/interfaces.js +1 -1
- package/dist_ts/utils.json.d.ts +21 -1
- package/dist_ts/utils.json.js +432 -191
- package/dist_ts/utils.projectionchange.d.ts +12 -2
- package/dist_ts/utils.projectionchange.js +41 -22
- package/dist_ts/utils.transfer.d.ts +15 -1
- package/dist_ts/utils.transfer.js +55 -7
- package/dist_ts/utils.validation.d.ts +3 -1
- package/dist_ts/utils.validation.js +19 -1
- package/package.json +3 -3
- package/readme.md +33 -5
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.flexharness.core.ts +29 -20
- package/ts/classes.flexharness.projects.ts +57 -29
- package/ts/classes.flexharness.prompts.ts +4 -2
- package/ts/classes.flexharness.runs.ts +5 -2
- package/ts/classes.flexharness.sessions.ts +49 -19
- package/ts/classes.flexharness.ts +13 -0
- package/ts/index.ts +1 -0
- package/ts/interfaces.flexharness.ts +5 -0
- package/ts/interfaces.ts +59 -0
- package/ts/readme.md +33 -5
- package/ts/utils.json.ts +521 -198
- package/ts/utils.projectionchange.ts +62 -26
- package/ts/utils.transfer.ts +68 -6
- 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
|
|
79
|
-
|
|
80
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
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 =
|
|
135
|
-
|
|
170
|
+
const { snapshot, kept } = applyProjectionChange(stored, change);
|
|
171
|
+
assertProjectionSnapshotEntries(snapshot, kept, sessionId);
|
|
136
172
|
return snapshot;
|
|
137
173
|
}
|
|
138
174
|
|
package/ts/utils.transfer.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
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
|
}
|
package/ts/utils.validation.ts
CHANGED
|
@@ -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,
|