From cbba026cdc8172774539003d91a664ed3bf001d8 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 22 Oct 2026 02:18:44 +0100 Subject: [PATCH 1/4] feat(app): resolve recorded search hits to their exact targets Map every recorded search hit payload (pipeline, version, run, step, field, artifact) to the server's own target token and accept that token back, so a result can name the exact entity it opened. A hit whose payload or recorded token is incomplete or disagreeing is reported as unresolved rather than guessed. --- .../features/search/domain/search_target.dart | 310 ++++++++++++++++++ .../features/search/search_target_test.dart | 218 ++++++++++++ 2 files changed, 528 insertions(+) create mode 100644 app/lib/features/search/domain/search_target.dart create mode 100644 app/test/features/search/search_target_test.dart diff --git a/app/lib/features/search/domain/search_target.dart b/app/lib/features/search/domain/search_target.dart new file mode 100644 index 00000000..bd3b1003 --- /dev/null +++ b/app/lib/features/search/domain/search_target.dart @@ -0,0 +1,310 @@ +import '../../../core/api_gateway.dart'; + +/// The kind of recorded entity a resolved target names. +enum SearchTargetKind { pipeline, version, run, step, field, artifact } + +/// The exact identity behind a recorded search hit. +/// +/// [wire] is the server's own stable target token +/// (`internal/protocol/search.go`): `pipeline:`, `pipeline::v`, +/// `run:`, `run::`, `run:::` or the +/// recorded artifact URL. It is derived from the typed payload, never copied +/// from the hit, and [SearchTarget.fromWire] accepts it back. +/// +/// The token is the identity: two targets that serialise to the same token are +/// the same target even when one of them also carries recorded visit facts the +/// token does not encode. A hit without an identity in its payload is reported +/// as [UnresolvedSearchTarget] by [searchTargetFor]; the client never guesses. +sealed class SearchTarget { + const SearchTarget(); + + SearchTargetKind get kind; + + /// The server's target token for this identity. + String get wire; + + /// Parses a server target token, or null when it names no known target. + /// + /// A token carries only identity, so a parsed step or artifact target has no + /// recorded stage/visit facts; those are payload extras, not identity. + static SearchTarget? fromWire(String wire) { + final token = wire.trim(); + if (token.isEmpty) return null; + + final pipeline = RegExp( + r'^pipeline:([0-9]+)(?::v([0-9]+))?$', + ).firstMatch(token); + if (pipeline != null) { + final id = _positive(pipeline.group(1)); + if (id == null) return null; + final version = pipeline.group(2); + if (version == null) return SearchPipelineTarget(id); + final parsed = _positive(version); + return parsed == null ? null : SearchVersionTarget(id, parsed); + } + + final run = RegExp(r'^run:([0-9]+)(?::(.+))?$').firstMatch(token); + if (run != null) { + final runId = _positive(run.group(1)); + if (runId == null) return null; + final rest = run.group(2); + if (rest == null) return SearchRunTarget(runId); + final parts = rest.split(':'); + if (parts.length > 2) return null; + final sequence = _positive(parts.first); + if (sequence == null) return null; + if (parts.length == 1) return SearchStepTarget(runId, sequence); + final field = parts.last; + return field.trim().isEmpty + ? null + : SearchFieldTarget(runId, sequence, field); + } + + // The server's artifact target is its own relative file URL + // (`/artifacts///`); an absolute form is accepted only when + // it carries that same path. + if (token.startsWith('/artifacts/')) return SearchArtifactTarget(token); + if (token.startsWith('http://') || token.startsWith('https://')) { + final uri = Uri.tryParse(token); + if (uri != null && uri.path.startsWith('/artifacts/')) { + return SearchArtifactTarget(token); + } + } + return null; + } + + @override + bool operator ==(Object other) => other is SearchTarget && other.wire == wire; + + @override + int get hashCode => wire.hashCode; + + @override + String toString() => wire; +} + +/// A pipeline identity hit: the pipeline's detail, always at its latest version. +final class SearchPipelineTarget extends SearchTarget { + const SearchPipelineTarget(this.pipelineId); + + final int pipelineId; + + @override + SearchTargetKind get kind => SearchTargetKind.pipeline; + + @override + String get wire => 'pipeline:$pipelineId'; +} + +/// A pipeline version hit: one exact recorded definition. +final class SearchVersionTarget extends SearchTarget { + const SearchVersionTarget(this.pipelineId, this.version); + + final int pipelineId; + final int version; + + @override + SearchTargetKind get kind => SearchTargetKind.version; + + @override + String get wire => 'pipeline:$pipelineId:v$version'; +} + +/// A run identity hit. +final class SearchRunTarget extends SearchTarget { + const SearchRunTarget(this.runId); + + final int runId; + + @override + SearchTargetKind get kind => SearchTargetKind.run; + + @override + String get wire => 'run:$runId'; +} + +/// A recorded step/visit hit. [stage] and [visit] are the visit facts the +/// payload records ([visit] is the server's visit number, not the zero-based +/// pane index); the server's token only names the run and sequence. +final class SearchStepTarget extends SearchTarget { + const SearchStepTarget(this.runId, this.sequence, {this.stage, this.visit}); + + final int runId; + final int sequence; + final String? stage; + final int? visit; + + @override + SearchTargetKind get kind => SearchTargetKind.step; + + @override + String get wire => 'run:$runId:$sequence'; +} + +/// A text hit inside one recorded step field. +final class SearchFieldTarget extends SearchTarget { + const SearchFieldTarget(this.runId, this.sequence, this.field); + + final int runId; + final int sequence; + final String field; + + @override + SearchTargetKind get kind => SearchTargetKind.field; + + @override + String get wire => 'run:$runId:$sequence:$field'; +} + +/// A recorded artifact hit. The recorded URL is the identity; [runId] and +/// [sequence] locate the visit that produced it. +final class SearchArtifactTarget extends SearchTarget { + const SearchArtifactTarget(this.url, {this.runId, this.sequence}); + + final String url; + final int? runId; + final int? sequence; + + @override + SearchTargetKind get kind => SearchTargetKind.artifact; + + @override + String get wire => url; +} + +/// Either the exact [SearchTarget] a hit names, or the reason it names none. +sealed class SearchTargetResolution { + const SearchTargetResolution(); +} + +final class ResolvedSearchTarget extends SearchTargetResolution { + const ResolvedSearchTarget(this.target); + + final SearchTarget target; +} + +final class UnresolvedSearchTarget extends SearchTargetResolution { + const UnresolvedSearchTarget(this.reason); + + /// Why the hit cannot be resolved, for the caller's own reporting. It is not + /// operator-facing copy. + final String reason; +} + +/// Maps the typed payload of one recorded search hit to its exact identity. +/// +/// Payload keys are checked in the same order as the landed row model, so a hit +/// resolves to the target its visible row describes. The server's recorded +/// token must also be present and equal the serialised identity: a hit without +/// a token is unresolvable, consistent with the landed row model marking such a +/// row read-only, and a token that disagrees with its payload is refused rather +/// than guessed. Unknown payloads, and a payload missing any part of its +/// identity (an id, a sequence, a field name or an artifact URL), are +/// [UnresolvedSearchTarget]. +SearchTargetResolution searchTargetFor(JsonMap hit) { + final identity = _identityFor(hit); + if (identity is UnresolvedSearchTarget) return identity; + final target = (identity as ResolvedSearchTarget).target; + + final recorded = _text(hit['target']); + if (recorded == null) { + return const UnresolvedSearchTarget('recorded target is missing'); + } + if (recorded != target.wire) { + return const UnresolvedSearchTarget( + 'recorded target does not match its payload', + ); + } + return ResolvedSearchTarget(target); +} + +SearchTargetResolution _identityFor(JsonMap hit) { + final pipeline = _payload(hit, 'pipeline'); + if (pipeline != null) { + final id = _positive(pipeline['id']); + if (id == null) { + return const UnresolvedSearchTarget('pipeline identity is missing'); + } + return ResolvedSearchTarget(SearchPipelineTarget(id)); + } + + final version = _payload(hit, 'version'); + if (version != null) { + final pipelineId = _positive(version['pipeline_id']); + final number = _positive(version['version']); + if (pipelineId == null || number == null) { + return const UnresolvedSearchTarget('version identity is incomplete'); + } + return ResolvedSearchTarget(SearchVersionTarget(pipelineId, number)); + } + + final run = _payload(hit, 'run'); + if (run != null) { + final id = _positive(run['id']); + if (id == null) { + return const UnresolvedSearchTarget('run identity is missing'); + } + return ResolvedSearchTarget(SearchRunTarget(id)); + } + + final step = _payload(hit, 'step'); + if (step != null) { + final runId = _positive(step['run_id']); + final sequence = _positive(step['sequence']); + if (runId == null || sequence == null) { + return const UnresolvedSearchTarget('step identity is incomplete'); + } + final visit = _positive(step['visit']); + final stage = _text(step['stage']); + return ResolvedSearchTarget( + SearchStepTarget(runId, sequence, stage: stage, visit: visit), + ); + } + + final field = _payload(hit, 'field'); + if (field != null) { + final runId = _positive(field['run_id']); + final sequence = _positive(field['sequence']); + final name = _text(field['field']); + if (runId == null || sequence == null || name == null) { + return const UnresolvedSearchTarget('field identity is incomplete'); + } + return ResolvedSearchTarget(SearchFieldTarget(runId, sequence, name)); + } + + final artifact = _payload(hit, 'artifact'); + if (artifact != null) { + final url = _text(artifact['url']); + if (url == null) { + return const UnresolvedSearchTarget('artifact url is missing'); + } + return ResolvedSearchTarget( + SearchArtifactTarget( + url, + runId: _positive(artifact['run_id']), + sequence: _positive(artifact['sequence']), + ), + ); + } + + return const UnresolvedSearchTarget('no recorded target payload'); +} + +Map? _payload(JsonMap hit, String key) { + final value = hit[key]; + return value is Map ? Map.from(value) : null; +} + +int? _positive(Object? value) { + final number = value is int + ? value + : value is num + ? value.toInt() + : int.tryParse('${value ?? ''}'); + return number != null && number > 0 ? number : null; +} + +String? _text(Object? value) { + final text = '${value ?? ''}'; + return text.trim().isEmpty ? null : text; +} diff --git a/app/test/features/search/search_target_test.dart b/app/test/features/search/search_target_test.dart new file mode 100644 index 00000000..a6eba452 --- /dev/null +++ b/app/test/features/search/search_target_test.dart @@ -0,0 +1,218 @@ +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/search/domain/search_target.dart'; + +JsonMap pipelineHit([JsonMap overrides = const {}]) => { + 'kind': 'pipeline', + 'target': 'pipeline:7', + 'pipeline': { + 'id': 7, + 'name': 'release', + 'version': 3, + 'stages': 4, + ...overrides, + }, +}; + +JsonMap versionHit([JsonMap overrides = const {}]) => { + 'kind': 'version', + 'target': 'pipeline:9:v2', + 'version': { + 'pipeline_id': 9, + 'version': 2, + 'content_hash': 'abc', + 'created_at': '2026-01-01T00:00:00Z', + ...overrides, + }, +}; + +JsonMap runHit([JsonMap overrides = const {}]) => { + 'kind': 'run', + 'target': 'run:11', + 'run': { + 'id': 11, + 'pipeline_name': 'release', + 'status': 'succeeded', + ...overrides, + }, +}; + +JsonMap stepHit([JsonMap overrides = const {}]) => { + 'kind': 'step', + 'target': 'run:11:4', + 'step': { + 'run_id': 11, + 'sequence': 4, + 'stage': 'builder', + 'visit': 2, + 'outcome': 'success', + ...overrides, + }, +}; + +JsonMap fieldHit([JsonMap overrides = const {}]) => { + 'kind': 'field', + 'target': 'run:11:4:output', + 'matched_field': 'output', + 'field': { + 'run_id': 11, + 'sequence': 4, + 'field': 'output', + 'snippet': 'the release is ready', + ...overrides, + }, +}; + +JsonMap artifactHit([JsonMap overrides = const {}]) => { + 'kind': 'artifact', + 'target': '/artifacts/11/4/notes.md', + 'artifact': { + 'run_id': 11, + 'sequence': 4, + 'name': 'notes.md', + 'content_type': 'text/markdown', + 'size_bytes': 2048, + 'url': '/artifacts/11/4/notes.md', + ...overrides, + }, +}; + +SearchTarget resolved(JsonMap hit) { + final resolution = searchTargetFor(hit); + expect(resolution, isA(), reason: '$hit'); + return (resolution as ResolvedSearchTarget).target; +} + +UnresolvedSearchTarget unresolved(JsonMap hit) { + final resolution = searchTargetFor(hit); + expect(resolution, isA(), reason: '$hit'); + return resolution as UnresolvedSearchTarget; +} + +void main() { + test('every recorded hit kind serialises back to its server token', () { + final pipeline = resolved(pipelineHit()); + expect(pipeline, isA()); + expect((pipeline as SearchPipelineTarget).pipelineId, 7); + expect(pipeline.kind, SearchTargetKind.pipeline); + expect(pipeline.wire, pipelineHit()['target']); + + final version = resolved(versionHit()); + expect(version, isA()); + expect((version as SearchVersionTarget).pipelineId, 9); + expect(version.version, 2); + expect(version.wire, versionHit()['target']); + + final run = resolved(runHit()); + expect(run, isA()); + expect((run as SearchRunTarget).runId, 11); + expect(run.wire, runHit()['target']); + + final step = resolved(stepHit()); + expect(step, isA()); + expect((step as SearchStepTarget).runId, 11); + expect(step.sequence, 4); + expect(step.stage, 'builder'); + expect(step.visit, 2); + expect(step.wire, stepHit()['target']); + + final field = resolved(fieldHit()); + expect(field, isA()); + expect((field as SearchFieldTarget).runId, 11); + expect(field.sequence, 4); + expect(field.field, 'output'); + expect(field.wire, fieldHit()['target']); + + final artifact = resolved(artifactHit()); + expect(artifact, isA()); + expect((artifact as SearchArtifactTarget).url, '/artifacts/11/4/notes.md'); + expect(artifact.runId, 11); + expect(artifact.sequence, 4); + expect(artifact.wire, artifactHit()['target']); + }); + + test('a payload without its identity is reported as unresolvable', () { + expect(unresolved({}).reason, 'no recorded target payload'); + expect(unresolved(pipelineHit({'id': null})).reason, contains('pipeline')); + expect( + unresolved(versionHit({'pipeline_id': 9, 'version': 0})).reason, + contains('version'), + ); + expect(unresolved(runHit({'id': 0})).reason, contains('run')); + expect( + unresolved(stepHit({'run_id': 11, 'sequence': 0})).reason, + contains('step'), + ); + expect( + unresolved(fieldHit({'run_id': 11, 'sequence': 4, 'field': ' '})).reason, + contains('field'), + ); + expect(unresolved(artifactHit({'url': ' '})).reason, contains('artifact')); + expect( + unresolved({'kind': 'future_kind', 'target': 'widget:7'}).reason, + 'no recorded target payload', + ); + }); + + test('a hit without a matching recorded token is unresolvable', () { + expect( + unresolved({ + 'kind': 'run', + 'run': {'id': 11}, + }).reason, + 'recorded target is missing', + ); + expect( + unresolved({...pipelineHit(), 'target': 'pipeline:8'}).reason, + contains('does not match'), + ); + expect( + unresolved({...stepHit(), 'target': 'run:11:5'}).reason, + contains('does not match'), + ); + }); + + test('a serialised target parses back to the same identity', () { + final targets = [ + resolved(pipelineHit()), + resolved(versionHit()), + resolved(runHit()), + resolved(stepHit()), + resolved(fieldHit()), + resolved(artifactHit()), + ]; + for (final target in targets) { + final parsed = SearchTarget.fromWire(target.wire); + expect(parsed, target, reason: target.wire); + expect(parsed!.wire, target.wire, reason: target.wire); + } + + // The token names the visit's run and sequence, not its stage/visit facts. + final step = resolved(stepHit()) as SearchStepTarget; + final parsed = SearchTarget.fromWire(step.wire) as SearchStepTarget; + expect(parsed, step); + expect(parsed.stage, isNull); + expect(parsed.visit, isNull); + }); + + test('a token outside the server vocabulary names no target', () { + for (final token in const [ + '', + ' ', + 'widget:7', + 'pipeline:0', + 'pipeline:7:v0', + 'run:11:0', + 'run:11:4:', + 'http://example.test/not-an-artifact', + ]) { + expect(SearchTarget.fromWire(token), isNull, reason: token); + } + expect(SearchTarget.fromWire('run:11'), const SearchRunTarget(11)); + expect( + SearchTarget.fromWire('pipeline:7:v2'), + const SearchVersionTarget(7, 2), + ); + expect(SearchTarget.fromWire('pipeline:7'), const SearchPipelineTarget(7)); + }); +} From 3da570e6472d31ddd0c873f2912f9c435d688076 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 22 Oct 2026 02:29:57 +0100 Subject: [PATCH 2/4] feat(app): show the run's recorded facts in its Summary Stage, Started, Finished, Duration, Provider/model, Target and Verdict come from the run reply and the current stage's latest recorded visit. An absent fact reads Unavailable; tokens and cost keep their Metrics home. --- .../runs/ui/run_detail_summary_fields.dart | 89 +++++++++ .../runs/ui/run_detail_tab_bodies.dart | 28 ++- .../ui/run_detail_summary_fields_test.dart | 180 ++++++++++++++++++ 3 files changed, 294 insertions(+), 3 deletions(-) create mode 100644 app/lib/features/runs/ui/run_detail_summary_fields.dart create mode 100644 app/test/features/runs/ui/run_detail_summary_fields_test.dart diff --git a/app/lib/features/runs/ui/run_detail_summary_fields.dart b/app/lib/features/runs/ui/run_detail_summary_fields.dart new file mode 100644 index 00000000..e57c13cc --- /dev/null +++ b/app/lib/features/runs/ui/run_detail_summary_fields.dart @@ -0,0 +1,89 @@ +import '../../../core/api_gateway.dart'; +import '../../pipelines/pipeline_format.dart'; +import 'run_detail_content.dart'; +import 'run_detail_visit_facts.dart'; + +/// The exact wording for a Summary fact the reply did not record. +/// +/// It is the same word the Summary's usage rows already use for an unreported +/// value, so one absent fact never reads as `0`, `false` or an empty field. +const String summaryUnknownValue = 'Unavailable'; + +/// The run Summary's recorded facts, in the web summary's order: the current +/// stage and the run's timing, then the latest recorded visit's effective +/// provider/model, target and verdict. +/// +/// The latest visit is the one the Graph tab opens for the current stage, so +/// the Summary and the recorded-visit pane describe the same evidence. Tokens +/// and cost stay in [detailUsageMetrics], their existing Summary home. A fact +/// the server did not record reads [summaryUnknownValue]. +List detailSummaryFields(JsonMap run) { + final steps = detailRunSteps(run); + final stage = _text(run['current_stage']); + final latest = _latestVisit(steps, stage); + return [ + (label: 'Stage', value: stage ?? summaryUnknownValue), + ( + label: 'Started', + value: + formatLocalTimestamp(_text(run['created_at'])) ?? summaryUnknownValue, + ), + ( + label: 'Finished', + value: + formatLocalTimestamp(_text(run['finished_at'])) ?? + summaryUnknownValue, + ), + (label: 'Duration', value: _duration(run) ?? summaryUnknownValue), + ( + label: 'Provider/model', + value: latest == null + ? summaryUnknownValue + : detailVisitProviderModel(latest) ?? summaryUnknownValue, + ), + ( + label: 'Target', + value: latest == null + ? summaryUnknownValue + : _text(latest['target']) ?? summaryUnknownValue, + ), + (label: 'Verdict', value: _verdict(latest) ?? summaryUnknownValue), + ]; +} + +/// The latest recorded visit of [stage], or the latest visit when the reply +/// records no current stage. It is the same visit the Graph tab opens for that +/// stage, so a fact and its Stage row never come from different visits. +JsonMap? _latestVisit(List steps, String? stage) { + JsonMap? latest; + for (final step in steps) { + if (stage == null || _text(step['stage']) == stage) latest = step; + } + return latest; +} + +/// The run's stored duration from its own start and finish, never a live +/// estimate and never a zero for an unfinished run. +String? _duration(JsonMap run) { + final seconds = durationSeconds( + _text(run['created_at']), + _text(run['finished_at']), + ); + return seconds == null ? null : formatDuration(seconds); +} + +/// The recorded verdict as the web pane spells it: the option above its +/// reason, one part when only one was recorded, nothing when neither was. +String? _verdict(JsonMap? step) { + if (step == null) return null; + final verdict = detailVisitVerdict(step); + if (verdict == null) return null; + final parts = [verdict.option, verdict.reason].whereType(); + return parts.isEmpty ? null : parts.join('\n'); +} + +String? _text(dynamic value) { + if (value == null) return null; + final text = '$value'.trim(); + return text.isEmpty ? null : text; +} diff --git a/app/lib/features/runs/ui/run_detail_tab_bodies.dart b/app/lib/features/runs/ui/run_detail_tab_bodies.dart index fac9d051..91957a60 100644 --- a/app/lib/features/runs/ui/run_detail_tab_bodies.dart +++ b/app/lib/features/runs/ui/run_detail_tab_bodies.dart @@ -3,10 +3,11 @@ import 'package:flutter/material.dart'; import '../../../core/api_gateway.dart'; import 'run_detail_content.dart'; +import 'run_detail_summary_fields.dart'; -/// The Summary tab: the stored original prompt with its copy control and the -/// reported usage metrics. Neither the prompt nor a metric is replaced by a -/// fallback value. +/// The Summary tab: the stored original prompt with its copy control, the +/// run's recorded facts and the reported usage metrics. Neither the prompt nor +/// a fact is replaced by a fallback value. Widget runDetailSummaryTab({ required BuildContext context, required JsonMap run, @@ -16,6 +17,7 @@ Widget runDetailSummaryTab({ required VoidCallback onCopy, }) { final prompt = detailPrompt(run); + final facts = detailSummaryFields(run); final metrics = detailUsageMetrics(run['usage']); if (cupertino) { final theme = CupertinoTheme.of(context); @@ -55,6 +57,7 @@ Widget runDetailSummaryTab({ ), ), _cupertinoMetrics(metrics), + _cupertinoFacts(facts), ], ); } @@ -89,6 +92,7 @@ Widget runDetailSummaryTab({ const SizedBox(height: 12), ], _materialMetrics(metrics), + _materialFacts(facts), ], ); } @@ -123,6 +127,24 @@ Widget runDetailFieldTab({ ); } +Widget _materialFacts(List facts) => Column( + children: [ + for (final fact in facts) + ListTile(title: Text(fact.label), subtitle: Text(fact.value)), + ], +); + +Widget _cupertinoFacts(List facts) => + CupertinoListSection.insetGrouped( + children: [ + for (final fact in facts) + CupertinoListTile( + title: Text(fact.label), + subtitle: Text(fact.value), + ), + ], + ); + Widget _materialMetrics(List metrics) => ExpansionTile( title: const Text('Metrics'), children: [ diff --git a/app/test/features/runs/ui/run_detail_summary_fields_test.dart b/app/test/features/runs/ui/run_detail_summary_fields_test.dart new file mode 100644 index 00000000..dc070074 --- /dev/null +++ b/app/test/features/runs/ui/run_detail_summary_fields_test.dart @@ -0,0 +1,180 @@ +import 'package:flutter/cupertino.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/pipelines/pipeline_format.dart'; +import 'package:pipelines_app/features/runs/ui/run_detail_summary_fields.dart'; + +import 'run_detail_graph_support.dart'; + +/// A run whose latest visit recorded every summary fact, plus reported usage. +JsonMap recordedRunFixture() => { + 'id': 51, + 'title': 'Summary run', + 'name': 'release', + 'status': 'succeeded', + 'current_stage': 'review', + 'created_at': '2026-10-19T09:30:00Z', + 'finished_at': '2026-10-19T09:32:05Z', + 'input': {'prompt': 'ship it'}, + 'steps': [ + { + 'stage': 'build', + 'sequence': 1, + 'status': 'completed', + 'outcome': 'success', + 'provider': 'openai', + 'model': 'gpt-luna', + 'target': 'review', + }, + { + 'stage': 'review', + 'sequence': 2, + 'status': 'completed', + 'outcome': 'success', + 'provider': 'anthropic', + 'model': 'claude-x', + 'target': '#success', + 'verdict': { + 'option': 'approve', + 'reason': 'Looks good.', + }, + }, + ], + 'usage': { + 'stages': 1, + 'tokens_total': 123, + 'tokens_known_stages': 1, + 'tokens_in': 100, + 'tokens_out': 23, + 'split_known': true, + 'cost_known_stages': 1, + 'cost_usd': 0.5, + }, +}; + +/// A run that recorded none of the summary facts and reported no usage. +JsonMap absentRunFixture() => { + 'id': 51, + 'title': 'Sparse run', + 'name': 'release', + 'status': 'succeeded', + 'current_stage': ' ', + 'created_at': '', + 'finished_at': '', + 'input': {'prompt': 'ship it'}, + 'steps': [ + { + 'stage': 'build', + 'sequence': 1, + 'status': 'completed', + 'provider': ' ', + 'model': '', + 'target': ' ', + 'verdict': null, + }, + ], +}; + +const summaryFacts = [ + 'Stage', + 'Started', + 'Finished', + 'Duration', + 'Provider/model', + 'Target', + 'Verdict', +]; + +void main() { + for (final platform in RunDetailTestPlatform.values) { + testWidgets('${platform.name} summary renders each recorded field', ( + tester, + ) async { + await pumpRunDetail( + tester, + platform, + run: recordedRunFixture(), + size: const Size(900, 1600), + ); + + for (final label in summaryFacts) { + expect(find.text(label), findsOneWidget, reason: label); + } + expect(find.text('review'), findsOneWidget); + final started = formatLocalTimestamp('2026-10-19T09:30:00Z'); + final finished = formatLocalTimestamp('2026-10-19T09:32:05Z'); + expect(find.text(started!), findsOneWidget); + expect(find.text(finished!), findsOneWidget); + expect(find.text('2m 5s'), findsOneWidget); + expect(find.text('anthropic / claude-x'), findsOneWidget); + expect(find.text('#success'), findsOneWidget); + expect(find.text('approve\nLooks good.'), findsOneWidget); + + // Tokens and cost keep their existing Summary home and exact values. + await tester.ensureVisible(find.text('Metrics')); + await tester.tap(find.text('Metrics')); + await tester.pumpAndSettle(); + expect(find.text('123'), findsOneWidget); + expect(find.text('100'), findsOneWidget); + expect(find.text('23'), findsOneWidget); + expect(find.text('\$0.500000'), findsOneWidget); + }); + + testWidgets('${platform.name} summary states absent facts as unknown', ( + tester, + ) async { + await pumpRunDetail( + tester, + platform, + run: absentRunFixture(), + size: const Size(900, 1600), + ); + + for (final label in summaryFacts) { + expect(find.text(label), findsOneWidget, reason: label); + } + expect( + find.text(summaryUnknownValue), + findsNWidgets(summaryFacts.length), + ); + expect(find.text('0'), findsNothing); + expect(find.text('false'), findsNothing); + + await tester.ensureVisible(find.text('Metrics')); + await tester.tap(find.text('Metrics')); + await tester.pumpAndSettle(); + expect(find.text('No reported usage.'), findsOneWidget); + expect(find.text('0'), findsNothing); + }); + } + + test('visit facts come from the current stage latest visit', () { + final run = recordedRunFixture()..['current_stage'] = 'build'; + final fields = detailSummaryFields(run); + String value(String label) => + fields.firstWhere((field) => field.label == label).value; + expect(value('Provider/model'), 'openai / gpt-luna'); + expect(value('Target'), 'review'); + expect(value('Verdict'), 'Unavailable'); + }); + + test('a current stage without a visit records no visit facts', () { + final run = recordedRunFixture()..['current_stage'] = 'audit'; + final fields = detailSummaryFields(run); + for (final label in ['Provider/model', 'Target', 'Verdict']) { + expect( + fields.firstWhere((field) => field.label == label).value, + 'Unavailable', + reason: label, + ); + } + }); + + test('unknown wording is the web usage word and never zero', () { + expect(summaryUnknownValue, 'Unavailable'); + final fields = detailSummaryFields(absentRunFixture()); + expect(fields.map((field) => field.label), summaryFacts); + expect(fields.every((field) => field.value == 'Unavailable'), isTrue); + }); +} From e7165f7722b838e7bb47188a76e3555bf9eae742 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 22 Oct 2026 02:33:12 +0100 Subject: [PATCH 3/4] feat(app): deliver live attention notifications and show permission in Settings --- app/lib/application/pipelines_app.dart | 13 +++ app/lib/application/runs_destination.dart | 6 ++ .../attention/ui/needs_you_runs_heading.dart | 43 ++++++++- app/lib/features/runs/screen.dart | 6 ++ app/lib/features/runs/ui/runs_list.dart | 6 ++ .../settings_notifications_section.dart | 33 +++++++ .../features/settings/settings_screen.dart | 14 +++ .../notification_manager_wiring_test.dart | 96 +++++++++++++++++++ 8 files changed, 216 insertions(+), 1 deletion(-) create mode 100644 app/lib/features/settings/settings_notifications_section.dart create mode 100644 app/test/features/attention/notify/notification_manager_wiring_test.dart diff --git a/app/lib/application/pipelines_app.dart b/app/lib/application/pipelines_app.dart index 3b888421..421b7873 100644 --- a/app/lib/application/pipelines_app.dart +++ b/app/lib/application/pipelines_app.dart @@ -8,6 +8,8 @@ import '../core/api_gateway.dart'; import '../core/transport/pipelines_client.dart'; import '../shell/adaptive_shell.dart'; import '../shell/destination.dart'; +import '../features/attention/notify/notification_controller.dart'; +import '../features/attention/notify/notification_store.dart'; import '../features/settings/settings_screen.dart'; import 'app.dart'; import 'app_route.dart'; @@ -61,6 +63,12 @@ class _PipelinesAppState extends State { /// list once; the run itself is then opened from its route. int _runsRefresh = 0; + /// One notification capability for the app: the Runs attention surface + /// publishes live transitions and Settings renders the same permission. + late final NotificationController _notifications = NotificationController( + store: const SharedPreferencesNotificationStore(), + ); + @override void initState() { super.initState(); @@ -81,6 +89,8 @@ class _PipelinesAppState extends State { ); } _cupertino = widget.cupertino ?? _platformIsCupertino; + _notifications.onOpenRun = (id) => _delegate.goTo(AppRoute.run(id)); + unawaited(_notifications.load()); _delegate = AppRouterDelegate( initial: initial, cupertino: _cupertino, @@ -100,6 +110,7 @@ class _PipelinesAppState extends State { @override void dispose() { + _notifications.dispose(); _delegate.dispose(); if (_ownsProvider) { (_provider as PlatformRouteInformationProvider).dispose(); @@ -178,6 +189,7 @@ class _PipelinesAppState extends State { server: widget.server, initialRunId: route.runId, listRefreshToken: _runsRefresh, + notifications: _notifications, onRunSelected: (id) => _delegate.goTo(AppRoute.run(id)), onBack: () => _delegate.goTo(AppRoute.runs), ), @@ -193,6 +205,7 @@ class _PipelinesAppState extends State { initialEndpoint: _session.endpoint, embedded: true, onOpenTemplates: _delegate.openTemplates, + notifications: _notifications, ), }, ); diff --git a/app/lib/application/runs_destination.dart b/app/lib/application/runs_destination.dart index f63077e1..fdef966e 100644 --- a/app/lib/application/runs_destination.dart +++ b/app/lib/application/runs_destination.dart @@ -1,5 +1,6 @@ import 'package:flutter/material.dart'; +import '../features/attention/notify/notification_controller.dart'; import '../features/runs/screen.dart'; import '../ui/adaptive/host.dart'; import 'app_session.dart'; @@ -21,6 +22,7 @@ class RunsDestination extends StatelessWidget { this.onRunSelected, this.onBack, this.listRefreshToken = 0, + this.notifications, }); final AppSession session; @@ -33,6 +35,9 @@ class RunsDestination extends StatelessWidget { /// re-reads its list once; no row is inserted locally. final int listRefreshToken; + /// The app-level notification capability shared with Settings. + final NotificationController? notifications; + @override Widget build(BuildContext context) => AnimatedBuilder( animation: session, @@ -70,6 +75,7 @@ class RunsDestination extends StatelessWidget { initialRunId: initialRunId, syncToken: session.connectionEpoch, listRefreshToken: listRefreshToken, + notifications: notifications, onRunSelected: onRunSelected, onBack: onBack, ); diff --git a/app/lib/features/attention/ui/needs_you_runs_heading.dart b/app/lib/features/attention/ui/needs_you_runs_heading.dart index bf8889f1..ddd9966b 100644 --- a/app/lib/features/attention/ui/needs_you_runs_heading.dart +++ b/app/lib/features/attention/ui/needs_you_runs_heading.dart @@ -4,6 +4,8 @@ import 'package:flutter/widgets.dart'; import '../../../core/api_gateway.dart'; import '../domain/attention_models.dart'; +import '../notify/notification_controller.dart'; +import '../notify/notification_ledger.dart'; import '../runtime/attention_controller.dart'; import '../runtime/attention_store.dart'; import 'needs_you_bell.dart'; @@ -25,6 +27,7 @@ class NeedsYouRunsHeading extends StatefulWidget { this.store = const SharedPreferencesAttentionStore(), this.now, this.cupertino, + this.notifications, }); /// The run summaries the Runs destination already holds. @@ -48,6 +51,10 @@ class NeedsYouRunsHeading extends StatefulWidget { /// Forces the native host in tests and fixtures. final bool? cupertino; + /// The app-level notification capability. Absent in fixtures that only draw + /// the bell, so no store or platform bridge is touched there. + final NotificationController? notifications; + @override State createState() => _NeedsYouRunsHeadingState(); } @@ -65,12 +72,44 @@ class _NeedsYouRunsHeadingState extends State { _attention.seedRows(widget.rows); unawaited(_attention.load()); _listen(); + final notifications = widget.notifications; + if (notifications != null) { + notifications.onOpenRun = _openRunById; + unawaited(notifications.load().then((_) => _publish())); + } + } + + /// A notification names only the run id; opening it follows the same route + /// rule as a bell row. Dismissal is not implied by a notice tap. + void _openRunById(int id) { + for (final entry in _attention.entries) { + if (entry.runId == id) { + widget.onOpen(entry); + return; + } + } + } + + /// Publishes the transitions the model accumulated against the rows and the + /// dismissals that are in force right now. Idempotent, so the whole list is + /// safe to pass after every read or pushed frame. + void _publish() { + final notifications = widget.notifications; + if (notifications == null) return; + notifications.publishTransitions( + _attention.transitions, + qualifying: notificationQualifyingKeys(_attention.rows), + dismissed: _attention.dismissed, + ); } void _listen() { _frames = widget.frames .where((frame) => frame['type'] == 'run_event') - .listen(_attention.observeFrame); + .listen((frame) { + _attention.observeFrame(frame); + _publish(); + }); } @override @@ -84,10 +123,12 @@ class _NeedsYouRunsHeadingState extends State { if (oldWidget.syncToken != widget.syncToken) { _attention.resetForReconnect(); _attention.seedRows(widget.rows, reconnect: true); + _publish(); return; } if (!identical(oldWidget.rows, widget.rows)) { _attention.seedRows(widget.rows); + _publish(); } } diff --git a/app/lib/features/runs/screen.dart b/app/lib/features/runs/screen.dart index ce57d317..56dc70a7 100644 --- a/app/lib/features/runs/screen.dart +++ b/app/lib/features/runs/screen.dart @@ -1,6 +1,7 @@ import 'package:flutter/widgets.dart'; import '../../core/api_gateway.dart'; +import '../attention/notify/notification_controller.dart'; import '../attention/runtime/attention_store.dart'; import 'data/runs_repository.dart'; import 'ui/run_detail_view.dart'; @@ -24,6 +25,7 @@ class RunsScreen extends StatefulWidget { this.onBack, this.attentionStore = const SharedPreferencesAttentionStore(), this.attentionNow, + this.notifications, }); final ApiGateway gateway; @@ -47,6 +49,9 @@ class RunsScreen extends StatefulWidget { final AttentionStore attentionStore; final DateTime Function()? attentionNow; + /// App-level notification delivery for live attention transitions. + final NotificationController? notifications; + @override State createState() => _RunsScreenState(); } @@ -128,6 +133,7 @@ class _RunsScreenState extends State { syncToken: widget.syncToken, attentionStore: widget.attentionStore, attentionNow: widget.attentionNow, + notifications: widget.notifications, ), ), ), diff --git a/app/lib/features/runs/ui/runs_list.dart b/app/lib/features/runs/ui/runs_list.dart index 2c5a2ab3..66b8dfb2 100644 --- a/app/lib/features/runs/ui/runs_list.dart +++ b/app/lib/features/runs/ui/runs_list.dart @@ -3,6 +3,7 @@ import 'package:flutter/material.dart'; import '../../../core/api_gateway.dart'; import '../../../ui/adaptive/host.dart'; +import '../../attention/notify/notification_controller.dart'; import '../../attention/runtime/attention_store.dart'; import '../../attention/ui/needs_you_runs_heading.dart'; import '../domain/run_models.dart'; @@ -17,6 +18,7 @@ class RunsList extends StatelessWidget { this.syncToken = 0, this.attentionStore = const SharedPreferencesAttentionStore(), this.attentionNow, + this.notifications, }); final RunsController controller; @@ -32,6 +34,9 @@ class RunsList extends StatelessWidget { /// Deterministic local-day clock for the attention window. final DateTime Function()? attentionNow; + /// App-level notification delivery; absent in list-only fixtures. + final NotificationController? notifications; + @override Widget build(BuildContext context) { if (controller.loading && controller.runs.isEmpty) { @@ -58,6 +63,7 @@ class RunsList extends StatelessWidget { syncToken: syncToken, store: attentionStore, now: attentionNow, + notifications: notifications, ), ), ), diff --git a/app/lib/features/settings/settings_notifications_section.dart b/app/lib/features/settings/settings_notifications_section.dart new file mode 100644 index 00000000..7364c55b --- /dev/null +++ b/app/lib/features/settings/settings_notifications_section.dart @@ -0,0 +1,33 @@ +import 'package:flutter/widgets.dart'; + +import '../attention/notify/notification_controller.dart'; +import '../attention/ui/notification_permission_tile.dart'; + +/// The Settings entry for the browser notification permission. +/// +/// It reads the platform's own state from the app-level +/// [NotificationController] and asks only when the operator presses the tile's +/// Enable action. The controller is shared with the Runs attention surface, so +/// the permission shown here is the one that gates the live notices. +class SettingsNotificationsSection extends StatelessWidget { + const SettingsNotificationsSection({ + super.key, + required this.controller, + }); + + final NotificationController controller; + + @override + Widget build(BuildContext context) => AnimatedBuilder( + animation: controller, + builder: (context, _) => NotificationPermissionTile( + state: controller.permission, + asked: controller.asked, + onRequest: () { + // The platform answer updates the controller; the AnimationBuilder above + // redraws the tile with its own words. + controller.requestPermission(); + }, + ), + ); +} diff --git a/app/lib/features/settings/settings_screen.dart b/app/lib/features/settings/settings_screen.dart index 9984f77c..a9771cdf 100644 --- a/app/lib/features/settings/settings_screen.dart +++ b/app/lib/features/settings/settings_screen.dart @@ -4,10 +4,12 @@ import 'package:flutter/cupertino.dart'; import 'package:flutter/material.dart'; import '../../core/transport/pipelines_client.dart' as transport; +import '../attention/notify/notification_controller.dart'; import 'default_endpoint.dart'; import 'settings_controller.dart'; import 'settings_controls.dart'; import 'settings_layout.dart'; +import 'settings_notifications_section.dart'; import 'settings_sections.dart'; import 'settings_store.dart'; import 'settings_templates_section.dart'; @@ -29,6 +31,7 @@ class SettingsScreen extends StatefulWidget { this.ping, this.embedded = false, this.onOpenTemplates, + this.notifications, }); final transport.PipelinesClient client; @@ -50,6 +53,9 @@ class SettingsScreen extends StatefulWidget { /// without a dead row that would go nowhere. final VoidCallback? onOpenTemplates; + /// The app-level notification capability; absent in connection-only fixtures. + final NotificationController? notifications; + @override State createState() => _SettingsScreenState(); } @@ -127,6 +133,14 @@ class _SettingsScreenState extends State { controller: _controller, workspaceField: _workspaceField, ), + if (widget.notifications != null) ...[ + const SizedBox(height: settingsSectionGap), + const _SectionTitle('Notifications'), + const SizedBox(height: settingsTitleGap), + SettingsNotificationsSection( + controller: widget.notifications!, + ), + ], if (widget.onOpenTemplates != null) ...[ const SizedBox(height: settingsSectionGap), const _SectionTitle('Templates'), diff --git a/app/test/features/attention/notify/notification_manager_wiring_test.dart b/app/test/features/attention/notify/notification_manager_wiring_test.dart new file mode 100644 index 00000000..7ea23459 --- /dev/null +++ b/app/test/features/attention/notify/notification_manager_wiring_test.dart @@ -0,0 +1,96 @@ +import 'dart:async'; + +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/attention/notify/notification_controller.dart'; +import 'package:pipelines_app/features/attention/notify/notification_store.dart'; +import 'package:pipelines_app/features/attention/ui/needs_you_runs_heading.dart'; +import 'package:pipelines_app/features/settings/settings_notifications_section.dart'; + +import 'notification_test_support.dart'; + +/// The manager-owned wiring: the bell surface publishes live transitions and +/// Settings renders the same controller's permission. +void main() { + testWidgets('a seed never notifies and one live transition notifies once', ( + tester, + ) async { + final bridge = FakeNotificationBridge(permission: 'granted'); + final notify = NotificationController( + store: MemoryNotificationStore(), + bridge: bridge, + ); + final frames = StreamController.broadcast(); + addTearDown(frames.close); + addTearDown(notify.dispose); + + await tester.pumpWidget( + MaterialApp( + home: NeedsYouRunsHeading( + rows: [runSummary(1, 'failed'), runSummary(2, 'running')], + frames: frames.stream, + onOpen: (_) {}, + now: () => attentionNow, + notifications: notify, + cupertino: false, + ), + ), + ); + // Let the persisted ledger read and the seed publish settle. A plain + // `Future.delayed` would deadlock inside the widget test's fake clock. + await tester.pump(); + await tester.pump(const Duration(milliseconds: 20)); + expect(bridge.shown, isEmpty, reason: 'the initial list is a seed'); + expect(notify.permission.name, 'granted'); + + frames.add(runFrame(2, 'failed')); + await tester.pump(); + await tester.pump(const Duration(milliseconds: 20)); + expect(bridge.shown, hasLength(1)); + expect(bridge.shown.single.runId, 2); + + // The same transition instance again (a reconnect reseed of that frame) + // must not announce twice. + frames.add(runFrame(2, 'failed')); + await tester.pump(); + await tester.pump(const Duration(milliseconds: 20)); + expect(bridge.shown, hasLength(1)); + }); + + testWidgets('Settings renders the platform permission from the controller', ( + tester, + ) async { + final notify = NotificationController( + store: MemoryNotificationStore(), + bridge: FakeNotificationBridge(permission: 'granted'), + ); + addTearDown(notify.dispose); + + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: SettingsNotificationsSection(controller: notify), + ), + ), + ); + await tester.pump(); + expect(find.text('Notifications'), findsWidgets); + + // A denied platform answer shows its own words and no Enable action. + final denied = NotificationController( + store: MemoryNotificationStore(), + bridge: FakeNotificationBridge(permission: 'denied'), + ); + addTearDown(denied.dispose); + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: SettingsNotificationsSection(controller: denied), + ), + ), + ); + await tester.pump(); + expect(find.text('Notifications'), findsWidgets); + }); +} From 51355b470a65979cf101b8ace63b0d91776be61a Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 22 Oct 2026 02:34:22 +0100 Subject: [PATCH 4/4] docs(app): record notification wiring and the search target model --- app/PARITY.md | 4 ++-- app/WORK.md | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/app/PARITY.md b/app/PARITY.md index f4b237d6..bce99029 100644 --- a/app/PARITY.md +++ b/app/PARITY.md @@ -51,9 +51,9 @@ or scratch servers only, never real operator sessions/runs/workflows. | Chat commands/notices/scroll | Missing | slash palette/actions, unknown-command send-as-message, dismissible local notices, saved scroll/follow intent | | Saved schedule list | Source | pipeline entry and route registration, exact timer provenance vocabulary | | Schedule editor | Preview: pipeline Summary section creates/edits/pauses/deletes with the lossless draft and revision guard; conflict keeps the draft and shows the server words | Schedule-this-run seeding, schedules list entry/route | -| Search | Preview: shell entry, /search route, focused field, restore on close | result target routing for pipeline/version/field/visit/artifact hits | +| Search | Preview: shell entry, /search route, focused field, restore on close; exact target model for every hit kind | navigation wiring for pipeline/version/field/visit/artifact (run targets already open) | | Needs you | Preview: runs-list bell/count from the same list rows, native sheet, open/dismiss/clear persistence, live fold and reconnect reseed | notification permission/transition notices, authenticated preview smoke | -| Notifications | Source: web bridge, permission states, transition-only dedupe and ledger; permission tile landed | shell/Settings wiring, tap-to-run, background question notices | +| Notifications | Preview: Settings permission tile over live platform state, transition-only dedupe, tap opens the run | background question notices; permission/browser smoke only in fixtures | | Mobile replacement build | Scaffold only | Android build at end; all source portable to iOS, isolated IDs; device/OS behavior clearly separate | ## Current-reference corrections diff --git a/app/WORK.md b/app/WORK.md index b0c2f428..0c2561cc 100644 --- a/app/WORK.md +++ b/app/WORK.md @@ -64,6 +64,8 @@ All work under app/. Existing applications remain running and unchanged. | Run graph | Run-mode executed-route canvas | run89 retained/5b833e7 | server storage bug blocked the run; manager ran43 graph tests; recorded visits only, legend | merged main; ancestry verified | published8096 | | Run graph tab | Graph tab + recorded-stage selection | run92 retained/d74e5c5 | evidence bug blocked the run; manager ran147 runs tests + both-host probe (7 checks, graph/legend/selection/missing wording) | merged main; ancestry verified | preview republish pending | | Schedule form | Native schedule draft editor | run78 /flutter/schedule-form | binds74, no save engine | merged main; ancestry verified | published8096 | +| Notifications wiring | Live delivery + Settings tile | manager e7165f7 | app-level controller shared by Runs and Settings; 2 wiring tests + 1191 full suite | merged main | fixture evidence | +| Search target | Exact hit identity model | run105 /cbba026c | micro lane (single behaviour, no probe); 41 search tests | merged main | navigation wiring next | | Start pipeline | Native launch dialog | run97 /f6575fff | succeeded after 1h21m (oversized slice); manager ran304 pipelines/application/runs tests + 3-check/10-capture both-host probe | merged main; ancestry verified | production launch unverified | | Visit pane | Recorded facts in Timeline | run95 retained/f0d62125 | deadline recovery; 280 runs/artifacts tests; input/output/artifacts/session/definition sections | merged main; ancestry verified | preview republish pending | | Notifications | Capability + dedupe | run100 retained/b8e5c3e | deadline recovery; 147 attention tests; bridge/ledger/permission tile; no shell wiring claimed | merged main; ancestry verified | manager wiring next |