@modelprofile.com/flexharness 18.1.0 → 18.2.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 (68) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/classes.flexharness.cachewarm.js +3 -3
  3. package/dist_ts/classes.flexharness.callbacks.d.ts +37 -0
  4. package/dist_ts/classes.flexharness.callbacks.js +129 -2
  5. package/dist_ts/classes.flexharness.compaction.js +2 -2
  6. package/dist_ts/classes.flexharness.configurations.js +4 -4
  7. package/dist_ts/classes.flexharness.core.d.ts +39 -4
  8. package/dist_ts/classes.flexharness.core.js +467 -134
  9. package/dist_ts/classes.flexharness.d.ts +4 -0
  10. package/dist_ts/classes.flexharness.deletion.d.ts +13 -0
  11. package/dist_ts/classes.flexharness.deletion.js +122 -40
  12. package/dist_ts/classes.flexharness.imports.js +26 -21
  13. package/dist_ts/classes.flexharness.js +9 -1
  14. package/dist_ts/classes.flexharness.lifecycle.js +9 -3
  15. package/dist_ts/classes.flexharness.projects.js +2 -2
  16. package/dist_ts/classes.flexharness.prompts.js +14 -8
  17. package/dist_ts/classes.flexharness.reversions.js +3 -3
  18. package/dist_ts/classes.flexharness.runs.js +18 -2
  19. package/dist_ts/classes.flexharness.sessions.d.ts +1 -1
  20. package/dist_ts/classes.flexharness.sessions.js +18 -18
  21. package/dist_ts/classes.flexharness.slashcommands.js +3 -3
  22. package/dist_ts/classes.flexharness.subagents.js +37 -16
  23. package/dist_ts/classes.flexharness.tooldispatch.js +3 -3
  24. package/dist_ts/classes.scoperecovery.d.ts +36 -0
  25. package/dist_ts/classes.scoperecovery.js +228 -0
  26. package/dist_ts/classes.stores.d.ts +14 -1
  27. package/dist_ts/classes.stores.js +150 -17
  28. package/dist_ts/index.d.ts +1 -0
  29. package/dist_ts/index.js +2 -1
  30. package/dist_ts/interfaces.d.ts +84 -0
  31. package/dist_ts/interfaces.flexharness.d.ts +36 -0
  32. package/dist_ts/interfaces.js +1 -1
  33. package/dist_ts/utils.harnessoptions.d.ts +2 -0
  34. package/dist_ts/utils.harnessoptions.js +16 -11
  35. package/dist_ts_stores_nosqldb/classes.nosqldbstores.d.ts +3 -2
  36. package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +33 -2
  37. package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +10 -1
  38. package/dist_ts_stores_nosqldb/classes.recordstore.js +75 -7
  39. package/package.json +3 -3
  40. package/readme.md +42 -4
  41. package/ts/00_commitinfo_data.ts +1 -1
  42. package/ts/classes.flexharness.cachewarm.ts +2 -2
  43. package/ts/classes.flexharness.callbacks.ts +142 -1
  44. package/ts/classes.flexharness.compaction.ts +1 -1
  45. package/ts/classes.flexharness.configurations.ts +3 -3
  46. package/ts/classes.flexharness.core.ts +463 -133
  47. package/ts/classes.flexharness.deletion.ts +161 -52
  48. package/ts/classes.flexharness.imports.ts +26 -21
  49. package/ts/classes.flexharness.lifecycle.ts +8 -2
  50. package/ts/classes.flexharness.projects.ts +1 -1
  51. package/ts/classes.flexharness.prompts.ts +11 -7
  52. package/ts/classes.flexharness.reversions.ts +2 -2
  53. package/ts/classes.flexharness.runs.ts +16 -1
  54. package/ts/classes.flexharness.sessions.ts +17 -17
  55. package/ts/classes.flexharness.slashcommands.ts +2 -2
  56. package/ts/classes.flexharness.subagents.ts +40 -15
  57. package/ts/classes.flexharness.tooldispatch.ts +2 -2
  58. package/ts/classes.flexharness.ts +13 -0
  59. package/ts/classes.scoperecovery.ts +290 -0
  60. package/ts/classes.stores.ts +150 -16
  61. package/ts/index.ts +2 -0
  62. package/ts/interfaces.flexharness.ts +38 -0
  63. package/ts/interfaces.ts +89 -0
  64. package/ts/readme.md +42 -4
  65. package/ts/utils.harnessoptions.ts +18 -12
  66. package/ts_stores_nosqldb/classes.nosqldbstores.ts +52 -2
  67. package/ts_stores_nosqldb/classes.recordstore.ts +78 -8
  68. package/ts_stores_nosqldb/readme.md +10 -0
@@ -10,7 +10,7 @@ import {
10
10
  type TFlexMessagePart,
11
11
  type TJsonValue,
12
12
  } from './interfaces.js';
13
- import { MIN_MAX_BYTES, normalizeJsonValue } from './utils.json.js';
13
+ import { MIN_MAX_BYTES, cloneSerializable, normalizeJsonValue } from './utils.json.js';
14
14
  import { jsonBytes, truncateUtf8 } from './utils.transfer.js';
15
15
  import {
16
16
  observeSessionMetricsCall,
@@ -26,6 +26,11 @@ import type {
26
26
  import type { FlexHarnessCore } from './classes.flexharness.core.js';
27
27
  import { toolCallNotStartedMessage } from './utils.flexharness.js';
28
28
 
29
+ /** A run's next projection checkpoint starts no sooner than this after its last save completed. */
30
+ const checkpointMinimumGapMs = 10_000;
31
+ /** ...and no sooner than this many times that save's duration after it completed. */
32
+ const checkpointSaveDurationFactor = 20;
33
+
29
34
  /** How a tool call ended, as its part records it. */
30
35
  type TToolPartOutcome = { output: TJsonValue } | { error: string; rejectedPermissionId?: string };
31
36
 
@@ -154,6 +159,142 @@ export class FlexHarnessRunCallbacks<TScope> {
154
159
  run.stepPartIds.clear();
155
160
  run.stepStreamedCalls.clear();
156
161
  run.stepInvalidCalls.clear();
162
+ this.markCheckpoint(run);
163
+ }
164
+
165
+ /**
166
+ * The step's parts are committed: the run's event log holds them (the engine saves it before it
167
+ * calls `onStepCommitted`). They join the parts a checkpoint saves, and a checkpoint is due at
168
+ * the run's deadline. Never awaited by the model loop.
169
+ */
170
+ private markCheckpoint(run: IActiveRun): void {
171
+ const checkpoint = run.checkpoint;
172
+ if (checkpoint.closed) return;
173
+ for (const part of run.callbackParts) checkpoint.committedPartIds.add(part.partId);
174
+ checkpoint.dirty = true;
175
+ this.scheduleCheckpoint(run);
176
+ }
177
+
178
+ /**
179
+ * Starts the run's checkpoint when it is due and none is outstanding, or arms the run's one
180
+ * deadline timer; the timer starts it also when no further step commits.
181
+ */
182
+ private scheduleCheckpoint(run: IActiveRun): void {
183
+ const checkpoint = run.checkpoint;
184
+ if (
185
+ checkpoint.closed
186
+ || !checkpoint.dirty
187
+ || checkpoint.outstanding
188
+ || checkpoint.timer !== undefined
189
+ || checkpoint.savedAt === undefined
190
+ ) return;
191
+ const clock = this.core.checkpointClock;
192
+ const deadline = checkpoint.savedAt
193
+ + Math.max(checkpointMinimumGapMs, checkpointSaveDurationFactor * checkpoint.saveMs);
194
+ const delayMs = deadline - clock.now();
195
+ if (delayMs <= 0) {
196
+ this.startCheckpoint(run);
197
+ return;
198
+ }
199
+ checkpoint.timer = clock.setTimeout(() => {
200
+ checkpoint.timer = undefined;
201
+ this.startCheckpoint(run);
202
+ }, delayMs);
203
+ }
204
+
205
+ /** Whether the run may still checkpoint: it is the session's active run, open, its namespace active. */
206
+ private checkpointable(run: IActiveRun): boolean {
207
+ return !run.checkpoint.closed
208
+ && run.state.lifecycle === 'active'
209
+ && run.state.activeRuns.get(run.sessionId) === run
210
+ && !run.callbacksClosed
211
+ && run.callbackError === undefined;
212
+ }
213
+
214
+ /** Queues the run's checkpoint in its projection FIFO. A failed save fails the run. */
215
+ private startCheckpoint(run: IActiveRun): void {
216
+ const checkpoint = run.checkpoint;
217
+ if (!this.checkpointable(run)) return;
218
+ checkpoint.outstanding = true;
219
+ this.core.checkpointProjection(
220
+ run.state,
221
+ run.stored,
222
+ () => this.checkpointMutation(run),
223
+ (startedAt, completedAt) => this.setCheckpointReference(run, startedAt, completedAt),
224
+ ).then(() => {
225
+ checkpoint.outstanding = false;
226
+ this.scheduleCheckpoint(run);
227
+ }, (error: unknown) => {
228
+ checkpoint.outstanding = false;
229
+ // As every other projection save of the run: an uncertain commit has fenced the namespace.
230
+ this.failCallback(run, this.core.projectExternalError(run, error, 'persistence'));
231
+ });
232
+ }
233
+
234
+ /**
235
+ * At the checkpoint's turn in the FIFO: the change that replaces the run's streaming assistant
236
+ * message with one holding the parts of committed steps as they stand now, or nothing when no
237
+ * step committed since the last checkpoint, the run cannot checkpoint, or the message is not its
238
+ * streaming assistant message any more.
239
+ */
240
+ private checkpointMutation(run: IActiveRun): (() => void) | undefined {
241
+ const checkpoint = run.checkpoint;
242
+ if (!checkpoint.dirty || !this.checkpointable(run)) return undefined;
243
+ // What this checkpoint reads covers every commit so far, whether or not it saves.
244
+ checkpoint.dirty = false;
245
+ const index = this.core.assistantMessagePositions(run).messageIndex;
246
+ const message = run.stored.messages[index];
247
+ if (
248
+ message === undefined
249
+ || message.role !== 'assistant'
250
+ || message.status !== 'streaming'
251
+ || message.runId !== run.runId
252
+ ) return undefined;
253
+ const parts = cloneSerializable(
254
+ run.callbackParts.filter((part) => checkpoint.committedPartIds.has(part.partId)),
255
+ );
256
+ return () => {
257
+ run.stored.messages[index] = { ...message, parts };
258
+ };
259
+ }
260
+
261
+ /**
262
+ * A save of the run's current assistant message completed (its start, a steer split, a
263
+ * checkpoint): the next checkpoint's deadline counts from it.
264
+ */
265
+ public setCheckpointReference(run: IActiveRun, startedAt: number, completedAt: number): void {
266
+ run.checkpoint.savedAt = completedAt;
267
+ run.checkpoint.saveMs = Math.max(0, completedAt - startedAt);
268
+ }
269
+
270
+ /**
271
+ * A steer split saves every part of the run's answer so far: no checkpoint is due, and the
272
+ * answer that follows starts with no committed part.
273
+ */
274
+ public resetCheckpoint(run: IActiveRun): void {
275
+ const checkpoint = run.checkpoint;
276
+ this.clearCheckpointTimer(run);
277
+ checkpoint.dirty = false;
278
+ checkpoint.committedPartIds.clear();
279
+ }
280
+
281
+ /** The run reached its terminal, closed, or its namespace stops: no checkpoint starts any more. */
282
+ public closeCheckpoint(run: IActiveRun): void {
283
+ this.clearCheckpointTimer(run);
284
+ run.checkpoint.closed = true;
285
+ run.checkpoint.dirty = false;
286
+ }
287
+
288
+ /** Closes the checkpoints of every active run of a namespace that is drained or fenced. */
289
+ public closeCheckpoints(state: IStorageState): void {
290
+ for (const run of state.activeRuns.values()) this.closeCheckpoint(run);
291
+ }
292
+
293
+ private clearCheckpointTimer(run: IActiveRun): void {
294
+ const checkpoint = run.checkpoint;
295
+ if (checkpoint.timer === undefined) return;
296
+ this.core.checkpointClock.clearTimeout(checkpoint.timer);
297
+ checkpoint.timer = undefined;
157
298
  }
158
299
 
159
300
  /**
@@ -36,7 +36,7 @@ export class FlexHarnessCompaction<TScope> {
36
36
  options: IFlexCompactSessionOptions = {},
37
37
  ): Promise<void> {
38
38
  const { modelHint } = validateCompactSessionOptions(options);
39
- const { scope, state } = await this.core.resolveState(scopeId);
39
+ const { scope, state } = await this.core.resolveState(scopeId, sessionId);
40
40
  const stored = this.core.requireSession(state, sessionId);
41
41
  this.core.assertSessionWritable(stored);
42
42
  const invocationOwner = this.core.commands.slashCommandInvocationContext.getStore();
@@ -44,11 +44,11 @@ export class FlexHarnessSessionConfigurations<TScope> {
44
44
  const controller = new AbortController();
45
45
  const parent = stored.session.parentSessionId === undefined
46
46
  ? undefined
47
- : state.sessions.get(stored.session.parentSessionId);
47
+ : state.catalogue.get(stored.session.parentSessionId);
48
48
  if (stored.session.parentSessionId !== undefined && !parent) {
49
49
  throw this.core.trustInternalError(new FlexHarnessAbortError('The session parent is no longer available.'));
50
50
  }
51
- const parentGeneration = parent === undefined ? undefined : requireSessionGeneration(parent.session);
51
+ const parentGeneration = parent === undefined ? undefined : requireSessionGeneration(parent);
52
52
  const context = Object.freeze({
53
53
  scopeId,
54
54
  scope,
@@ -57,7 +57,7 @@ export class FlexHarnessSessionConfigurations<TScope> {
57
57
  ...generation,
58
58
  configurationRef,
59
59
  ...(parent === undefined ? {} : {
60
- parentSessionId: parent.session.sessionId,
60
+ parentSessionId: parent.sessionId,
61
61
  parentSessionGenerationId: parentGeneration!.sessionGenerationId,
62
62
  parentSessionGenerationSequence: parentGeneration!.sessionGenerationSequence,
63
63
  }),