@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
@@ -776,9 +776,12 @@ export class FlexHarnessCore<TScope> {
776
776
  },
777
777
  }
778
778
  : {}),
779
+ // Undone and excluded turns leave every model-visible derivation: context, summaries and
780
+ // the visible pinned context revision.
781
+ contextEventFilter: (events) => this.reversions.filterReversionContextEvents(stored, events),
779
782
  contextBuilder: ({ events }) => hydrateAgentMessages(
780
783
  (this.agentSessionPolicy.contextBuilder ?? ((options) => plugins.buildModelMessages(options.events)))({
781
- events: this.reversions.filterReversionContextEvents(stored, events),
784
+ events,
782
785
  }),
783
786
  ),
784
787
  ...(contextCompactor
@@ -798,13 +801,6 @@ export class FlexHarnessCore<TScope> {
798
801
  throw new Error('Agent context compaction is missing its exact FlexHarness invocation context.');
799
802
  }
800
803
  const { modelHint, ...invocation } = invocationContext;
801
- const filteredEvents = this.reversions.filterReversionContextEvents(stored, events);
802
- const filteredMessages = hydrateAgentMessages(
803
- (this.agentSessionPolicy.contextBuilder
804
- ?? ((contextOptions) => plugins.buildModelMessages(contextOptions.events)))({
805
- events: filteredEvents,
806
- }),
807
- );
808
804
  const operation = createSessionMetricsOperation(plugins.crypto.randomUUID(), 'compaction');
809
805
  try {
810
806
  await this.mutateProjection(state, stored, () => {
@@ -831,7 +827,8 @@ export class FlexHarnessCore<TScope> {
831
827
  }
832
828
  stored.metricsCompaction = operation;
833
829
  try {
834
- return await contextCompactor(filteredMessages, filteredEvents, {
830
+ // The session passes the events `contextEventFilter` left and the messages built from them.
831
+ return await contextCompactor(messages, events, {
835
832
  ...options,
836
833
  ...invocation,
837
834
  scope: invocation.scope as TScope,
@@ -982,7 +979,8 @@ export class FlexHarnessCore<TScope> {
982
979
  const outcome = outcomes.get(runId);
983
980
  const stage = stages.get(runId);
984
981
  if (outcome === 'accepted' && stage?.status === 'completed') {
985
- this.runs.replaceVisibleRun(stored, this.runs.withKeptInContext(stage, true));
982
+ // A cache-warm exchange leaves the model context with its outcome.
983
+ this.runs.replaceVisibleRun(stored, this.runs.withKeptInContext(stage, !stage.assistantMessage.cacheWarm));
986
984
  if (!stage.assistantMessage.cacheWarm) latestTerminal = stage;
987
985
  } else if (outcome !== 'accepted') {
988
986
  const visible = stored.messages.filter((message) => message.runId === runId);
@@ -1951,20 +1949,31 @@ export class FlexHarnessCore<TScope> {
1951
1949
  });
1952
1950
  }
1953
1951
 
1952
+ /**
1953
+ * Where the run's assistant message sits in the transcript and the part among its parts. Both
1954
+ * positions are remembered on the run and checked on every use, so a streamed delta compares
1955
+ * one id each; a position is searched again only after it moved (a steer, a restored or
1956
+ * reloaded projection).
1957
+ */
1954
1958
  private partEventCoordinates(
1955
1959
  run: IActiveRun,
1956
1960
  partId: string,
1957
1961
  ): { messageIndex: number; partIndex: number } {
1958
- const messageIndex = run.stored.messages.findIndex(
1959
- (message) => message.messageId === run.assistantMessageId,
1960
- );
1961
- const partIndex = run.callbackParts.findIndex((entry) => entry.partId === partId);
1962
- if (
1963
- messageIndex < 0
1964
- || run.stored.messages[messageIndex]?.messageId !== run.assistantMessageId
1965
- || partIndex < 0
1966
- || run.callbackParts[partIndex]?.partId !== partId
1967
- ) throw new Error('Flex part event source coordinates are unavailable.');
1962
+ const positions = run.partEventPositions ??= { messageIndex: -1, partIndexes: new Map() };
1963
+ if (run.stored.messages[positions.messageIndex]?.messageId !== run.assistantMessageId) {
1964
+ positions.messageIndex = run.stored.messages.findIndex(
1965
+ (message) => message.messageId === run.assistantMessageId,
1966
+ );
1967
+ }
1968
+ let partIndex = positions.partIndexes.get(partId) ?? -1;
1969
+ if (run.callbackParts[partIndex]?.partId !== partId) {
1970
+ partIndex = run.callbackParts.findIndex((entry) => entry.partId === partId);
1971
+ if (partIndex >= 0) positions.partIndexes.set(partId, partIndex);
1972
+ }
1973
+ const { messageIndex } = positions;
1974
+ if (messageIndex < 0 || partIndex < 0) {
1975
+ throw new Error('Flex part event source coordinates are unavailable.');
1976
+ }
1968
1977
  return { messageIndex, partIndex };
1969
1978
  }
1970
1979
 
@@ -655,7 +655,8 @@ export class FlexHarnessProjectManagement<TScope> {
655
655
  const id = plugins.z.string().min(1).max(FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskIdBytes);
656
656
  const content = plugins.z.string().min(1).max(FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskContentBytes);
657
657
  return plugins.tool({
658
- description: 'List, create, update, delete, or clear session-local project tasks.',
658
+ description: 'List, create, update, delete, or clear the session-local project tasks. Each action '
659
+ + 'returns the project revision with the tasks it read or changed.',
659
660
  strict: false,
660
661
  inputSchema: plugins.z.object({
661
662
  action: plugins.z.enum(['list', 'create', 'update', 'delete', 'clear']),
@@ -726,7 +727,8 @@ export class FlexHarnessProjectManagement<TScope> {
726
727
 
727
728
  public createProjectGoalTool(run: IActiveRun): unknown {
728
729
  return plugins.tool({
729
- description: 'Get, set, or clear the session-local project goal.',
730
+ description: 'Get, set, or clear the session-local project goal. Each action returns the project '
731
+ + 'revision and the goal.',
730
732
  strict: false,
731
733
  inputSchema: plugins.z.object({
732
734
  action: plugins.z.enum(['get', 'set', 'clear']),
@@ -763,7 +765,9 @@ export class FlexHarnessProjectManagement<TScope> {
763
765
  public createProjectScratchpadTool(run: IActiveRun): unknown {
764
766
  const content = plugins.z.string().max(FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes);
765
767
  return plugins.tool({
766
- description: 'Get, set, append to, or clear the session-local project scratchpad.',
768
+ description: 'Get, set, append to, or clear the session-local project scratchpad. "get" returns the '
769
+ + 'project revision and the scratchpad; a change returns the project revision and the scratchpad\'s '
770
+ + 'size in UTF-8 bytes.',
767
771
  strict: false,
768
772
  inputSchema: plugins.z.object({
769
773
  action: plugins.z.enum(['get', 'set', 'append', 'clear']),
@@ -812,17 +816,27 @@ export class FlexHarnessProjectManagement<TScope> {
812
816
  });
813
817
  }
814
818
 
819
+ /**
820
+ * The `task` tool. Like every project tool it returns the revision with the field it read or the
821
+ * item it changed, never the whole state: a tool would otherwise show the model fields the host did
822
+ * not enable for it. Equal revisions across reads mean a consistent view.
823
+ */
815
824
  private async executeProjectTaskTool(
816
825
  run: IActiveRun,
817
826
  input: TProjectTaskToolInput,
818
827
  toolCallId: string | undefined,
819
- ): Promise<IFlexProjectStateResult | IFlexProjectTaskResult | IFlexProjectTasksResult> {
828
+ ): Promise<Omit<IFlexProjectTaskResult, 'state'> | Omit<IFlexProjectTasksResult, 'state'>> {
820
829
  this.assertProjectManagementSession(run.state, run.stored);
821
830
  if (input.action === 'list') {
822
831
  const snapshot = await this.readProjectManagementState(run.state, run.stored);
823
- return this.projectTasksResult(snapshot, snapshot.tasks);
832
+ return { revision: snapshot.revision, tasks: snapshot.tasks };
824
833
  }
825
834
  const writeContext = this.projectManagementAgentWriteContext(run, toolCallId);
835
+ if (input.action === 'clear') {
836
+ const { revision, tasks } = await this.clearProjectTasksInState(run.state, run.stored, writeContext);
837
+ return { revision, tasks };
838
+ }
839
+ let result: IFlexProjectTaskResult;
826
840
  if (input.action === 'create') {
827
841
  const id = input.id ?? (() => {
828
842
  validateUtf8String(
@@ -845,9 +859,8 @@ export class FlexHarnessProjectManagement<TScope> {
845
859
  ...(input.priority === undefined ? {} : { priority: input.priority }),
846
860
  };
847
861
  validateCreateProjectTaskInput(createInput);
848
- return this.createProjectTaskInState(run.state, run.stored, createInput, writeContext);
849
- }
850
- if (input.action === 'update') {
862
+ result = await this.createProjectTaskInState(run.state, run.stored, createInput, writeContext);
863
+ } else if (input.action === 'update') {
851
864
  const updateInput: IFlexUpdateProjectTaskInput = {
852
865
  id: input.id,
853
866
  ...(input.content === undefined ? {} : { content: input.content }),
@@ -855,71 +868,86 @@ export class FlexHarnessProjectManagement<TScope> {
855
868
  ...(input.priority === undefined ? {} : { priority: input.priority }),
856
869
  };
857
870
  validateUpdateProjectTaskInput(updateInput);
858
- return this.updateProjectTaskInState(run.state, run.stored, updateInput, writeContext);
859
- }
860
- if (input.action === 'delete') {
871
+ result = await this.updateProjectTaskInState(run.state, run.stored, updateInput, writeContext);
872
+ } else {
861
873
  validateProjectTaskId(input.id);
862
- return this.deleteProjectTaskInState(run.state, run.stored, input.id, writeContext);
874
+ result = await this.deleteProjectTaskInState(run.state, run.stored, input.id, writeContext);
863
875
  }
864
- return this.clearProjectTasksInState(run.state, run.stored, writeContext);
876
+ return { revision: result.revision, task: result.task };
865
877
  }
866
878
 
879
+ /** The `goal` tool: the revision and the goal. */
867
880
  private async executeProjectGoalTool(
868
881
  run: IActiveRun,
869
882
  input: TProjectGoalToolInput,
870
883
  toolCallId: string | undefined,
871
- ): Promise<IFlexProjectGoalResult> {
884
+ ): Promise<Omit<IFlexProjectGoalResult, 'state'>> {
872
885
  this.assertProjectManagementSession(run.state, run.stored);
886
+ let result: IFlexProjectGoalResult;
873
887
  if (input.action === 'get') {
874
- return this.projectGoalResult(await this.readProjectManagementState(run.state, run.stored));
875
- }
876
- const writeContext = this.projectManagementAgentWriteContext(run, toolCallId);
877
- if (input.action === 'set') {
888
+ result = this.projectGoalResult(await this.readProjectManagementState(run.state, run.stored));
889
+ } else if (input.action === 'set') {
878
890
  validateUtf8String(
879
891
  input.goal,
880
892
  'project goal',
881
893
  FLEX_PROJECT_MANAGEMENT_LIMITS.maxGoalBytes,
882
894
  true,
883
895
  );
884
- return this.setProjectGoalInState(run.state, run.stored, input.goal, writeContext);
896
+ result = await this.setProjectGoalInState(
897
+ run.state,
898
+ run.stored,
899
+ input.goal,
900
+ this.projectManagementAgentWriteContext(run, toolCallId),
901
+ );
902
+ } else {
903
+ result = await this.clearProjectGoalInState(
904
+ run.state,
905
+ run.stored,
906
+ this.projectManagementAgentWriteContext(run, toolCallId),
907
+ );
885
908
  }
886
- return this.clearProjectGoalInState(run.state, run.stored, writeContext);
909
+ return { revision: result.revision, goal: result.goal };
887
910
  }
888
911
 
912
+ /**
913
+ * The `scratchpad` tool: `get` returns the revision and the scratchpad, a change the revision and
914
+ * the scratchpad's size in UTF-8 bytes, so appending never sends the scratchpad back.
915
+ */
889
916
  private async executeProjectScratchpadTool(
890
917
  run: IActiveRun,
891
918
  input: TProjectScratchpadToolInput,
892
919
  toolCallId: string | undefined,
893
- ): Promise<IFlexProjectScratchpadResult> {
920
+ ): Promise<Omit<IFlexProjectScratchpadResult, 'state'> | { revision: number; scratchpadBytes: number }> {
894
921
  this.assertProjectManagementSession(run.state, run.stored);
895
922
  if (input.action === 'get') {
896
- return this.projectScratchpadResult(
897
- await this.readProjectManagementState(run.state, run.stored),
898
- );
923
+ const snapshot = await this.readProjectManagementState(run.state, run.stored);
924
+ return { revision: snapshot.revision, scratchpad: snapshot.scratchpad };
899
925
  }
900
926
  const writeContext = this.projectManagementAgentWriteContext(run, toolCallId);
927
+ let result: IFlexProjectScratchpadResult;
901
928
  if (input.action === 'set') {
902
929
  validateUtf8String(
903
930
  input.content,
904
931
  'project scratchpad',
905
932
  FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
906
933
  );
907
- return this.setProjectScratchpadInState(run.state, run.stored, input.content, writeContext);
908
- }
909
- if (input.action === 'append') {
934
+ result = await this.setProjectScratchpadInState(run.state, run.stored, input.content, writeContext);
935
+ } else if (input.action === 'append') {
910
936
  validateUtf8String(
911
937
  input.content,
912
938
  'project scratchpad append',
913
939
  FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
914
940
  );
915
- return this.appendProjectScratchpadInState(
941
+ result = await this.appendProjectScratchpadInState(
916
942
  run.state,
917
943
  run.stored,
918
944
  input.content,
919
945
  writeContext,
920
946
  );
947
+ } else {
948
+ result = await this.clearProjectScratchpadInState(run.state, run.stored, writeContext);
921
949
  }
922
- return this.clearProjectScratchpadInState(run.state, run.stored, writeContext);
950
+ return { revision: result.revision, scratchpadBytes: Buffer.byteLength(result.scratchpad, 'utf8') };
923
951
  }
924
952
 
925
953
  private createProjectTaskId(
@@ -730,11 +730,13 @@ export class FlexHarnessPromptQueue<TScope> {
730
730
  ? undefined
731
731
  : cloneSerializable(prompt.modelMessage.content) as TFlexAgentPrompt;
732
732
  this.assertPromptPromotion(queued, run);
733
+ // A cache-warm exchange is model-visible only to its own model calls.
734
+ const beginOptions = { generationId: run.runId, ...(run.cacheWarm ? { ephemeral: true as const } : {}) };
733
735
  run.transaction = await this.core.compaction.withRunCompactorContext(
734
736
  run,
735
737
  () => generationPrompt === undefined
736
- ? run.stored.agentSession.beginContinuation({ generationId: run.runId })
737
- : run.stored.agentSession.beginGeneration(generationPrompt, { generationId: run.runId }),
738
+ ? run.stored.agentSession.beginContinuation(beginOptions)
739
+ : run.stored.agentSession.beginGeneration(generationPrompt, beginOptions),
738
740
  );
739
741
  this.assertPromptPromotion(queued, run);
740
742
  const reservation = this.core.runs.createReservation(run, prompt, queued.promptId);
@@ -207,8 +207,10 @@ export class FlexHarnessRuns<TScope> {
207
207
  await this.core.lifecycle.fenceNamespace(run.state, run, projected);
208
208
  throw projected;
209
209
  }
210
- run.steering.keptInContext = true;
211
- terminal = this.withKeptInContext(terminal, true);
210
+ // A cache-warm exchange leaves the model context with its outcome.
211
+ const keptInContext = run.cacheWarm !== true;
212
+ run.steering.keptInContext = keptInContext;
213
+ terminal = this.withKeptInContext(terminal, keptInContext);
212
214
  this.core.reversions.refreshAutomaticArchiveHorizon(run.stored);
213
215
  run.phase = 'promoting';
214
216
  const closePublication = this.core.openPublication(run.state, run.sessionId);
@@ -619,6 +621,7 @@ export class FlexHarnessRuns<TScope> {
619
621
  ? {}
620
622
  : { contextCompactionDefaultTokens: model!.contextCompactionDefaultTokens }),
621
623
  ...(contextCompaction === undefined ? {} : { contextCompaction }),
624
+ ...(model!.pinnedContext === undefined ? {} : { pinnedContext: model!.pinnedContext }),
622
625
  ...(close ? { close } : {}),
623
626
  };
624
627
  } catch (error) {
@@ -9,6 +9,7 @@ import {
9
9
  type IFlexCreateSessionOptions,
10
10
  type IFlexEventArchiveMetadata,
11
11
  type IFlexMessage,
12
+ type IFlexMessageMetadataPage,
12
13
  type IFlexMessagePage,
13
14
  type IFlexMessagePageOptions,
14
15
  type IFlexMessageReadOptions,
@@ -19,15 +20,18 @@ import {
19
20
  type IFlexUpdateSessionOptions,
20
21
  type IJsonObject,
21
22
  } from './interfaces.js';
22
- import { cloneSerializable } from './utils.json.js';
23
+ import { cloneSerializable, deepFreeze } from './utils.json.js';
23
24
  import {
24
25
  createBoundedTransferMessage,
25
- jsonBytes,
26
26
  maxMessagePageCursorBytes,
27
+ messagePageBytes,
27
28
  maxMessagePageSize,
28
29
  maxTransferPageBytes,
29
30
  publicSnapshot,
30
31
  requireTransferIdentifier,
32
+ sizeBoundedTransferMessage,
33
+ sizeTransferMessageMetadata,
34
+ type ISizedTransferMessage,
31
35
  } from './utils.transfer.js';
32
36
  import {
33
37
  validateContextCompactionSetting,
@@ -365,11 +369,33 @@ export class FlexHarnessSessions<TScope> {
365
369
  return publicSnapshot(this.core.transcriptMessages(stored, includeUndone));
366
370
  }
367
371
 
368
- public async listMessagePage(
372
+ public listMessagePage(
369
373
  scopeId: string,
370
374
  sessionId: string,
371
375
  options: IFlexMessagePageOptions = {},
372
376
  ): Promise<IFlexMessagePage> {
377
+ return this.readMessagePage(scopeId, sessionId, options, sizeBoundedTransferMessage);
378
+ }
379
+
380
+ public listMessageMetadataPage(
381
+ scopeId: string,
382
+ sessionId: string,
383
+ options: IFlexMessagePageOptions = {},
384
+ ): Promise<IFlexMessageMetadataPage> {
385
+ return this.readMessagePage(scopeId, sessionId, options, sizeTransferMessageMetadata);
386
+ }
387
+
388
+ /**
389
+ * The newest page of transcript messages before the cursor, each projected by `project`, as
390
+ * many as `limit` allows and the page transfer limit holds. Each message is encoded once: the
391
+ * page's size is summed from the sizes `project` measured.
392
+ */
393
+ private async readMessagePage<TMessage extends { messageId: string }>(
394
+ scopeId: string,
395
+ sessionId: string,
396
+ options: IFlexMessagePageOptions,
397
+ project: (message: IFlexMessage) => ISizedTransferMessage<TMessage>,
398
+ ): Promise<{ messages: TMessage[]; startIndex: number; nextCursor?: string }> {
373
399
  if (!options || typeof options !== 'object' || Array.isArray(options)) {
374
400
  throw new FlexHarnessValidationError('Message page options must be a plain object.');
375
401
  }
@@ -409,29 +435,33 @@ export class FlexHarnessSessions<TScope> {
409
435
  end = anchor;
410
436
  }
411
437
  let start = end;
412
- let messages: IFlexMessage[] = [];
438
+ let nextCursor: string | undefined;
439
+ // Newest first while collecting; reversed into chronological order below.
440
+ const messages: TMessage[] = [];
441
+ let messageBytes = 0;
413
442
  for (let index = end - 1; index >= 0 && messages.length < limit; index--) {
414
- const candidate = createBoundedTransferMessage(visibleMessages[index]);
415
- const candidateMessages = [candidate, ...messages];
416
- const nextCursor = index > 0
417
- ? this.core.createMessageCursor(namespace, sessionId, candidate.messageId)
443
+ const candidate = project(visibleMessages[index]);
444
+ const candidateCursor = index > 0
445
+ ? this.core.createMessageCursor(namespace, sessionId, candidate.message.messageId)
418
446
  : undefined;
419
- const candidatePage: IFlexMessagePage = {
420
- messages: candidateMessages,
421
- startIndex: index,
422
- ...(nextCursor ? { nextCursor } : {}),
423
- };
424
- if (jsonBytes(candidatePage) > maxTransferPageBytes) break;
447
+ const candidateBytes = messagePageBytes(
448
+ messageBytes + candidate.bytes,
449
+ messages.length + 1,
450
+ index,
451
+ candidateCursor,
452
+ );
453
+ if (candidateBytes > maxTransferPageBytes) break;
454
+ messages.push(candidate.message);
455
+ messageBytes += candidate.bytes;
425
456
  start = index;
426
- messages = candidateMessages;
457
+ nextCursor = candidateCursor;
427
458
  }
428
459
  if (messages.length === 0 && end > 0) {
429
460
  throw new FlexHarnessValidationError('Stored message exceeds the page transfer limit.');
430
461
  }
431
- const nextCursor = start > 0
432
- ? this.core.createMessageCursor(namespace, sessionId, messages[0].messageId)
433
- : undefined;
434
- return publicSnapshot({ messages, startIndex: start, ...(nextCursor ? { nextCursor } : {}) });
462
+ messages.reverse();
463
+ // `project` built every message afresh, so freezing the page in place makes it public.
464
+ return deepFreeze({ messages, startIndex: start, ...(nextCursor ? { nextCursor } : {}) });
435
465
  }
436
466
 
437
467
  public async getMessage(
@@ -15,6 +15,7 @@ import type {
15
15
  IFlexHarnessOptions,
16
16
  IFlexImportedRun,
17
17
  IFlexMessage,
18
+ IFlexMessageMetadataPage,
18
19
  IFlexMessagePage,
19
20
  IFlexMessagePageOptions,
20
21
  IFlexMessageReadOptions,
@@ -273,6 +274,18 @@ export class FlexHarness<TScope = unknown> {
273
274
  return this.core.sessions.listMessagePage(scopeId, sessionId, options);
274
275
  }
275
276
 
277
+ /**
278
+ * Like {@link listMessagePage}, with each message's identity and state only (no parts, model,
279
+ * usage or error), so a full scan reads metadata whatever the size of the messages' content.
280
+ */
281
+ public listMessageMetadataPage(
282
+ scopeId: string,
283
+ sessionId: string,
284
+ options?: IFlexMessagePageOptions,
285
+ ): Promise<IFlexMessageMetadataPage> {
286
+ return this.core.sessions.listMessageMetadataPage(scopeId, sessionId, options);
287
+ }
288
+
276
289
  public getMessage(
277
290
  scopeId: string,
278
291
  sessionId: string,
package/ts/index.ts CHANGED
@@ -30,6 +30,7 @@ export {
30
30
  export {
31
31
  applyFlexProjectionChange,
32
32
  assertFlexProjectionChange,
33
+ createChangedProjectionSnapshot,
33
34
  createWholeProjectionChange,
34
35
  } from './utils.projectionchange.js';
35
36
  export { assertFlexToolJobSnapshot } from './utils.storecodecs.js';
@@ -246,6 +246,11 @@ export interface IActiveRun {
246
246
  callbackEventCount: number;
247
247
  callbackOutputBytes: number;
248
248
  callbackParts: TFlexMessagePart[];
249
+ /**
250
+ * The last known positions of the assistant message in the transcript and of parts among
251
+ * `callbackParts`, kept by part events and checked before each use.
252
+ */
253
+ partEventPositions?: { messageIndex: number; partIndexes: Map<string, number> };
249
254
  partTextUtf8Bytes: Map<string, number>;
250
255
  callbacksClosed: boolean;
251
256
  /** Set once the run emitted its `run.finished` event. */
package/ts/interfaces.ts CHANGED
@@ -735,6 +735,37 @@ export interface IFlexMessagePage {
735
735
  nextCursor?: string;
736
736
  }
737
737
 
738
+ /**
739
+ * A transcript message's identity and state without its content: no parts, model, usage or error.
740
+ * Enough to tell which input a session received and how its run ended, for example to prove that a
741
+ * prompt or steer was delivered, without reading its text or tool output.
742
+ */
743
+ export type TFlexMessageMetadata = Pick<
744
+ IFlexMessage,
745
+ | 'messageId'
746
+ | 'sessionId'
747
+ | 'runId'
748
+ | 'role'
749
+ | 'status'
750
+ | 'createdAt'
751
+ | 'completedAt'
752
+ | 'steerId'
753
+ | 'promptId'
754
+ | 'keptInContext'
755
+ | 'undone'
756
+ | 'cacheWarm'
757
+ >;
758
+
759
+ /**
760
+ * A page of message metadata. Pages, `startIndex`, cursors and `includeUndone` work as in
761
+ * {@link IFlexMessagePage}, and cursors of both kinds of page are interchangeable.
762
+ */
763
+ export interface IFlexMessageMetadataPage {
764
+ messages: TFlexMessageMetadata[];
765
+ startIndex: number;
766
+ nextCursor?: string;
767
+ }
768
+
738
769
  /**
739
770
  * A session as the events up to `sequence` describe it, read in one step. Replaying the events of
740
771
  * the same harness instance after `sequence` onto it gives the session's later states.
@@ -795,6 +826,34 @@ export interface IFlexResolvedModel {
795
826
  * `contextWindow`.
796
827
  */
797
828
  contextCompactionDefaultTokens?: number;
829
+ /**
830
+ * Text the model sees in its current revision without it being part of `system`, such as a
831
+ * host's working notes: a new revision changes neither the system prompt nor the tool
832
+ * definitions, so the provider's cached prefix survives it. See `IFlexPinnedContext`.
833
+ */
834
+ pinnedContext?: IFlexPinnedContext;
835
+ }
836
+
837
+ /**
838
+ * A pinned context. FlexHarness keeps the current revision of its `id` in the model's context
839
+ * exactly once after the latest compaction: when a run starts and the model-visible context does
840
+ * not show this revision as the id's latest, the run appends a pinned context message, which the
841
+ * model sees right before the run's prompt; a compaction ends its summary with the latest revision
842
+ * of each pinned context it covered. The message states the id and revision and that it replaces
843
+ * every earlier revision; earlier revisions stay where they are in the history, so the prefix in
844
+ * front of the new message is unchanged. FlexHarness keeps no record of its own: a run that
845
+ * leaves the model context (undone, or failed without output) takes its pinned context message
846
+ * along, and the next run appends it again.
847
+ */
848
+ export interface IFlexPinnedContext {
849
+ /** Names the context. */
850
+ id: string;
851
+ /**
852
+ * Names the text, a non-negative safe integer: a changed text needs a new revision. FlexHarness
853
+ * compares revisions only, never the text.
854
+ */
855
+ revision: number;
856
+ text: string;
798
857
  }
799
858
 
800
859
  export interface IFlexModelResolver<TScope> {