Add show_diff chat tool and diff card

The Pipelines MCP server gains show_diff: it runs Git in a repository
inside the operator's home (default: the chat's directory) and records
the per-file patches. Without base it shows uncommitted work against
HEAD; with base it shows everything since the merge base (a pull
request preview), optionally committed changes only. Bounded at 300
files, 256 KiB per patch and 1 MiB total, with partial diffs labelled;
diff bodies share the per-chat retention budget with HTML views.

The chat draws the item as a card listing each changed file with its
stat; a row opens the existing file diff viewer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-21 17:08:02 +00:00
parent 79e5183469
commit 059eb1bb0d
15 changed files with 1077 additions and 16 deletions
@@ -0,0 +1,88 @@
import '../../../core/api_gateway.dart';
import '../../changes/domain/change_capture.dart';
import '../../changes/domain/unified_patch.dart';
/// A `show_diff` item's comparison, as the server records it
/// (`internal/protocol/chat_shown.go` ChatShownDiffBody): a repository's work
/// tree, or HEAD when committed only, against HEAD or the merge base with a
/// base branch, with the same per-file changes a run records.
class ChatShownDiff {
const ChatShownDiff({
required this.repo,
required this.base,
required this.baseCommit,
required this.head,
required this.committedOnly,
required this.files,
required this.additions,
required this.deletions,
required this.capture,
});
/// The diff of a `diff` item, or null for any other item or a malformed one.
static ChatShownDiff? of(JsonMap item) {
final body = item['diff'];
if (item['kind'] != 'diff' || body is! Map) return null;
final changes = body['changes'];
return ChatShownDiff(
repo: _text(body['repo']),
base: _text(body['base']),
baseCommit: _text(body['base_commit']),
head: _text(body['head']),
committedOnly: body['committed_only'] == true,
files: _count(body['files']),
additions: _count(body['additions']),
deletions: _count(body['deletions']),
capture: item['expired'] == true || changes is! Map
? null
: ChangeCapture.fromJson(Map<String, dynamic>.from(changes)),
);
}
final String repo;
final String base;
final String baseCommit;
final String head;
final bool committedOnly;
final int files;
final int additions;
final int deletions;
/// The per-file changes, or null once the server no longer retains them.
final ChangeCapture? capture;
/// The repository's folder name.
String get repoName {
final parts = repo.split('/').where((part) => part.isNotEmpty);
return parts.isEmpty ? repo : parts.last;
}
/// What was compared, in words: the branch against its base and whether
/// uncommitted work is included.
String get comparison {
final head = this.head.isEmpty ? 'HEAD' : this.head;
final against = base.isEmpty
? (baseCommit.isEmpty ? 'no commits yet' : 'uncommitted changes')
: '$head vs $base${committedOnly ? ' · committed only' : ' · with uncommitted work'}';
final where = repoName.isEmpty ? '' : '$repoName · ';
return base.isEmpty ? '$where$head · $against' : '$where$against';
}
/// "3 files changed +12 -4", or "No changes".
String get heading {
if (files == 0) return 'No changes';
final stat = changeStat(additions, deletions);
return '${files == 1 ? '1 file' : '$files files'} changed'
'${stat.isEmpty ? '' : ' $stat'}';
}
/// True when files or patches were left out by the size limits.
bool get partial {
final capture = this.capture;
return capture != null && (!capture.complete || capture.omitted > 0);
}
}
String _text(Object? value) => '${value ?? ''}'.trim();
int _count(Object? value) => value is num && value > 0 ? value.toInt() : 0;
@@ -2,15 +2,15 @@ import '../../../core/api_gateway.dart';
import 'chat_transcript.dart';
/// Entries a chat's model showed the operator through the Pipelines tools
/// (`show_file`, `show_image`, `show_html`, `notify`).
/// (`show_file`, `show_image`, `show_html`, `show_diff`, `notify`).
///
/// The server keeps them per chat, outside the harness transcript: the
/// `chat_subscribe` reply carries the retained list (oldest first) and a
/// pushed `chat_shown` frame carries each new or updated item. Items are keyed
/// by `id`; a later copy replaces the held one in place.
/// The four recorded kinds.
const chatShownKinds = {'file', 'image', 'html', 'notify'};
/// The recorded kinds.
const chatShownKinds = {'file', 'image', 'html', 'diff', 'notify'};
/// The transcript row kind an item is drawn as.
const String chatShownRowKind = 'shown';
@@ -52,7 +52,7 @@ List<JsonMap> mergeChatShownItems(
/// `pipelines/show_file`.
final RegExp _pipelinesTool = RegExp(
r'^(?:mcp__pipelines__|pipelines_|pipelines/)'
r'(?:show_file|show_image|show_html|notify)$',
r'(?:show_file|show_image|show_html|show_diff|notify)$',
);
/// Whether [part] is a call of a Pipelines tool whose result the transcript
@@ -3,6 +3,7 @@ import 'package:flutter/widgets.dart';
import '../../../../../core/api_gateway.dart';
import '../../../../artifacts/ui/artifact_html_view.dart';
import '../../../files/files_viewer.dart';
import 'chat_shown_diff_card.dart';
import 'chat_shown_file_card.dart';
import 'chat_shown_html_card.dart';
import 'chat_shown_link_image.dart';
@@ -35,6 +36,7 @@ class ChatShownCard extends StatelessWidget {
return switch ('${item['kind']}') {
'notify' => ChatShownNotifyRow(item: item),
'html' => ChatShownHtmlCard(item: item, htmlBuilder: htmlBuilder),
'diff' => ChatShownDiffCard(item: item),
'image' when path.isEmpty => ChatShownLinkImage(
item: item,
openExternal: viewer.openExternal,
@@ -0,0 +1,115 @@
import 'package:flutter/material.dart';
import '../../../../../core/api_gateway.dart';
import '../../../../changes/changes.dart';
import '../../../domain/chat_shown_diff.dart';
import 'chat_shown_surface.dart';
/// How many changed files the card lists before "Show all".
const chatShownDiffPreviewFiles = 8;
/// A Git comparison the model showed through `show_diff`: what was compared,
/// the totals, an honest note when the size limits left something out, and
/// one row per changed file that opens the app's file diff viewer, stepping
/// through every file of the diff. A diff the server no longer retains says so.
class ChatShownDiffCard extends StatefulWidget {
const ChatShownDiffCard({super.key, required this.item});
final JsonMap item;
@override
State<ChatShownDiffCard> createState() => _ChatShownDiffCardState();
}
class _ChatShownDiffCardState extends State<ChatShownDiffCard> {
bool _all = false;
@override
Widget build(BuildContext context) {
final diff = ChatShownDiff.of(widget.item);
if (diff == null) return const SizedBox.shrink();
final title = chatShownTitle(widget.item, 'Diff');
final secondary = chatShownSecondary(context);
final noteStyle = Theme.of(
context,
).textTheme.bodySmall?.copyWith(color: secondary);
final capture = diff.capture;
final files = capture?.files ?? const <FileChange>[];
final shown = _all || files.length <= chatShownDiffPreviewFiles
? files
: files.take(chatShownDiffPreviewFiles).toList();
return ChatShownSurface(
label: 'Shown diff $title',
maxWidth: 720,
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
Padding(
padding: const EdgeInsetsDirectional.fromSTEB(12, 8, 12, 4),
child: ChatShownHeading(
title: title,
subtitle: diff.comparison,
leading: Icon(Icons.difference_outlined, color: secondary),
),
),
Padding(
padding: const EdgeInsetsDirectional.fromSTEB(12, 0, 12, 8),
child: ChangeStatText(
diff.heading,
key: const Key('chat-shown-diff-heading'),
style: const TextStyle(fontWeight: FontWeight.w600),
),
),
if (capture == null)
Padding(
padding: const EdgeInsetsDirectional.fromSTEB(12, 0, 12, 12),
child: Text('This diff is no longer retained', style: noteStyle),
)
else ...[
if (diff.partial)
Padding(
key: const Key('chat-shown-diff-partial'),
padding: const EdgeInsetsDirectional.fromSTEB(12, 0, 12, 8),
child: Text(
capture.diagnostic.isEmpty
? 'Part of this diff was left out by the size limit.'
: 'Partial diff: ${capture.diagnostic}',
style: noteStyle,
),
),
for (final file in shown)
ChangeFileRow(
key: ValueKey<String>('chat-shown-diff-file-${file.path}'),
file: file,
onOpen: (file) =>
showFileDiffViewer(context, file, files: files),
),
if (shown.length < files.length)
Align(
alignment: AlignmentDirectional.centerStart,
child: Padding(
padding: const EdgeInsetsDirectional.fromSTEB(4, 0, 4, 4),
child: TextButton(
key: const Key('chat-shown-diff-all'),
onPressed: () => setState(() => _all = true),
child: Text('Show all ${files.length} files'),
),
),
),
if (capture.omitted > 0)
Padding(
padding: const EdgeInsetsDirectional.fromSTEB(12, 0, 12, 12),
child: Text(
'${capture.omitted} more '
'${capture.omitted == 1 ? 'file is' : 'files are'} '
'not listed.',
style: noteStyle,
),
),
],
],
),
);
}
}
+13 -2
View File
@@ -1,6 +1,6 @@
# Chat: Pipelines tools (show file / image / HTML, notify phone)
# Chat: Pipelines tools (show file / image / HTML / diff, notify phone)
A chat's model can call four tools that act on Pipelines, not on the harness
A chat's model can call five tools that act on Pipelines, not on the harness
or the workspace. The tools come from an MCP server that runs inside
`pipelines-server`. Each call adds an entry to the chat transcript, and the
entry is persisted.
@@ -10,6 +10,7 @@ entry is persisted.
| `show_file` | `path`, `title?` | Shows an existing file inside the operator's home. The path can be absolute, `~/…`, or relative to the chat's directory. Images render inline; other files render as a preview card. |
| `show_image` | `url_or_path`, `title?`, `alt?` | Shows a home image file (it must be `image/*`) or an `https://` URL. |
| `show_html` | `html`, `title?`, `height_hint?` | Renders model-authored HTML or SVG inline in a sandbox, with an **Open** button for full screen. |
| `show_diff` | `path?`, `base?`, `committed_only?`, `title?` | Runs Git in a repository inside the operator's home (default: the chat's directory) and shows a diff card: every changed file with its +/- counts, each opening the app's file diff viewer. Without `base`: uncommitted work (staged, unstaged, untracked) against HEAD. With `base` (e.g. `main`): everything since the merge base with it, which is what a pull request would contain, plus uncommitted work unless `committed_only`. |
| `notify` | `title`, `message`, `priority?` | Sends a phone notification through the existing ntfy "system" destination. Tapping it opens `pipelines://chat/<id>`. |
Each tool returns one short text line to the model. A refusal comes back as
@@ -58,6 +59,16 @@ Each tool returns one short text line to the model. A refusal comes back as
## Limits
- `show_diff` lists at most **300 files** (the rest are counted as omitted).
A patch over **256 KiB**, or past **1 MiB** in total, keeps its row with a
no-patch reason, and the card says the diff is partial. Binary files are
listed without a patch. `base` must be a plain revision name (no leading
`-`, no `..`, no whitespace); Git runs without pager, external diff or text
conversion, with a 30 s timeout. Renames show as a deletion plus an addition.
- Diff patches count against the same **2 MiB per chat** budget as HTML
bodies; an older diff past it keeps its summary and says it is no longer
retained.
- `show_html` documents are refused, not truncated, above **512 KiB**. The
model is told the size and the limit.
- At most **100 items are retained per chat**. HTML bodies are kept only for the
@@ -0,0 +1,147 @@
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/changes/changes.dart';
import 'package:pipelines_app/features/chat/domain/chat_shown_items.dart';
import 'package:pipelines_app/features/chat/ui/transcript/shown/chat_shown_card.dart';
JsonMap _file(String path, String kind, String patch) => {
'path': path,
'kind': kind,
'patch': patch,
};
JsonMap _item({
List<JsonMap>? files,
String status = 'complete',
int omitted = 0,
bool expired = false,
String base = 'main',
}) {
final list =
files ??
[
_file(
'app/lib/a.dart',
'modified',
'--- a/app/lib/a.dart\n+++ b/app/lib/a.dart\n@@ -1,2 +1,2 @@\n one\n-two\n+TWO\n',
),
_file('docs/new.md', 'added', '@@ -0,0 +1,2 @@\n+# New\n+text\n'),
];
return {
'id': 'd1',
'kind': 'diff',
'created_at': 1,
'title': 'PR preview',
'expired': expired,
'diff': {
'repo': '/home/op/repos/pipelines',
'base': base,
'base_commit': 'abc123def456',
'head': 'feature',
'files': list.length + omitted,
'additions': 3,
'deletions': 1,
if (!expired)
'changes': {
'status': status,
'files': list,
'omitted': omitted,
'skipped': 0,
if (status != 'complete')
'diagnostic': 'some patches were left out by the size limit.',
},
},
};
}
Future<void> _pump(WidgetTester tester, JsonMap item) async {
await tester.pumpWidget(
MaterialApp(
home: Scaffold(
body: SingleChildScrollView(
child: ChatShownCard(
row: {'kind': chatShownRowKind, 'item': item},
endpoint: 'ws://127.0.0.1:1/connect',
),
),
),
),
);
await tester.pumpAndSettle();
}
void main() {
test('diff items are a recorded kind and show_diff calls are hidden', () {
expect(chatShownKinds, contains('diff'));
expect(
chatPipelinesToolRepresented({
'type': 'tool',
'name': 'mcp__pipelines__show_diff',
'state': {'status': 'completed'},
}),
isTrue,
);
});
testWidgets('a diff card lists its files and opens the diff viewer', (
tester,
) async {
await _pump(tester, _item());
expect(find.text('PR preview'), findsOneWidget);
expect(
find.text('pipelines · feature vs main · with uncommitted work'),
findsOneWidget,
);
expect(find.text('2 files changed +3 -1'), findsOneWidget);
expect(find.text('app/lib/a.dart'), findsOneWidget);
expect(find.text('docs/new.md'), findsOneWidget);
expect(find.byKey(const Key('chat-shown-diff-partial')), findsNothing);
await tester.tap(find.text('app/lib/a.dart'));
await tester.pumpAndSettle();
expect(find.byType(FileDiffPage), findsOneWidget);
expect(find.textContaining('TWO', findRichText: true), findsWidgets);
});
testWidgets('a long diff lists the first files until Show all', (
tester,
) async {
final files = [
for (var i = 0; i < 12; i++)
_file('f$i.txt', 'added', '@@ -0,0 +1 @@\n+x\n'),
];
await _pump(tester, _item(files: files));
expect(find.text('f7.txt'), findsOneWidget);
expect(find.text('f8.txt'), findsNothing);
await tester.ensureVisible(find.byKey(const Key('chat-shown-diff-all')));
await tester.tap(find.byKey(const Key('chat-shown-diff-all')));
await tester.pumpAndSettle();
expect(find.text('f11.txt'), findsOneWidget);
expect(find.byKey(const Key('chat-shown-diff-all')), findsNothing);
});
testWidgets('a partial diff says what was left out', (tester) async {
await _pump(tester, _item(status: 'partial', omitted: 3));
expect(find.byKey(const Key('chat-shown-diff-partial')), findsOneWidget);
expect(find.text('3 more files are not listed.'), findsOneWidget);
expect(find.text('5 files changed +3 -1'), findsOneWidget);
});
testWidgets('an expired diff keeps its summary and says so', (tester) async {
await _pump(tester, _item(expired: true));
expect(find.text('2 files changed +3 -1'), findsOneWidget);
expect(find.text('This diff is no longer retained'), findsOneWidget);
expect(find.byType(ChangeFileRow), findsNothing);
});
testWidgets('without a base it describes the uncommitted changes', (
tester,
) async {
await _pump(tester, _item(base: ''));
expect(
find.text('pipelines · feature · uncommitted changes'),
findsOneWidget,
);
});
}
+60
View File
@@ -68,5 +68,65 @@ JsonMap chatShownFixture(Object? sessionId) => {
'priority': 'default',
'delivered': true,
},
{
'id': 'shown-diff',
'kind': 'diff',
'created_at': _at(19, 50),
'title': 'Pull request preview',
'diff_bytes': 612,
'diff': {
'repo': '/srv/probe/pipelines',
'base': 'main',
'base_commit': '79e51834a1b2',
'head': 'show-diff-tool',
'files': 3,
'additions': 7,
'deletions': 2,
'changes': {
'status': 'complete',
'skipped': 0,
'files': [
{
'path': 'internal/chattools/tools.go',
'kind': 'modified',
'patch':
'diff --git a/internal/chattools/tools.go b/internal/chattools/tools.go\n'
'--- a/internal/chattools/tools.go\n'
'+++ b/internal/chattools/tools.go\n'
'@@ -6,7 +6,8 @@ const (\n'
' \tToolShowFile = "show_file"\n'
' \tToolShowImage = "show_image"\n'
'-\tToolShowHTML = "show_html"\n'
'+\tToolShowHTML = "show_html"\n'
'+\tToolShowDiff = "show_diff"\n'
' \tToolNotify = "notify"\n'
' )\n',
},
{
'path': 'internal/server/chat_tools_diff.go',
'kind': 'added',
'patch':
'--- /dev/null\n'
'+++ b/internal/server/chat_tools_diff.go\n'
'@@ -0,0 +1,5 @@\n'
'+package server\n'
'+\n'
'+// runShowDiff compares a repository inside the operator\'s home\n'
'+// and records the per-file patches as one diff item.\n'
'+const showDiffMaxFiles = 300\n',
},
{
'path': 'docs/old-notes.md',
'kind': 'deleted',
'patch':
'--- a/docs/old-notes.md\n'
'+++ /dev/null\n'
'@@ -1,1 +0,0 @@\n'
'-Superseded notes.\n',
},
],
},
},
},
],
};