@modelprofile.com/flexharness 16.3.0 → 17.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/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 +32 -4
- 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 +32 -4
- 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
|
@@ -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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
1959
|
-
|
|
1960
|
-
|
|
1961
|
-
|
|
1962
|
-
|
|
1963
|
-
|
|
1964
|
-
|
|
1965
|
-
|
|
1966
|
-
|
|
1967
|
-
|
|
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<
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
874
|
+
result = await this.deleteProjectTaskInState(run.state, run.stored, input.id, writeContext);
|
|
863
875
|
}
|
|
864
|
-
return
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
897
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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(
|
|
737
|
-
: run.stored.agentSession.beginGeneration(generationPrompt,
|
|
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
|
-
|
|
211
|
-
|
|
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
|
|
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
|
|
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 =
|
|
415
|
-
const
|
|
416
|
-
|
|
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
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
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
|
-
|
|
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
|
-
|
|
432
|
-
|
|
433
|
-
|
|
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
|
@@ -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> {
|