feat(app): separate turn documents from artifacts

This commit is contained in:
2026-10-31 12:56:16 +00:00
parent 480f8843eb
commit acf74116d7
4 changed files with 279 additions and 47 deletions
@@ -7,12 +7,15 @@ import 'package:flutter/services.dart';
import '../../../core/api_gateway.dart';
import '../../../ui/adaptive/host.dart';
import '../../chat/ui/transcript/chat_markdown_view.dart';
import '../../graph/domain/stage_visits.dart';
import '../actions/artifact_file_actions.dart';
import '../actions/artifact_file_bridge.dart';
import '../domain/artifact_capture.dart';
import '../domain/artifact_document.dart';
import '../domain/artifact_groups.dart';
import '../domain/artifact_kind.dart';
import '../domain/artifact_record.dart';
import '../domain/artifact_selection.dart';
import '../domain/artifact_summary.dart';
import '../domain/artifact_url.dart';
import 'artifact_external_open.dart';
@@ -89,31 +92,88 @@ class _ArtifactGalleryPageState extends State<ArtifactGalleryPage> {
String? _status;
List<ArtifactGroup> _groupsOf(int? focusIndex) {
if (focusIndex == null) return galleryGroups(widget.steps);
final group = visitArtifactGroup(widget.steps, focusIndex);
if (group == null) return const <ArtifactGroup>[];
// The visit pane sees the same document-enriched group the gallery shows for
// that visit, not only its recorded files.
for (final enriched in galleryGroups(widget.steps)) {
if (enriched.stageKey == group.stageKey &&
enriched.visit == group.visit) {
// The visit pane's own Session section opens session.html, so the
// per-visit Artifacts drill-down keeps only stage output and the other
// turn documents; the run-wide gallery still shows every document.
final documents = enriched.documents
.where((doc) => doc.record?.name != sessionExportDocumentName)
.toList(growable: false);
return <ArtifactGroup>[
final allGroups = _withRepairDocuments(galleryGroups(widget.steps));
if (focusIndex == null) return allGroups;
if (focusIndex < 0 || focusIndex >= widget.steps.length) {
return const <ArtifactGroup>[];
}
final step = widget.steps[focusIndex];
final stageKey = '${step['stage'] ?? ''}';
final visits = visitsByStage(widget.steps)[stageKey];
if (visits == null) return const <ArtifactGroup>[];
final visitIndex = visits.indexOf(step);
if (visitIndex < 0) return const <ArtifactGroup>[];
final visit = displayVisit(step, visitIndex);
// Find the enriched gallery group directly rather than deriving it from the
// generated-artifact-only group. This retains document-only visits, including
// session.html, in the per-stage Artifacts section.
return [
for (final group in allGroups)
if (group.stageKey == stageKey && group.visit == visit) group,
];
}
/// Repaired session exports are also turn-owned debugging evidence, despite
/// living outside the four named document slots.
List<ArtifactGroup> _withRepairDocuments(List<ArtifactGroup> groups) {
final enriched = [
for (final group in groups)
ArtifactGroup(
stageKey: group.stageKey,
visit: group.visit,
artifacts: group.artifacts,
documents: [
...group.documents,
for (final artifact in systemArtifacts(
_stepsByGroup[artifactGroupKey(group.stageKey, group.visit)] ??
const <String, dynamic>{},
))
if (!group.documents.any(
(document) =>
document.record?.url == artifact.url &&
document.record?.name == artifact.name,
))
ArtifactDocument(
name: artifact.name,
record: artifact,
absence: '',
),
],
),
];
final keys = {
for (final group in enriched)
artifactGroupKey(group.stageKey, group.visit),
};
// `galleryGroups` intentionally only creates document-only groups for the
// four standard slots. A repair can be the only recorded evidence, so give
// it the same reachable secondary section.
for (final entry in visitsByStage(widget.steps).entries) {
for (var index = 0; index < entry.value.length; index += 1) {
final step = entry.value[index];
final visit = displayVisit(step, index);
final key = artifactGroupKey(entry.key, visit);
if (keys.contains(key)) continue;
final documents = systemArtifacts(step);
if (documents.isEmpty) continue;
enriched.add(
ArtifactGroup(
stageKey: enriched.stageKey,
visit: enriched.visit,
artifacts: enriched.artifacts,
documents: documents,
stageKey: entry.key,
visit: visit,
artifacts: const <ArtifactRecord>[],
documents: [
for (final artifact in documents)
ArtifactDocument(
name: artifact.name,
record: artifact,
absence: '',
),
],
),
];
);
}
}
return <ArtifactGroup>[group];
return enriched;
}
Future<void> _select(ArtifactGroup group, ArtifactRecord artifact) async {
@@ -129,19 +189,40 @@ class _ArtifactGalleryPageState extends State<ArtifactGalleryPage> {
if (!externalOnly &&
resolved != null &&
isViewerArtifact(artifact.contentType, artifact.name)) {
await _openViewer(identity);
await _openViewer(group, artifact);
return;
}
await _showSelected(group, artifact, resolved);
}
Future<void> _openViewer(String identity) async {
Future<void> _openViewer(
ArtifactGroup selectedGroup,
ArtifactRecord artifact,
) async {
final identity = artifactVisitIdentity(selectedGroup, artifact);
final isDocument = selectedGroup.documents.any(
(document) =>
document.record?.url == artifact.url &&
document.record?.name == artifact.name,
);
final viewerGroups = isDocument
? [
for (final group in _groups)
ArtifactGroup(
stageKey: group.stageKey,
visit: group.visit,
artifacts: [
for (final document in group.documents) ?document.record,
],
),
]
: _groups;
final previousFocus = FocusManager.instance.primaryFocus;
await Navigator.of(context).push<void>(
usesCupertinoHost(context)
? CupertinoPageRoute<void>(
builder: (_) => ArtifactViewerPage(
groups: _groups,
groups: viewerGroups,
selectedIdentity: identity,
configuredEndpoint: widget.configuredEndpoint,
openExternal: widget.openExternal,
@@ -152,7 +233,7 @@ class _ArtifactGalleryPageState extends State<ArtifactGalleryPage> {
)
: MaterialPageRoute<void>(
builder: (_) => ArtifactViewerPage(
groups: _groups,
groups: viewerGroups,
selectedIdentity: identity,
configuredEndpoint: widget.configuredEndpoint,
openExternal: widget.openExternal,
@@ -303,10 +384,30 @@ class _ArtifactGalleryPageState extends State<ArtifactGalleryPage> {
0,
(total, group) => total + group.artifacts.length,
);
if (count == 0 && groups.any((group) => group.documents.isNotEmpty)) {
return 'No artifacts recorded for this visit.';
}
return artifactsSummary(focused, count: count);
}
if (widget.steps.isEmpty) return 'No steps recorded for this run.';
return artifactsHeader(widget.steps, executing: widget.executing);
final count = groups.fold<int>(
0,
(total, group) => total + group.artifacts.length,
);
if (count == 0) {
if (widget.executing) return 'Artifacts · capture pending';
if (widget.steps.any(
(step) => !ArtifactCapture.fromStep(step).isAvailable,
)) {
return 'Artifacts · capture unavailable';
}
return 'No artifacts recorded for this run.';
}
var label = '${count == 1 ? 'Artifact' : 'Artifacts'} · $count recorded';
if (widget.steps.any((step) => ArtifactCapture.fromStep(step).isPartial)) {
label += ' · partial capture';
}
return label;
}
/// The partial-capture notes shown under the page's summary.
@@ -56,9 +56,8 @@ class ArtifactVisitList extends StatefulWidget {
final String configuredEndpoint;
final ArtifactFetch fetch;
/// Whether the artifact sections begin closed. Run artifact galleries use
/// the default; this remains configurable for composed hosts that explicitly
/// want to restore their own open state.
/// Whether generated-artifact sections begin closed. Turn documents always
/// begin closed because they are debugging evidence.
final bool initiallyCollapsed;
/// The layout last chosen, kept for the app's lifetime.
@@ -78,16 +77,15 @@ class _ArtifactVisitListState extends State<ArtifactVisitList> {
@override
void initState() {
super.initState();
_closed = widget.initiallyCollapsed
? {
for (final group in widget.groups)
if (group.artifacts.isNotEmpty)
'${group.stageKey}\u0000${group.visit}\u0000artifacts',
for (final group in widget.groups)
if (group.documents.isNotEmpty)
'${group.stageKey}\u0000${group.visit}\u0000documents',
}
: <String>{};
_closed = {
if (widget.initiallyCollapsed)
for (final group in widget.groups)
if (group.artifacts.isNotEmpty)
'${group.stageKey}\u0000${group.visit}\u0000artifacts',
for (final group in widget.groups)
if (group.documents.isNotEmpty)
'${group.stageKey}\u0000${group.visit}\u0000documents',
};
}
void _toggle(String key) => setState(() {
@@ -132,11 +130,17 @@ class _ArtifactVisitListState extends State<ArtifactVisitList> {
key: key,
title: '${artifactGroupLabel(group)} · Turn documents',
count: group.documents.length,
body: ArtifactDocumentSection(
group: group,
selectedIdentity: widget.selectedIdentity,
onSelected: widget.onSelected,
showHeader: false,
body: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
_debugHint(context),
ArtifactDocumentSection(
group: group,
selectedIdentity: widget.selectedIdentity,
onSelected: widget.onSelected,
showHeader: false,
),
],
),
),
);
@@ -220,6 +224,20 @@ class _ArtifactVisitListState extends State<ArtifactVisitList> {
);
}
Widget _debugHint(BuildContext context) {
final style = usesCupertinoHost(context)
? CupertinoTheme.of(context).textTheme.textStyle.copyWith(
color: CupertinoColors.secondaryLabel.resolveFrom(context),
)
: Theme.of(context).textTheme.bodySmall?.copyWith(
color: Theme.of(context).colorScheme.onSurfaceVariant,
);
return Padding(
padding: const EdgeInsetsDirectional.fromSTEB(16, 8, 16, 4),
child: Text('For debugging.', style: style),
);
}
/// The list view: one row per artifact with a small thumbnail beside it.
Widget _list(ArtifactGroup group) => Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
@@ -53,6 +53,7 @@ Future<void> _pump(
List<JsonMap>? steps,
ArtifactFetch? fetch,
ArtifactExternalOpen? openExternal,
int? focusIndex,
}) async {
tester.view.physicalSize = const Size(900, 2600);
tester.view.devicePixelRatio = 1;
@@ -60,6 +61,7 @@ Future<void> _pump(
addTearDown(tester.view.resetDevicePixelRatio);
final page = ArtifactGalleryPage(
steps: steps ?? _steps(),
focusIndex: focusIndex,
configuredEndpoint: _endpoint,
openExternal: openExternal ?? (_) async => true,
fetch:
@@ -78,6 +80,14 @@ Future<void> _pump(
await tester.pumpAndSettle();
}
Future<void> _expandTurnDocuments(WidgetTester tester) async {
final headings = find.textContaining('Turn documents');
for (var index = 0; index < headings.evaluate().length; index += 1) {
await tester.tap(headings.at(index));
await tester.pumpAndSettle();
}
}
Finder _dialog(_Platform platform, String text) => find.descendant(
of: find.byType(
platform == _Platform.material ? AlertDialog : CupertinoAlertDialog,
@@ -92,6 +102,11 @@ void main() {
) async {
await _pump(tester, platform);
expect(find.textContaining('Turn documents'), findsNWidgets(2));
// The generated artifact grid remains primary; debugging evidence is
// deliberately hidden until its own section is opened.
expect(find.text('input.md'), findsNothing);
expect(find.text('For debugging.'), findsNothing);
await _expandTurnDocuments(tester);
expect(find.text('input.md'), findsNWidgets(2));
expect(find.text('output.md'), findsNWidgets(2));
expect(find.text('session.html'), findsNWidgets(2));
@@ -104,6 +119,7 @@ void main() {
tester,
) async {
await _pump(tester, platform);
await _expandTurnDocuments(tester);
expect(find.text('No memory recorded for this visit.'), findsOneWidget);
expect(find.text('No output recorded.'), findsOneWidget);
expect(find.text('This visit has no harness session.'), findsOneWidget);
@@ -114,6 +130,7 @@ void main() {
tester,
) async {
await _pump(tester, platform);
await _expandTurnDocuments(tester);
await tester.tap(find.text('input.md').first);
await tester.pumpAndSettle();
expect(find.byType(ArtifactViewerPage), findsOneWidget);
@@ -128,6 +145,7 @@ void main() {
'${platform.name}: absent rows are informational, not controls',
(tester) async {
await _pump(tester, platform);
await _expandTurnDocuments(tester);
final absence = find.text('No output recorded.');
expect(absence, findsOneWidget);
if (platform == _Platform.material) {
@@ -169,6 +187,7 @@ void main() {
},
fetch: (_) async => throw StateError('x'),
);
await _expandTurnDocuments(tester);
await tester.tap(find.text('session.html').first);
await tester.pumpAndSettle();
expect(find.byType(ArtifactViewerPage), findsNothing);
@@ -181,5 +200,99 @@ void main() {
Uri.parse('http://127.0.0.1:8081/artifacts/1/1/session.html'),
]);
});
testWidgets('${platform.name}: documents do not count as artifacts and '
'viewer paging stays within documents', (tester) async {
await _pump(
tester,
platform,
steps: [
step(
stage: 'review',
visit: 1,
artifacts: [
_recorded('report.csv', contentType: 'text/csv', sizeBytes: 23),
_recorded('input.md', contentType: 'text/markdown', sizeBytes: 1),
_recorded(
'output.md',
contentType: 'text/markdown',
sizeBytes: 1,
),
],
),
],
);
expect(find.text('Artifact · 1 recorded'), findsOneWidget);
expect(find.text('report.csv'), findsOneWidget);
expect(find.text('input.md'), findsNothing);
await _expandTurnDocuments(tester);
expect(find.text('For debugging.'), findsOneWidget);
await tester.tap(find.text('input.md'));
await tester.pumpAndSettle();
expect(find.byType(ArtifactViewerPage), findsOneWidget);
expect(find.text('1 of 2 · text/markdown'), findsOneWidget);
});
testWidgets('${platform.name}: document-only visits retain an honest empty '
'artifact state', (tester) async {
await _pump(
tester,
platform,
steps: [
step(
stage: 'review',
visit: 1,
artifacts: [
_recorded('input.md', contentType: 'text/markdown', sizeBytes: 1),
],
),
],
);
expect(find.text('No artifacts recorded for this run.'), findsOneWidget);
expect(find.text('input.md'), findsNothing);
await _expandTurnDocuments(tester);
expect(find.text('input.md'), findsOneWidget);
expect(find.text('For debugging.'), findsOneWidget);
});
testWidgets('${platform.name}: focused document-only visits retain turn '
'documents', (tester) async {
await _pump(
tester,
platform,
focusIndex: 0,
steps: [
step(
stage: 'review',
visit: 1,
artifacts: [
_recorded('input.md', contentType: 'text/markdown', sizeBytes: 1),
],
),
],
);
expect(
find.text('No artifacts recorded for this visit.'),
findsOneWidget,
);
expect(find.text('input.md'), findsNothing);
await _expandTurnDocuments(tester);
expect(find.text('input.md'), findsOneWidget);
expect(find.text('For debugging.'), findsOneWidget);
});
testWidgets('${platform.name}: focused visits retain session documents', (
tester,
) async {
await _pump(tester, platform, focusIndex: 0);
expect(find.text('session.html'), findsNothing);
await _expandTurnDocuments(tester);
expect(find.text('session.html'), findsOneWidget);
expect(find.text('For debugging.'), findsOneWidget);
});
}
}
@@ -79,12 +79,12 @@ void main() {
expect(find.text('ok'), findsOneWidget);
await openVisitTab(tester, RunVisitSection.artifacts);
// The section is the run's gallery, focused on this visit: exactly the
// stage's files, without the session evidence file.
// The focused gallery keeps generated files primary and makes the session
// evidence reachable in its secondary turn-documents section.
await _expandArtifactGroup(tester);
expect(find.byType(ArtifactGalleryPage), findsOneWidget);
expect(find.text('plan.csv'), findsOneWidget);
expect(find.text('session.html'), findsNothing);
expect(find.text('session.html'), findsOneWidget);
await openVisitTab(tester, RunVisitSection.session);
expect(find.text('Session'), findsWidgets);