Merge branch 'worktree-agent-aae8756320b8309f6'

# Conflicts:
#	app/lib/features/chat/conversation/chat_thread_view.dart
#	app/tool/perf/perf_fixture.dart
#	internal/protocol/message.go
#	internal/server/chat_hub.go
This commit is contained in:
2026-11-09 16:56:55 +00:00
54 changed files with 4192 additions and 22 deletions
@@ -6,6 +6,7 @@ import '../../../core/api_gateway.dart';
import '../data/chat_repository.dart';
import '../domain/chat_account_usage.dart';
import '../domain/chat_sessions.dart';
import '../domain/chat_shown_items.dart';
import '../domain/chat_transcript.dart';
import '../domain/chat_turn_diffs.dart';
import 'chat_server_queue.dart';
@@ -73,6 +74,7 @@ class ChatThreadController extends ChangeNotifier {
void Function(JsonMap queue)? onQueue;
List<JsonMap> _messages = const [];
List<JsonMap> _shown = const [];
bool _running = false;
bool _loaded = false;
bool _loading = false;
@@ -116,6 +118,10 @@ class ChatThreadController extends ChangeNotifier {
List<JsonMap> get messages => _messages;
/// What the model showed through the Pipelines tools ([chatShownItemsOf]),
/// as the server retains it, oldest first.
List<JsonMap> get shown => _shown;
/// The prompts the server still holds for this session, in delivery order.
List<JsonMap> get queuedPrompts => _queue.prompts;
@@ -312,6 +318,7 @@ class ChatThreadController extends ChangeNotifier {
_subscribed = true;
_subscriptionError = null;
_applyQueue(reply['chat_queue']);
_applyShown(reply['chat_shown'], replace: true);
} catch (error) {
// History stays usable, but the UI must report that live updates failed.
if (_disposed) return;
@@ -340,8 +347,20 @@ class ChatThreadController extends ChangeNotifier {
_notify();
}
/// Adopts the subscribe reply's retained list, or one pushed item.
void _applyShown(Object? body, {bool replace = false}) {
final items = chatShownItemsOf(body, sessionId);
if (items == null) return;
_shown = mergeChatShownItems(_shown, items, replace: replace);
_notify();
}
void _onFrame(JsonMap envelope) {
if (_disposed) return;
if (envelope['type'] == 'chat_shown') {
_applyShown(envelope['chat_shown']);
return;
}
if (envelope['type'] == 'chat_queue') {
_applyQueue(envelope['chat_queue']);
return;
@@ -14,6 +14,9 @@ import '../domain/chat_activity_detail.dart';
import '../domain/chat_notice.dart';
import '../domain/chat_attachment_picker.dart';
import '../domain/chat_colors.dart';
import '../../../core/transport/pipelines_client.dart'
show configuredGatewayEndpoint;
import '../domain/chat_shown_items.dart';
import '../domain/chat_transcript.dart';
import '../domain/chat_turn_diffs.dart';
import '../ui/sessions/chat_adaptive.dart';
@@ -24,6 +27,7 @@ import '../ui/transcript/chat_markdown_view.dart';
import '../ui/transcript/chat_message_view.dart';
import '../ui/transcript/chat_transcript_selection.dart';
import '../ui/transcript/chat_injected_rows.dart';
import '../ui/transcript/shown/chat_shown_card.dart';
import '../ui/transcript/chat_task_notices_group.dart';
import '../ui/transcript/chat_turn_diff_chip.dart';
import '../../artifacts/actions/artifact_file_bridge.dart';
@@ -998,20 +1002,26 @@ class _ChatThreadViewState extends State<ChatThreadView> {
final allRows = attachChatTurnDiffs(
groupSettledQuestions(
groupSettledPermissions(
transcriptRows(
messages,
trailing: cards,
running:
_controller.running &&
!_reconnecting &&
!_staleTranscript &&
!cards.any(chatCardAwaitingOperator),
awaitingResponse:
_controller.awaitingResponse &&
!_reconnecting &&
!_staleTranscript &&
!cards.any(chatCardAwaitingOperator),
liveMessageId: _controller.liveAssistantMessageId,
withChatShownItems(
transcriptRows(
messages,
trailing: cards,
running:
_controller.running &&
!_reconnecting &&
!_staleTranscript &&
!cards.any(chatCardAwaitingOperator),
awaitingResponse:
_controller.awaitingResponse &&
!_reconnecting &&
!_staleTranscript &&
!cards.any(chatCardAwaitingOperator),
liveMessageId: _controller.liveAssistantMessageId,
),
// Placed only against a loaded transcript, so an entry never
// leads an empty one and then jumps down when history arrives.
_controller.loaded ? _controller.shown : const [],
hasMore: _controller.hasMore,
),
),
),
@@ -1482,6 +1492,12 @@ class _ChatThreadViewState extends State<ChatThreadView> {
runId: '${row['run_id']}',
);
}
if (kind == chatShownRowKind) {
return ChatShownCard(
row: row,
endpoint: configuredGatewayEndpoint(widget.gateway),
);
}
if (kind == 'task_notices') return ChatTaskNoticesGroup(row: row);
if (kind == 'questions') return ChatQuestionsRow(row: row);
if (kind == 'permission' || kind == 'question') {
@@ -0,0 +1,157 @@
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`).
///
/// 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 transcript row kind an item is drawn as.
const String chatShownRowKind = 'shown';
/// The items of a `chat_shown` body for [sessionId], or null when the body is
/// absent, malformed or for another chat. Items of unknown kind or without an
/// id are dropped rather than drawn as something they are not.
List<JsonMap>? chatShownItemsOf(Object? body, String sessionId) {
if (body is! Map || '${body['session_id'] ?? ''}' != sessionId) return null;
final items = body['items'];
if (items is! List) return const [];
return [
for (final item in items.whereType<Map>())
if ('${item['id'] ?? ''}'.isNotEmpty &&
chatShownKinds.contains(item['kind']))
Map<String, dynamic>.from(item),
];
}
/// [held] with [incoming] merged by id: a known item is replaced where it is,
/// a new one is appended. [replace] adopts [incoming] as the whole list (the
/// subscribe reply is the server's complete retained set).
List<JsonMap> mergeChatShownItems(
List<JsonMap> held,
List<JsonMap> incoming, {
bool replace = false,
}) {
if (replace) return List<JsonMap>.unmodifiable(incoming);
final byId = {for (final item in incoming) '${item['id']}': item};
final merged = [
for (final item in held) byId.remove('${item['id']}') ?? item,
...byId.values,
];
return List<JsonMap>.unmodifiable(merged);
}
/// The tool names a harness reports for the Pipelines tools: Claude Code
/// `mcp__pipelines__show_file`, OpenCode `pipelines_show_file`, Codex
/// `pipelines/show_file`.
final RegExp _pipelinesTool = RegExp(
r'^(?:mcp__pipelines__|pipelines_|pipelines/)'
r'(?:show_file|show_image|show_html|notify)$',
);
/// Whether [part] is a call of a Pipelines tool whose result the transcript
/// draws as its own entry. A failed call stays a normal tool row: its error is
/// the only record of what went wrong.
bool chatPipelinesToolRepresented(JsonMap part) {
if ('${part['type'] ?? ''}' != 'tool') return false;
if (!_pipelinesTool.hasMatch('${part['name'] ?? ''}'.trim())) return false;
final state = part['state'];
return !(state is Map && '${state['status'] ?? ''}' == 'error');
}
int? _createdAt(JsonMap value) => chatMessageCreatedAt(value);
/// A transcript row's recorded time, or null for a row without one.
int? _rowTime(JsonMap row) {
final own = _createdAt(row);
if (own != null) return own;
final message = row['message'];
return message is Map ? _createdAt(Map<String, dynamic>.from(message)) : null;
}
/// [rows] (from [transcriptRows]) with the Pipelines tool calls removed from
/// answer turns and each shown item placed by its time.
///
/// An item goes before the first timed row recorded after it, else after the
/// last timed row (so it never follows the pending cards or the response
/// shell that come after the transcript). While older history pages remain
/// ([hasMore]), an item older than the oldest loaded row stays out until that
/// page loads, so it is never drawn above messages that precede it.
List<JsonMap> withChatShownItems(
List<JsonMap> rows,
List<JsonMap> items, {
required bool hasMore,
}) {
final out = <JsonMap>[];
for (final row in rows) {
final parts = row['parts'];
if (row['kind'] != 'assistant' || parts is! List) {
out.add(row);
continue;
}
final kept = [
for (final part in parts.whereType<Map>())
if (!chatPipelinesToolRepresented(Map<String, dynamic>.from(part)))
part,
];
if (kept.length == parts.length) {
out.add(row);
} else if (kept.isNotEmpty ||
row['streaming'] == true ||
row['activityRecords'] != null) {
out.add({...row, 'parts': kept});
}
}
if (items.isEmpty) return out;
final timed = [
for (final item in items)
if (_createdAt(item) != null) item,
]..sort((a, b) => _createdAt(a)!.compareTo(_createdAt(b)!));
int? oldest;
var lastTimed = -1;
for (var index = 0; index < out.length; index++) {
final time = _rowTime(out[index]);
if (time == null) continue;
oldest ??= time;
lastTimed = index;
}
final result = <JsonMap>[];
var next = 0;
JsonMap rowOf(JsonMap item) => {
'kind': chatShownRowKind,
'key': 'chat-shown-${item['id']}',
'messageIds': ['shown:${item['id']}'],
'item': item,
};
if (hasMore) {
while (next < timed.length &&
(oldest == null || _createdAt(timed[next])! < oldest)) {
next++;
}
}
for (var index = 0; index < out.length; index++) {
final time = _rowTime(out[index]);
if (time != null) {
while (next < timed.length && _createdAt(timed[next])! < time) {
result.add(rowOf(timed[next++]));
}
}
result.add(out[index]);
if (index == lastTimed) {
while (next < timed.length) {
result.add(rowOf(timed[next++]));
}
}
}
// A transcript with no timed row yet: the items lead.
if (lastTimed < 0) {
return [for (; next < timed.length; next++) rowOf(timed[next]), ...result];
}
return result;
}
@@ -0,0 +1,50 @@
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_file_card.dart';
import 'chat_shown_html_card.dart';
import 'chat_shown_link_image.dart';
import 'chat_shown_notify_row.dart';
/// One transcript row of kind `shown` ([withChatShownItems]): what the model
/// showed through a Pipelines tool, drawn by its recorded kind. [endpoint] is
/// the configured endpoint of the chat's own machine, so a file is read from
/// the machine that recorded it.
class ChatShownCard extends StatelessWidget {
const ChatShownCard({
super.key,
required this.row,
required this.endpoint,
this.viewer = const FilesViewer(),
this.htmlBuilder = defaultArtifactHtml,
});
final JsonMap row;
final String endpoint;
final FilesViewer viewer;
final ArtifactHtmlBuilder htmlBuilder;
@override
Widget build(BuildContext context) {
final raw = row['item'];
if (raw is! Map) return const SizedBox.shrink();
final item = Map<String, dynamic>.from(raw);
final path = '${item['path'] ?? ''}'.trim();
return switch ('${item['kind']}') {
'notify' => ChatShownNotifyRow(item: item),
'html' => ChatShownHtmlCard(item: item, htmlBuilder: htmlBuilder),
'image' when path.isEmpty => ChatShownLinkImage(
item: item,
openExternal: viewer.openExternal,
),
'file' || 'image' => ChatShownFileCard(
item: item,
endpoint: endpoint,
viewer: viewer,
),
_ => const SizedBox.shrink(),
};
}
}
@@ -0,0 +1,161 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import '../../../../../core/api_gateway.dart';
import '../../../../artifacts/domain/artifact_kind.dart';
import '../../../../artifacts/ui/artifact_viewer_fetch.dart';
import '../../../data/directory_listing.dart';
import '../../../files/files_icons.dart';
import '../../../files/files_models.dart';
import '../../../files/files_preview.dart';
import '../../../files/files_thumbnail_image.dart';
import '../../../files/files_urls.dart';
import '../../../files/files_viewer.dart';
import 'chat_shown_file_lines.dart';
import 'chat_shown_surface.dart';
/// The file a `file` (or path `image`) entry names on the chat's machine.
DirectoryEntry chatShownEntry(JsonMap item) {
final path = '${item['path'] ?? ''}';
var name = '${item['name'] ?? ''}'.trim();
if (name.isEmpty) {
name = path.split('/').lastWhere((s) => s.isNotEmpty, orElse: () => path);
}
final size = item['size'];
return DirectoryEntry(
name: name,
path: path,
isDir: false,
isGitRepo: false,
hidden: false,
size: size is num ? size.toInt() : null,
);
}
/// The largest logical height an inline shown image takes.
const double chatShownImageMaxHeight = 280;
/// A file the model showed: an image inline as a picture, any other file as a
/// card with its kind glyph, name and size, and the first lines of a text
/// document. Activating either opens the Files viewer (preview and download)
/// over the chat machine's `/files` endpoint ([endpoint]).
class ChatShownFileCard extends StatelessWidget {
const ChatShownFileCard({
super.key,
required this.item,
required this.endpoint,
this.viewer = const FilesViewer(),
});
final JsonMap item;
final String endpoint;
final FilesViewer viewer;
@override
Widget build(BuildContext context) {
final entry = chatShownEntry(item);
final urls = resolveFileUrls(endpoint, entry.path);
final image = isThumbnailFile(entry.name) && urls != null;
final kind = artifactKindLabel(
artifactKind(fileContentType(entry.name), entry.name),
);
final title = chatShownTitle(item, entry.name);
final subtitle = [
if (title != entry.name) entry.name,
kind,
fileSizeLabel(entry.size),
].join(' · ');
void open() => viewer.open(context, endpoint: endpoint, entry: entry);
final heading = Padding(
padding: const EdgeInsets.all(12),
child: ChatShownHeading(
title: title,
subtitle: subtitle,
leading: image
? null
: Icon(
fileIcon(entry),
size: 32,
color: chatShownSecondary(context),
),
),
);
final body = Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
if (image)
_ChatShownPicture(
view: urls.view,
name: entry.name,
fetch: viewer.fetch,
),
heading,
if (!image && urls != null)
ChatShownFileLines(
entry: entry,
view: urls.view,
fetch: viewer.fetch,
),
],
);
final cupertino = chatShownCupertino(context);
return ChatShownSurface(
label: image ? 'Shown image $title' : 'Shown file $title',
child: Semantics(
button: true,
onTap: open,
child: cupertino
? CupertinoButton(
padding: EdgeInsets.zero,
onPressed: open,
child: DefaultTextStyle.merge(
style: CupertinoTheme.of(context).textTheme.textStyle,
child: body,
),
)
: InkWell(onTap: open, child: body),
),
);
}
}
/// An image file's own bytes from the files endpoint, decoded at the width it
/// is drawn, with the image glyph while loading and when it fails.
class _ChatShownPicture extends StatelessWidget {
const _ChatShownPicture({
required this.view,
required this.name,
required this.fetch,
});
final Uri view;
final String name;
final ArtifactFetch fetch;
@override
Widget build(BuildContext context) {
final ratio = MediaQuery.devicePixelRatioOf(context).clamp(1, 3);
final ImageProvider source = kIsWeb
? NetworkImage(view.toString())
: FileThumbnailImage(view, fetch: fetch);
final glyph = SizedBox(
height: 96,
child: Center(
child: Icon(Icons.image_outlined, color: chatShownSecondary(context)),
),
);
return ConstrainedBox(
constraints: const BoxConstraints(maxHeight: chatShownImageMaxHeight),
child: Image(
image: ResizeImage.resizeIfNeeded((560 * ratio).round(), null, source),
fit: BoxFit.contain,
semanticLabel: name,
loadingBuilder: (_, child, progress) =>
progress == null ? child : glyph,
errorBuilder: (_, _, _) => glyph,
),
);
}
}
@@ -0,0 +1,105 @@
import 'dart:convert';
import 'package:flutter/material.dart';
import '../../../../artifacts/domain/artifact_kind.dart';
import '../../../../artifacts/ui/artifact_viewer_fetch.dart';
import '../../../data/directory_listing.dart';
import '../../../files/files_preview.dart';
import 'chat_shown_surface.dart';
/// Text documents up to this size preview their first lines inline; larger
/// ones (and documents of unknown size) show only their card.
const int chatShownLinesMaxBytes = 256 << 10;
/// How many leading lines the inline preview shows.
const int chatShownPreviewLines = 6;
/// Whether [entry] is a text document the card previews by its first lines:
/// plain text, markdown and tables (the formats the Files viewer reads as
/// text).
bool chatShownPreviewsLines(DirectoryEntry entry) {
final size = entry.size;
if (size == null || size <= 0 || size > chatShownLinesMaxBytes) return false;
return switch (filePreviewFormat(fileContentType(entry.name), entry.name)) {
ArtifactPreviewFormat.text ||
ArtifactPreviewFormat.markdown ||
ArtifactPreviewFormat.table => true,
_ => false,
};
}
/// The first [chatShownPreviewLines] lines of a decoded document.
String chatShownLeadingLines(List<int> bytes) {
final text = utf8.decode(bytes, allowMalformed: true);
final lines = const LineSplitter().convert(text);
return lines.take(chatShownPreviewLines).join('\n').trimRight();
}
/// The first lines of a small text document, fetched once over the same
/// scoped fetch the viewer uses. Nothing is drawn for a document that is not
/// previewable or whose fetch fails: the card still names and opens it.
class ChatShownFileLines extends StatefulWidget {
const ChatShownFileLines({
super.key,
required this.entry,
required this.view,
required this.fetch,
});
final DirectoryEntry entry;
final Uri view;
final ArtifactFetch fetch;
@override
State<ChatShownFileLines> createState() => _ChatShownFileLinesState();
}
class _ChatShownFileLinesState extends State<ChatShownFileLines> {
Future<String?>? _lines;
@override
void initState() {
super.initState();
if (chatShownPreviewsLines(widget.entry)) _lines = _load();
}
Future<String?> _load() async {
try {
final result = await widget.fetch(widget.view);
if (!result.ok) return null;
final text = chatShownLeadingLines(result.bytes);
return text.isEmpty ? null : text;
} catch (_) {
return null;
}
}
@override
Widget build(BuildContext context) {
final lines = _lines;
if (lines == null) return const SizedBox.shrink();
return FutureBuilder<String?>(
future: lines,
builder: (context, snapshot) {
final text = snapshot.data;
if (text == null) return const SizedBox.shrink();
final style = Theme.of(context).textTheme.bodySmall?.copyWith(
fontFamily: 'monospace',
color: chatShownSecondary(context),
);
return Padding(
key: const Key('chat-shown-file-lines'),
padding: const EdgeInsetsDirectional.fromSTEB(12, 0, 12, 12),
child: Text(
text,
style: style,
maxLines: chatShownPreviewLines,
overflow: TextOverflow.ellipsis,
softWrap: false,
),
);
},
);
}
}
@@ -0,0 +1,188 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../../../../../core/api_gateway.dart';
import '../../../../../ui/adaptive/host.dart';
import '../../../../artifacts/ui/artifact_fullscreen.dart';
import '../../../../artifacts/ui/artifact_html_view.dart';
import '../../../../artifacts/ui/artifact_viewer_scaffold.dart';
import '../../../files/files_models.dart';
import 'chat_shown_surface.dart';
/// The inline frame's height when the model gave no hint.
const double chatShownHtmlDefaultHeight = 320;
/// The inline frame's height: the model's hint held between 120 and 600.
double chatShownHtmlHeight(JsonMap item) {
final hint = item['height_hint'];
if (hint is! num || hint <= 0) return chatShownHtmlDefaultHeight;
return hint.toDouble().clamp(120, 600);
}
/// A view the model authored (HTML or SVG), drawn inline by the same inert
/// renderer as an HTML artifact preview: on the web an iframe whose sandbox
/// is only `allow-popups allow-popups-to-escape-sandbox` (no scripts, no
/// same origin, no forms, no navigation of the app); on Android and iOS a web
/// view with JavaScript off that refuses navigation. Open shows it full
/// screen. A body the server no longer retains says so instead.
class ChatShownHtmlCard extends StatelessWidget {
const ChatShownHtmlCard({
super.key,
required this.item,
this.htmlBuilder = defaultArtifactHtml,
});
final JsonMap item;
final ArtifactHtmlBuilder htmlBuilder;
@override
Widget build(BuildContext context) {
final title = chatShownTitle(item, 'View');
final html = '${item['html'] ?? ''}';
final expired = item['expired'] == true || html.isEmpty;
final bytes = item['html_bytes'];
final size = bytes is num ? fileSizeLabel(bytes.toInt()) : null;
final cupertino = chatShownCupertino(context);
final open = expired
? null
: () => Navigator.of(context, rootNavigator: true).push(
artifactFullscreenRoute(
cupertino: usesCupertinoHost(context),
builder: (_) => ChatShownHtmlPage(
title: title,
html: html,
htmlBuilder: htmlBuilder,
),
),
);
final action = open == null
? null
: cupertino
? CupertinoButton(
key: const Key('chat-shown-html-open'),
padding: const EdgeInsets.symmetric(horizontal: 8),
onPressed: open,
child: const Text('Open'),
)
: TextButton(
key: const Key('chat-shown-html-open'),
onPressed: open,
child: const Text('Open'),
);
final heading = Padding(
padding: const EdgeInsetsDirectional.fromSTEB(12, 8, 4, 8),
child: ChatShownHeading(
title: title,
subtitle: expired
? 'This view is no longer retained'
: ['View', ?size].join(' · '),
leading: Icon(
cupertino ? CupertinoIcons.chart_bar_square : Icons.web_asset,
color: chatShownSecondary(context),
),
trailing: action,
),
);
return ChatShownSurface(
label: 'Shown view $title',
maxWidth: 720,
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
heading,
if (!expired)
// Inset from the card's edge: a web platform view is not clipped
// by the card's rounded outline and would draw over it.
Padding(
padding: const EdgeInsetsDirectional.fromSTEB(8, 0, 8, 8),
child: SizedBox(
height: chatShownHtmlHeight(item),
child: MediaQuery.removePadding(
context: context,
removeTop: true,
removeBottom: true,
child: _SettledFrame(
builder: (context) => htmlBuilder(context, html),
),
),
),
),
],
),
);
}
}
/// Builds [builder] from the row's second frame on. The transcript's lazy
/// list can lay a row out and drop it within one frame; a platform view
/// (the web frame) laid out that way fails its post-frame position read, so
/// the frame is only created for a row that is still mounted a frame later.
class _SettledFrame extends StatefulWidget {
const _SettledFrame({required this.builder});
final WidgetBuilder builder;
@override
State<_SettledFrame> createState() => _SettledFrameState();
}
class _SettledFrameState extends State<_SettledFrame> {
bool _settled = false;
@override
void initState() {
super.initState();
WidgetsBinding.instance.addPostFrameCallback((_) {
if (mounted) setState(() => _settled = true);
});
}
@override
Widget build(BuildContext context) =>
_settled ? widget.builder(context) : const SizedBox.expand();
}
/// The full-screen view of a shown HTML entry: the platform's Close, the
/// title, and on the web the zoom actions the sandboxed frame needs.
class ChatShownHtmlPage extends StatefulWidget {
const ChatShownHtmlPage({
super.key,
required this.title,
required this.html,
this.htmlBuilder = defaultArtifactHtml,
});
final String title;
final String html;
final ArtifactHtmlBuilder htmlBuilder;
@override
State<ChatShownHtmlPage> createState() => _ChatShownHtmlPageState();
}
class _ChatShownHtmlPageState extends State<ChatShownHtmlPage> {
final ValueNotifier<double> _zoom = ValueNotifier<double>(1);
@override
void dispose() {
_zoom.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) => ValueListenableBuilder<double>(
valueListenable: _zoom,
builder: (context, _, _) => ArtifactViewerScaffold(
title: widget.title,
subtitle: null,
actions: artifactHtmlZoomButtons ? artifactHtmlZoomActions(_zoom) : [],
body: ArtifactFullscreenScope(
htmlZoom: _zoom,
child: Builder(
builder: (context) => widget.htmlBuilder(context, widget.html),
),
),
),
);
}
@@ -0,0 +1,100 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../../../../../core/api_gateway.dart';
import '../../../../artifacts/ui/artifact_external_open.dart';
import 'chat_shown_file_card.dart';
import 'chat_shown_surface.dart';
/// The https address of a web `image` entry, or null for any other scheme.
Uri? chatShownImageUrl(JsonMap item) {
final uri = Uri.tryParse('${item['url'] ?? ''}'.trim());
if (uri == null || uri.scheme != 'https' || uri.host.isEmpty) return null;
return uri;
}
/// A web image the model showed: the picture inline with its address under
/// it. The picture is fetched without credentials (the default network image
/// fetch; on the web that needs the host to allow cross-origin reads, and a
/// refused fetch shows the glyph and the link). Activating it opens the
/// address outside the app.
class ChatShownLinkImage extends StatelessWidget {
const ChatShownLinkImage({
super.key,
required this.item,
this.openExternal = openArtifactExternally,
});
final JsonMap item;
final ArtifactExternalOpen openExternal;
@override
Widget build(BuildContext context) {
final url = chatShownImageUrl(item);
final address = '${item['url'] ?? ''}'.trim();
final title = chatShownTitle(item, url?.host ?? 'Image');
final alt = '${item['alt'] ?? ''}'.trim();
final glyph = SizedBox(
height: 96,
child: Center(
child: Icon(
Icons.broken_image_outlined,
color: chatShownSecondary(context),
),
),
);
final picture = url == null
? glyph
: ConstrainedBox(
constraints: const BoxConstraints(
maxHeight: chatShownImageMaxHeight,
),
child: Image.network(
url.toString(),
fit: BoxFit.contain,
semanticLabel: alt.isEmpty ? title : alt,
loadingBuilder: (_, child, progress) =>
progress == null ? child : glyph,
errorBuilder: (_, _, _) => glyph,
),
);
final body = Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
picture,
Padding(
padding: const EdgeInsets.all(12),
child: ChatShownHeading(
title: title,
subtitle: url == null ? 'Not an https address: $address' : address,
),
),
],
);
void open() {
if (url != null) openExternal(url);
}
return ChatShownSurface(
label: 'Shown image $title',
child: url == null
? body
: Semantics(
button: true,
link: true,
onTap: open,
child: chatShownCupertino(context)
? CupertinoButton(
padding: EdgeInsets.zero,
onPressed: open,
child: DefaultTextStyle.merge(
style: CupertinoTheme.of(context).textTheme.textStyle,
child: body,
),
)
: InkWell(onTap: open, child: body),
),
);
}
}
@@ -0,0 +1,84 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../../../../../core/api_gateway.dart';
import 'chat_shown_surface.dart';
/// What a `notify` entry says: the phone notification was accepted for
/// delivery, or why it was not sent.
String chatShownNotifyText(JsonMap item) {
final title = chatShownTitle(item, 'notification');
if (item['delivered'] == true) return 'Notified your phone: $title';
final detail = '${item['detail'] ?? ''}'.trim();
return detail.isEmpty
? 'Phone notification not sent: $title'
: 'Phone notification not sent: $title — $detail';
}
/// One secondary line in the agent's column for a `notify` entry, with the
/// notification's message under it.
class ChatShownNotifyRow extends StatelessWidget {
const ChatShownNotifyRow({super.key, required this.item});
final JsonMap item;
@override
Widget build(BuildContext context) {
final cupertino = chatShownCupertino(context);
final delivered = item['delivered'] == true;
final secondary = chatShownSecondary(context);
final color = delivered
? secondary
: (cupertino
? CupertinoColors.systemRed.resolveFrom(context)
: Theme.of(context).colorScheme.error);
final base = cupertino
? CupertinoTheme.of(context).textTheme.textStyle
: Theme.of(context).textTheme.bodySmall;
final text = chatShownNotifyText(item);
final message = '${item['message'] ?? ''}'.trim();
final icon = delivered
? (cupertino ? CupertinoIcons.bell : Icons.notifications_outlined)
: (cupertino
? CupertinoIcons.bell_slash
: Icons.notifications_off_outlined);
return Semantics(
container: true,
label: text,
value: message,
child: ExcludeSemantics(
child: Padding(
padding: const EdgeInsets.symmetric(vertical: 6),
child: Row(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Padding(
padding: const EdgeInsetsDirectional.only(end: 8),
child: Icon(
icon,
size: base?.fontSize == null ? 16 : base!.fontSize! * 1.2,
color: color,
),
),
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(text, style: base?.copyWith(color: color)),
if (message.isNotEmpty)
Text(
message,
maxLines: 2,
overflow: TextOverflow.ellipsis,
style: base?.copyWith(color: secondary),
),
],
),
),
],
),
),
),
);
}
}
@@ -0,0 +1,142 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../../../../../core/api_gateway.dart';
import '../../sessions/chat_adaptive.dart';
/// Whether the transcript draws Cupertino controls.
bool chatShownCupertino(BuildContext context) =>
chatControlsStyleOf(context) == ChatControlsStyle.cupertino;
/// The secondary text colour of either host.
Color chatShownSecondary(BuildContext context) => chatShownCupertino(context)
? CupertinoColors.secondaryLabel.resolveFrom(context)
: Theme.of(context).colorScheme.onSurfaceVariant;
/// The item's title, else [fallback].
String chatShownTitle(JsonMap item, String fallback) {
final title = '${item['title'] ?? ''}'.trim();
return title.isEmpty ? fallback : title;
}
/// The outlined card a shown entry sits in, on the agent's side of the
/// transcript, at most [maxWidth] wide.
class ChatShownSurface extends StatelessWidget {
const ChatShownSurface({
super.key,
required this.label,
required this.child,
this.maxWidth = 560,
});
/// The entry's accessible name ("Shown file", "Shown view", ...).
final String label;
final Widget child;
final double maxWidth;
@override
Widget build(BuildContext context) {
final cupertino = chatShownCupertino(context);
const radius = BorderRadius.all(Radius.circular(12));
final card = cupertino
? DecoratedBox(
decoration: BoxDecoration(
color: CupertinoColors.secondarySystemGroupedBackground
.resolveFrom(context),
border: Border.all(
color: CupertinoColors.separator.resolveFrom(context),
),
borderRadius: radius,
),
child: ClipRRect(borderRadius: radius, child: child),
)
: Card.outlined(
margin: EdgeInsets.zero,
clipBehavior: Clip.antiAlias,
child: child,
);
return Semantics(
container: true,
explicitChildNodes: true,
label: label,
child: Padding(
padding: const EdgeInsets.symmetric(vertical: 6),
child: Align(
alignment: AlignmentDirectional.centerStart,
child: ConstrainedBox(
constraints: BoxConstraints(maxWidth: maxWidth),
child: card,
),
),
),
);
}
}
/// A title line with an optional subtitle, leading glyph and trailing action.
class ChatShownHeading extends StatelessWidget {
const ChatShownHeading({
super.key,
required this.title,
this.subtitle,
this.leading,
this.trailing,
});
final String title;
final String? subtitle;
final Widget? leading;
final Widget? trailing;
@override
Widget build(BuildContext context) {
final cupertino = chatShownCupertino(context);
final titleStyle = cupertino
? CupertinoTheme.of(
context,
).textTheme.textStyle.copyWith(fontWeight: FontWeight.w600)
: Theme.of(context).textTheme.titleSmall;
// Cupertino has no caption role; the body style at a smaller size keeps
// the line secondary while still following text scaling.
final cupertinoBody = CupertinoTheme.of(context).textTheme.textStyle;
final subtitleStyle =
(cupertino
? cupertinoBody.copyWith(
fontSize: (cupertinoBody.fontSize ?? 17) * 0.8,
)
: Theme.of(context).textTheme.bodySmall)
?.copyWith(color: chatShownSecondary(context));
final sub = subtitle;
return Row(
children: [
if (leading != null)
Padding(
padding: const EdgeInsetsDirectional.only(end: 12),
child: leading,
),
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
mainAxisSize: MainAxisSize.min,
children: [
Text(
title,
style: titleStyle,
maxLines: 2,
overflow: TextOverflow.ellipsis,
),
if (sub != null && sub.isNotEmpty)
Text(
sub,
style: subtitleStyle,
maxLines: 1,
overflow: TextOverflow.ellipsis,
),
],
),
),
?trailing,
],
);
}
}
+199
View File
@@ -0,0 +1,199 @@
# Chat: Pipelines tools (show file / image / HTML, notify phone)
A chat's model can call four 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.
| Tool | Arguments | Effect |
| --- | --- | --- |
| `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. |
| `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
`isError` together with the reason.
## Security model
- **Endpoint.** The endpoint is `POST /mcp/chat/<token>` on the server's own
listener. It speaks JSON-RPC 2.0 over MCP streamable HTTP: `initialize`,
`ping`, `tools/list`, `tools/call`, and notifications (answered `202`).
- `GET` and other methods get `405`.
- The protocol version is negotiated: 2025-11-25, 2025-06-18, 2025-03-26 or
2024-11-05.
- Batches are refused, and request bodies are capped at 4 MiB.
- Requests that carry an `Origin` header (from a browser) get `403`, as do
requests from non-loopback peers. Unknown tokens get `404`.
- **Not exposed through the web.** `web/serve.mjs` and the peer relay forward
only an allowlist (`/connect`, `/files`, `/artifacts/`, `/chat-uploads`,
`/updates/`). Both new tests (`web/test/mcpRefused.test.mjs` and the
peerRelay test) confirm `/mcp…` never reaches the server, including for a
signed-in browser and `%6dcp`-encoded paths.
- **Tokens.** Each token is 256 random bits, stored in `chat_tool_tokens` with
the scope it serves:
- `session:<id>`: one chat. Claude Code and Codex use this, and the token
stays stable across restarts so detached hosts keep working.
- `pending:`: a Codex thread before its id is known. Calls are refused until
the token is bound.
- `instance:opencode`: the shared OpenCode service. See "OpenCode attribution"
below.
- **Paths.** Paths use the same containment as `/files`:
`expandHomePath`, then `resolveInsideHome` (resolves every symlink), then
"regular file only", then the `specialFilesystem` check. The item records
the real path, and the client loads it from the chat's own machine's
`/files` (or `/peers/<id>/files` for a peer).
- **Image URLs.** Only `https` URLs without credentials, at most 2048 chars.
The client fetches them with a plain network image, without cookies.
- **HTML views.** These use the same inert view as artifact HTML previews:
- On web, an iframe with `sandbox="allow-popups allow-popups-to-escape-sandbox"`
and `srcdoc`. There are no scripts, no same-origin access, no forms and no
top navigation.
- Links are rewritten first: `#anchors` scroll inside the frame,
http(s)/mailto links open a new tab, and every other link is made inert.
- On Android/iOS, a WebView with JavaScript disabled that refuses navigation.
- Interactivity is therefore limited to CSS (`:hover`, `<details>`) and SVG.
The tool description tells the model this.
## Limits
- `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
newest documents within **2 MiB per chat**; older documents keep their entry
but are marked `expired`, and the card says "This view is no longer retained".
- `notify` allows **5 per minute per chat** (a sliding window, held in memory).
Rate-limited calls record nothing.
- An undelivered notification is recorded with its reason, for example ntfy
not configured or switched off.
- `priority` is recorded, but ntfy always publishes at the default priority,
because `stage.PublishNtfy` has no priority parameter.
## Protocol and persistence
Items are stored in `chat_shown_items` (pipeline store). There are two ways
they reach clients:
- The `chat_subscribe` reply carries `chat_shown: {session_id, items}` with
every retained item, oldest first.
- A pushed `chat_shown` frame carries one new item.
The client interleaves items into the transcript by `created_at`. Items older
than the loaded history wait until that page loads. In a multi-machine chat,
the session id is rewritten by `ChatServerGateway`, and file URLs resolve
against the chat's own machine endpoint.
The generic tool rows for `mcp__pipelines__*` (Claude), `pipelines_*`
(OpenCode tool parts) and `pipelines/*` (Codex) are hidden; failed calls stay
visible. OpenCode V2 runs MCP tools from its code-mode `execute` script, and
that row stays visible because it can contain other code.
## Per-harness registration
`server.ConfigureChatTools(store, addr)` runs at startup, before any harness
starts, and installs `chattools.Registry`. The registry's base URL is the
loopback address of `-addr`; a wildcard address maps to 127.0.0.1, and a
non-loopback-only bind disables the tools with a log line.
- **Claude Code.** Started with `--mcp-config '{"mcpServers":{"pipelines":{"type":"http","url":…}}}'`
and `--allowedTools mcp__pipelines`. Both direct and hosted chats get the
session token.
- The config is added to the operator's own MCP servers; it does not replace
them.
- If a start fails with these flags, the chat logs the reason and retries
once without them (`session.toolsOff`).
- **Codex.** `thread/start` gets `config.mcp_servers.pipelines.url` with a
pending token, which is then bound to the returned thread id.
- A `thread/resume` (after "thread not found") registers the thread's
session token.
- If the App Server refuses the override, the thread starts or resumes
without it, and this is logged.
- Threads already loaded by the Codex desktop app before Pipelines touched
them have no tools.
- **OpenCode.** The spawned chat service gets
`mcp.pipelines = {type: "remote", url, enabled: true}` through
`OPENCODE_CONFIG_CONTENT`. This covers both `OpenChat` and the owned detached
`EnsureOwnedChatService`.
- The operator's chat overrides win.
- If the service does not start with the tools, it starts without them, and
this is logged.
- An operator-supplied endpoint (`-opencode-endpoint`) is not reconfigured,
so it has no tools.
- **Pi.** There is no Pi chat harness in this repository (chat backends are
opencode, claude and codex), so it is not supported.
**OpenCode attribution.** One OpenCode service serves every chat, and its MCP
requests carry no session (verified: OpenCode 2.0.32 sends only
`User-Agent: opencode/latest/2.0.32/cli` and `Mcp-Protocol-Version`).
A call on the instance token waits up to 3 s for exactly one chat whose
retained stream shows that call running. That means one of:
- a `pipelines_<tool>` part with identical arguments, or
- a running code-mode `execute` script containing `pipelines.<tool>(`. If
several such scripts are running, they are told apart by the argument
values.
When no chat matches, or several still do, the call is refused. It is never
guessed into a chat. Only chats Pipelines is observing can use the tools.
## Verification
- Go:
- `go test ./internal/server/ ./internal/chattools/ ./internal/pipeline/ ./internal/protocol/ ./internal/codex/ ./internal/codexhost/ ./internal/claudehost/`: all `ok` (server 72 s).
- `go test ./internal/claude/ ./internal/opencode/`: `ok` under `umask 022`.
Under this sandbox's `umask 077`, the existing tests
`TestServiceTokenIsPassedOnlyFromAPrivateFile` and
`TestStageDiscoveryRequiresPrivateRegistrationBeforeSessionWork` fail,
because both depend on 0644 file creation. They are unrelated to this
change.
- New Go tests:
- `chattools/mcp_test.go`: handshake, list, call, refusals, harness config.
- `server/chat_tools_test.go`: token isolation, pending binding, path
containment, image URLs, HTML limit and retention, notify rate limit,
instance and code-mode attribution.
- `server/chat_tools_http_test.go`: endpoint on the real listener,
`loopbackBase`.
- `claude|codex|opencode/pipelines_tools_test.go`: registration config and
the refuse-then-start-without fallback.
- `cd web && node --test test/`: `ℹ tests 18 … ℹ pass 18 ℹ fail 0`.
- Flutter:
- `tool/memwatch/full.sh test/features/chat`:
`memwatch: PASS: 1080 passed, 0 failed, 0 skipped; peak 2204 MB; 89s; exit 0 (test/features/chat)`.
- `tool/analyze.sh`: `0 errors, 8 warnings`. All 8 are the existing
`invalid_null_aware_operator` warnings in the unchanged
`integration_test/discovery_probe_test.dart`.
- Real end-to-end check, run on 2026-11-09:
- Setup: a scratch `pipelines-server` on `127.0.0.1:53834`, with
`HOME=/tmp/pl-e2e-tools/home`, a scratch database,
`PIPELINES_SHUTDOWN_SESSIONS=stop` and ntfy unset.
- OpenCode 2.0.32 (its default free model) was asked to `show_file
~/scratch/checker.png` and to `show_html` an SVG circle. Its `execute`
script returned "Shown in the operator's Pipelines chat: checker.png (217
bytes)" and "Shown … (137 bytes, sandboxed…)".
- `chat_subscribe` returned both items. The file item had
`path=/private/tmp/pl-e2e-tools/home/scratch/checker.png`,
`mime=image/png` and `size=217`. `/files` served that path with
`200 image/png 217`.
- `notify` was recorded as not delivered: "phone notifications (ntfy) are
not configured on this Pipelines server".
- A POST carrying an `Origin` header got `403`.
- The first OpenCode attempt was refused, and this is how code-mode
attribution was found to be necessary.
- Not run end to end:
- Claude Code under the isolated HOME answered "Not logged in", and
`~/.config/pipelines/claude-token` is empty.
- Codex has no app-server under the isolated HOME.
- Both registrations are covered only by unit tests against fake CLI
arguments and a fake App Server.
- Screenshots, real Chrome via `tool/capture` on the full-app fixture with
`?chats=1&timestamps=1&shown=1&files=1`, all in
`notes/images/chat-pipelines-tools/`:
- `cards-light-880.png`: image, markdown card with first lines, HTML
diagram with Open, and notify row.
- `cards-dark-880.png`
- `cards-cupertino-560.png`
- `html-open-light-880.png`: full-screen HTML with zoom.
- `image-open-dark-880.png`: the existing viewer with download.
- Mobile (Android/iOS WebView, native thumbnails) is unverified: no device run.
Binary file not shown.

After

Width:  |  Height:  |  Size: 78 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 111 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 114 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 99 KiB

@@ -0,0 +1,88 @@
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/chat/conversation/chat_thread_controller.dart';
import 'chat_thread_fixtures.dart';
void main() {
late FakeChatGateway gateway;
late ChatThreadController controller;
setUp(() {
gateway = FakeChatGateway();
gateway.history = (_) async => chatPage([]);
controller = ChatThreadController(gateway, 's');
});
tearDown(() {
controller.dispose();
gateway.close();
});
test('takes the retained list from the subscribe reply', () async {
gateway.subscribe = () async => {
'chat_shown': {
'session_id': 's',
'items': [
{'id': 'a', 'kind': 'file', 'created_at': 1, 'path': '/h/a.png'},
{'id': 'b', 'kind': 'notify', 'created_at': 2, 'title': 'Done'},
],
},
};
await controller.load();
expect(controller.shown.map((item) => item['id']), ['a', 'b']);
});
test('a pushed frame adds or replaces one item of this chat only', () async {
gateway.subscribe = () async => {
'chat_shown': {
'session_id': 's',
'items': [
{'id': 'a', 'kind': 'notify', 'created_at': 1, 'delivered': false},
],
},
};
await controller.load();
var notified = 0;
controller.transcriptChanges.addListener(() => notified++);
gateway.emitRaw({
'type': 'chat_shown',
'chat_shown': {
'session_id': 'other',
'items': [
{'id': 'x', 'kind': 'notify', 'created_at': 3},
],
},
});
gateway.emitRaw({
'type': 'chat_shown',
'chat_shown': {
'session_id': 's',
'items': [
{'id': 'a', 'kind': 'notify', 'created_at': 1, 'delivered': true},
{'id': 'c', 'kind': 'html', 'created_at': 4, 'html': '<p>x</p>'},
],
},
});
await pumpEventQueue();
expect(controller.shown.map((item) => item['id']), ['a', 'c']);
expect(controller.shown.first['delivered'], isTrue);
expect(notified, 1);
});
test('a resync re-subscribes and adopts the server list', () async {
var round = 0;
gateway.subscribe = () async => {
'chat_shown': {
'session_id': 's',
'items': [
{'id': 'r$round', 'kind': 'notify', 'created_at': 1},
],
},
};
gateway.onSubscribe = () => round++;
await controller.load();
expect(controller.shown.single['id'], 'r1');
await controller.resync();
expect(controller.shown.single['id'], 'r2');
});
}
@@ -0,0 +1,165 @@
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/core/api_gateway.dart';
import 'package:pipelines_app/features/chat/domain/chat_shown_items.dart';
import 'package:pipelines_app/features/chat/domain/chat_transcript.dart';
JsonMap _item(String id, int at, {String kind = 'notify'}) => {
'id': id,
'kind': kind,
'created_at': at,
'title': id,
};
JsonMap _message(String id, String role, int at, {List<JsonMap>? parts}) => {
'id': id,
'role': role,
'created_at': at,
'parts':
parts ??
[
{'type': 'text', 'text': id},
],
};
List<String> _shape(List<JsonMap> rows) => [
for (final row in rows)
row['kind'] == 'shown'
? 'shown:${(row['item'] as Map)['id']}'
: '${row['kind']}:${row['key']}',
];
void main() {
group('chatShownItemsOf', () {
test('reads only this session and known kinds with ids', () {
final body = {
'session_id': 's',
'items': [
_item('a', 1),
{'id': '', 'kind': 'file'},
{'id': 'x', 'kind': 'future'},
'junk',
],
};
expect(chatShownItemsOf(body, 's')!.map((i) => i['id']), ['a']);
expect(chatShownItemsOf(body, 'other'), isNull);
expect(chatShownItemsOf(null, 's'), isNull);
});
});
test('merge replaces by id in place and appends new items', () {
final held = [_item('a', 1), _item('b', 2)];
final updated = {..._item('a', 1), 'title': 'A2'};
final merged = mergeChatShownItems(held, [updated, _item('c', 3)]);
expect(merged.map((i) => i['id']), ['a', 'b', 'c']);
expect(merged.first['title'], 'A2');
expect(
mergeChatShownItems(held, [_item('z', 9)], replace: true).single['id'],
'z',
);
});
group('withChatShownItems', () {
final messages = [
_message('u1', 'user', 100),
_message('a1', 'assistant', 110),
_message('u2', 'user', 200),
_message('a2', 'assistant', 210),
];
test('interleaves items by time before trailing cards', () {
final rows = transcriptRows(
messages,
trailing: [
{'kind': 'permission', 'key': 'p'},
],
);
final out = withChatShownItems(rows, [
_item('late', 500),
_item('mid', 150),
], hasMore: false);
expect(_shape(out), [
'user:u1',
'assistant:a1',
'shown:mid',
'user:u2',
'assistant:a2',
'shown:late',
'permission:p',
]);
final shown = out.firstWhere((row) => row['kind'] == 'shown');
expect(shown['messageIds'], ['shown:mid']);
});
test('older items wait for their history page while more remains', () {
final rows = transcriptRows(messages);
final early = [_item('early', 50), _item('mid', 150)];
expect(
_shape(withChatShownItems(rows, early, hasMore: true)),
isNot(contains('shown:early')),
);
expect(
_shape(withChatShownItems(rows, early, hasMore: false)).first,
'shown:early',
);
});
test('items lead an empty transcript only when no history remains', () {
expect(_shape(withChatShownItems([], [_item('a', 1)], hasMore: false)), [
'shown:a',
]);
expect(withChatShownItems([], [_item('a', 1)], hasMore: true), isEmpty);
});
test('hides represented Pipelines tool calls, keeps others and errors', () {
JsonMap tool(String name, {String status = 'completed'}) => {
'type': 'tool',
'id': name,
'name': name,
'state': {'status': status},
};
final turn = _message(
'a',
'assistant',
10,
parts: [
{'type': 'text', 'text': 'Here it is'},
tool('mcp__pipelines__show_file'),
tool('pipelines_show_html'),
tool('pipelines/notify'),
tool('pipelines_show_image', status: 'error'),
tool('bash'),
tool('pipelines_other'),
],
);
final out = withChatShownItems(
transcriptRows([turn]),
[],
hasMore: false,
);
final names = [
for (final part in out.single['parts'] as List)
if (part['type'] == 'tool') part['name'],
];
expect(names, ['pipelines_show_image', 'bash', 'pipelines_other']);
});
test('a turn holding only a represented call is not drawn', () {
final turn = _message(
'a',
'assistant',
10,
parts: [
{
'type': 'tool',
'name': 'pipelines_notify',
'state': {'status': 'completed'},
},
],
);
final out = withChatShownItems(transcriptRows([turn]), [
_item('n', 20),
], hasMore: false);
expect(_shape(out), ['shown:n']);
});
});
}
@@ -0,0 +1,215 @@
import 'dart:convert';
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/artifacts/ui/artifact_fullscreen.dart';
import 'package:pipelines_app/features/artifacts/ui/artifact_viewer_fetch.dart';
import 'package:pipelines_app/features/artifacts/ui/artifact_viewer_page.dart';
import 'package:pipelines_app/features/chat/files/files_urls.dart';
import 'package:pipelines_app/features/chat/files/files_viewer.dart';
import 'package:pipelines_app/features/chat/ui/transcript/shown/chat_shown_card.dart';
import 'package:pipelines_app/features/chat/ui/transcript/shown/chat_shown_html_card.dart';
const _png =
'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
Widget _stubHtml(BuildContext context, String html) => Container(
key: const Key('stub-html'),
child: Text(
ArtifactFullscreenScope.maybeOf(context) == null
? 'inline $html'
: 'full $html',
),
);
void main() {
late FileUrlResolver original;
final fetched = <Uri>[];
final opened = <Uri>[];
setUp(() {
original = resolveFileUrls;
resolveFileUrls = (endpoint, path) => fileUrls(endpoint, path);
fetched.clear();
opened.clear();
});
tearDown(() => resolveFileUrls = original);
final viewer = FilesViewer(
fetch: (uri) async {
fetched.add(uri);
final path = uri.queryParameters['path'] ?? '';
return ArtifactFetchResult(
status: 200,
bytes: path.endsWith('.png')
? base64Decode(_png)
: utf8.encode('# Release notes\nline two\nline three\n'),
);
},
openExternal: (uri) async {
opened.add(uri);
return true;
},
);
Future<void> pump(WidgetTester tester, JsonMap item) async {
await tester.pumpWidget(
MaterialApp(
home: Scaffold(
body: SingleChildScrollView(
child: ChatShownCard(
row: {'kind': 'shown', 'item': item},
endpoint: 'ws://peer.example.test/peers/abc/connect',
viewer: viewer,
htmlBuilder: _stubHtml,
),
),
),
),
);
await tester.pumpAndSettle();
}
testWidgets('an image file draws inline and opens the files viewer', (
tester,
) async {
await pump(tester, {
'id': 'i',
'kind': 'file',
'path': '/home/demo/chart.png',
'name': 'chart.png',
'size': 2048,
'title': 'Latency chart',
});
expect(find.text('Latency chart'), findsOneWidget);
expect(find.text('chart.png · Image · 2.0 KiB'), findsOneWidget);
expect(find.bySemanticsLabel('chart.png'), findsOneWidget);
await tester.tap(find.text('Latency chart'));
await tester.pumpAndSettle();
expect(find.byType(ArtifactViewerPage), findsOneWidget);
expect(fetched.last.path, '/peers/abc/files');
expect(fetched.last.queryParameters['path'], '/home/demo/chart.png');
});
testWidgets('a document card shows icon, size and its first lines', (
tester,
) async {
await pump(tester, {
'id': 'd',
'kind': 'file',
'path': '/home/demo/NOTES.md',
'name': 'NOTES.md',
'size': 40,
});
expect(find.text('NOTES.md'), findsOneWidget);
expect(find.byIcon(Icons.description_outlined), findsOneWidget);
expect(find.byKey(const Key('chat-shown-file-lines')), findsOneWidget);
expect(find.textContaining('# Release notes'), findsOneWidget);
expect(fetched.single.queryParameters['path'], '/home/demo/NOTES.md');
await tester.tap(find.text('NOTES.md'));
await tester.pumpAndSettle();
expect(find.byType(ArtifactViewerPage), findsOneWidget);
});
testWidgets('a PDF card opens the host handler', (tester) async {
await pump(tester, {
'id': 'p',
'kind': 'file',
'path': '/home/demo/report.pdf',
'size': 100000,
});
expect(find.byIcon(Icons.picture_as_pdf_outlined), findsOneWidget);
expect(find.byKey(const Key('chat-shown-file-lines')), findsNothing);
await tester.tap(find.text('report.pdf'));
await tester.pumpAndSettle();
expect(opened.single.queryParameters['path'], '/home/demo/report.pdf');
});
testWidgets('a web image shows its address and opens it outside', (
tester,
) async {
await pump(tester, {
'id': 'w',
'kind': 'image',
'url': 'https://example.test/cat.png',
'alt': 'A cat',
});
expect(find.text('https://example.test/cat.png'), findsOneWidget);
await tester.tap(find.text('example.test'));
await tester.pumpAndSettle();
expect(opened.single.toString(), 'https://example.test/cat.png');
});
testWidgets('a non-https image address is never fetched or opened', (
tester,
) async {
await pump(tester, {
'id': 'w',
'kind': 'image',
'url': 'http://example.test/cat.png',
});
expect(find.byType(Image), findsNothing);
expect(find.textContaining('Not an https address'), findsOneWidget);
});
testWidgets('an HTML view renders inline at its hint and opens full screen', (
tester,
) async {
await pump(tester, {
'id': 'h',
'kind': 'html',
'title': 'Pipeline graph',
'html': '<svg></svg>',
'html_bytes': 11,
'height_hint': 2000,
});
expect(find.text('inline <svg></svg>'), findsOneWidget);
final box = tester.getSize(
find
.ancestor(
of: find.byKey(const Key('stub-html')),
matching: find.byType(SizedBox),
)
.first,
);
expect(box.height, 600);
await tester.tap(find.byKey(const Key('chat-shown-html-open')));
await tester.pumpAndSettle();
expect(find.byType(ChatShownHtmlPage), findsOneWidget);
expect(find.text('full <svg></svg>'), findsOneWidget);
});
testWidgets('an expired HTML view says so and offers no Open', (
tester,
) async {
await pump(tester, {'id': 'h', 'kind': 'html', 'expired': true});
expect(find.text('This view is no longer retained'), findsOneWidget);
expect(find.byKey(const Key('chat-shown-html-open')), findsNothing);
expect(find.byKey(const Key('stub-html')), findsNothing);
});
testWidgets('notify rows say whether the phone was notified', (tester) async {
await pump(tester, {
'id': 'n',
'kind': 'notify',
'title': 'Build done',
'message': 'All green',
'delivered': true,
});
expect(find.text('Notified your phone: Build done'), findsOneWidget);
expect(find.text('All green'), findsOneWidget);
await pump(tester, {
'id': 'n2',
'kind': 'notify',
'title': 'Build done',
'delivered': false,
'detail': 'notifications are not set up',
});
expect(
find.text(
'Phone notification not sent: Build done — notifications are not set up',
),
findsOneWidget,
);
});
}
+72
View File
@@ -0,0 +1,72 @@
// `?shown=1` (with `?chats=N&timestamps=1`, and `?files=1` so the files
// resolve to tool/capture/fixtures/files copied under capture-files/): the
// subscribe reply carries one of each Pipelines tool entry, after the last answer of the
// bench transcript's messages (perf-m0..19 at 09:00..09:19 UTC).
import 'package:pipelines_app/core/api_gateway.dart';
int _at(int minute, int second) =>
DateTime.utc(2026, 11, 5, 9, minute, second).millisecondsSinceEpoch;
const String _diagram = '''
<!doctype html><html><body style="margin:0;font:14px system-ui;background:#fff">
<svg viewBox="0 0 520 160" width="100%" height="150" role="img"
aria-label="Build, test and release stages">
<defs><marker id="a" markerWidth="8" markerHeight="8" refX="7" refY="4"
orient="auto"><path d="M0,0 L8,4 L0,8 z" fill="#555"/></marker></defs>
<g font-family="system-ui" font-size="14" text-anchor="middle">
<rect x="10" y="50" width="130" height="56" rx="10" fill="#e3f2fd" stroke="#1e88e5"/>
<text x="75" y="83">Build</text>
<rect x="195" y="50" width="130" height="56" rx="10" fill="#e8f5e9" stroke="#43a047"/>
<text x="260" y="83">Test</text>
<rect x="380" y="50" width="130" height="56" rx="10" fill="#fff3e0" stroke="#fb8c00"/>
<text x="445" y="83">Release</text>
<line x1="140" y1="78" x2="190" y2="78" stroke="#555" stroke-width="2" marker-end="url(#a)"/>
<line x1="325" y1="78" x2="375" y2="78" stroke="#555" stroke-width="2" marker-end="url(#a)"/>
</g></svg>
<details style="padding:0 12px"><summary>Stage timings</summary>
<p>Build 2m 10s · Test 4m 02s · Release 38s</p></details>
</body></html>''';
/// The retained entries the fixture's subscribe reply carries.
JsonMap chatShownFixture(Object? sessionId) => {
'session_id': sessionId,
'items': [
{
'id': 'shown-image',
'kind': 'file',
'created_at': _at(19, 10),
'title': 'Release design',
'path': '/srv/probe/release/design.png',
'name': 'design.png',
'size': 18432,
'mime': 'image/png',
},
{
'id': 'shown-doc',
'kind': 'file',
'created_at': _at(19, 20),
'path': '/srv/probe/release/release.md',
'name': 'release.md',
'size': 640,
'mime': 'text/markdown',
},
{
'id': 'shown-html',
'kind': 'html',
'created_at': _at(19, 30),
'title': 'Pipeline stages',
'html': _diagram,
'html_bytes': _diagram.length,
'height_hint': 220,
},
{
'id': 'shown-notify',
'kind': 'notify',
'created_at': _at(19, 40),
'title': 'Release ready',
'message': 'All three stages passed; the release is ready to publish.',
'priority': 'default',
'delivered': true,
},
],
};
+9 -1
View File
@@ -26,6 +26,7 @@ import 'chat_new_session_fixture.dart';
import 'chat_turn_diff_fixture.dart';
import 'chat_question_fixture.dart';
import 'chat_shell_fixture.dart';
import 'chat_shown_fixture.dart';
import 'chat_scroll_fixture.dart';
Map<String, String> _params = const {};
@@ -273,7 +274,14 @@ JsonMap? perfChatReply(JsonMap request) {
case 'chat_new_session':
return perfChatNewSessionReply(request, _chatRow);
case 'chat_subscribe':
return {'id': id, 'type': 'chat_subscribed'};
return {
'id': id,
'type': 'chat_subscribed',
if (_params['shown'] == '1')
'chat_shown': chatShownFixture(
(request['chat_subscribe'] as Map?)?['session_id'],
),
};
case 'chat_prompt':
// Accepted, as the server does; no reply follows, so a capture can
// watch the sent message itself.
+6
View File
@@ -70,6 +70,12 @@ func main() {
} else if seeded > 0 {
log.Printf("added %d example pipelines to the new database", seeded)
}
// Every chat harness Pipelines launches registers the Pipelines tools (show
// a file, an image or an HTML view in the chat, notify the phone) as an MCP
// server on this listener's loopback address (internal/chattools).
if err := server.ConfigureChatTools(store, *addr); err != nil {
log.Printf("chat tools unavailable: %v", err)
}
artifactsRoot := filepath.Join(filepath.Dir(*db), "artifacts")
// Each new run gets a bounded one-line title from the configured default
// harness; the summariser falls back to the prompt's first line, so title
+49
View File
@@ -0,0 +1,49 @@
package chattools
import (
"encoding/json"
"strings"
)
// ClaudeMCPConfig is the inline JSON Claude Code takes as --mcp-config.
func ClaudeMCPConfig(url string) string {
data, _ := json.Marshal(map[string]any{"mcpServers": map[string]any{
ServerName: map[string]any{"type": "http", "url": url},
}})
return string(data)
}
// ClaudeAllowedTools pre-approves every Pipelines tool, so a call never waits
// on a permission card: the tools only present content to the operator.
func ClaudeAllowedTools() string { return "mcp__" + ServerName }
// CodexConfig is the thread/start (and thread/resume) config override that
// registers the endpoint as a streamable HTTP MCP server for one thread.
func CodexConfig(url string) map[string]any {
return map[string]any{"mcp_servers": map[string]any{
ServerName: map[string]any{"url": url},
}}
}
// OpenCodeConfig is the OpenCode config fragment registering the endpoint as a
// remote MCP server.
func OpenCodeConfig(url string) map[string]any {
return map[string]any{"mcp": map[string]any{
ServerName: map[string]any{"type": "remote", "url": url, "enabled": true},
}}
}
// HarnessToolNames are the names one tool has in each harness's transcript.
func HarnessToolNames(tool string) []string {
return []string{"mcp__" + ServerName + "__" + tool, ServerName + "_" + tool, ServerName + "/" + tool}
}
// ToolFromHarnessName returns the Pipelines tool a harness tool name denotes.
func ToolFromHarnessName(name string) (string, bool) {
for _, prefix := range []string{"mcp__" + ServerName + "__", ServerName + "_", ServerName + "/"} {
if tool, ok := strings.CutPrefix(name, prefix); ok && IsTool(tool) {
return tool, true
}
}
return "", false
}
+172
View File
@@ -0,0 +1,172 @@
package chattools
import (
"context"
"encoding/json"
"errors"
"io"
"net"
"net/http"
"slices"
)
// MaxRequestBytes bounds one MCP request body: a full show_html document plus
// JSON escaping and the envelope.
const MaxRequestBytes = 4 << 20
// LatestProtocolVersion is the MCP revision this server implements. Older
// revisions a client asks for are accepted: the subset used here (initialize,
// tools/list, tools/call, ping over streamable HTTP with JSON responses) is the
// same in each.
const LatestProtocolVersion = "2025-06-18"
var protocolVersions = []string{"2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"}
// Result is one tool call's outcome: short text for the model.
type Result struct {
Text string
IsError bool
}
// Service executes tool calls for the chat an endpoint token serves.
type Service interface {
// Known reports whether token is an issued endpoint token.
Known(ctx context.Context, token string) bool
// Call runs one tool. arguments is the raw JSON object the model sent.
Call(ctx context.Context, token, tool string, arguments json.RawMessage) Result
}
// Handler serves the MCP streamable HTTP transport for one endpoint token.
type Handler struct {
Service Service
Version string
}
type rpcRequest struct {
JSONRPC string `json:"jsonrpc"`
ID json.RawMessage `json:"id,omitempty"`
Method string `json:"method"`
Params json.RawMessage `json:"params,omitempty"`
}
type rpcError struct {
Code int `json:"code"`
Message string `json:"message"`
}
type rpcResponse struct {
JSONRPC string `json:"jsonrpc"`
ID json.RawMessage `json:"id"`
Result any `json:"result,omitempty"`
Error *rpcError `json:"error,omitempty"`
}
// Loopback reports whether a request came over the loopback interface. The
// endpoint is for harness processes on this machine only.
func Loopback(r *http.Request) bool {
host, _, err := net.SplitHostPort(r.RemoteAddr)
if err != nil {
return false
}
ip := net.ParseIP(host)
return ip != nil && ip.IsLoopback()
}
// ServeHTTP answers one POSTed JSON-RPC message. A browser request (any Origin
// header) and a non-loopback peer are refused, an unknown token is 404, and
// GET (the optional server-to-client stream) is not offered.
func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, token string) {
if r.Header.Get("Origin") != "" || !Loopback(r) {
http.Error(w, "forbidden", http.StatusForbidden)
return
}
if h.Service == nil || !h.Service.Known(r.Context(), token) {
http.NotFound(w, r)
return
}
if r.Method != http.MethodPost {
w.Header().Set("Allow", http.MethodPost)
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, MaxRequestBytes))
if err != nil {
var tooLarge *http.MaxBytesError
if errors.As(err, &tooLarge) {
writeRPC(w, rpcResponse{JSONRPC: "2.0", ID: json.RawMessage("null"), Error: &rpcError{Code: -32600, Message: "request exceeds 4 MiB"}})
return
}
http.Error(w, "unreadable request", http.StatusBadRequest)
return
}
var request rpcRequest
if err := json.Unmarshal(body, &request); err != nil || request.JSONRPC != "2.0" || request.Method == "" {
writeRPC(w, rpcResponse{JSONRPC: "2.0", ID: json.RawMessage("null"), Error: &rpcError{Code: -32700, Message: "expected one JSON-RPC 2.0 request"}})
return
}
if len(request.ID) == 0 || string(request.ID) == "null" {
// A notification (notifications/initialized, cancellations) has no reply.
w.WriteHeader(http.StatusAccepted)
return
}
response := rpcResponse{JSONRPC: "2.0", ID: request.ID}
response.Result, response.Error = h.dispatch(r.Context(), token, request)
writeRPC(w, response)
}
func (h Handler) dispatch(ctx context.Context, token string, request rpcRequest) (any, *rpcError) {
switch request.Method {
case "initialize":
var params struct {
ProtocolVersion string `json:"protocolVersion"`
}
_ = json.Unmarshal(request.Params, &params)
version := LatestProtocolVersion
if slices.Contains(protocolVersions, params.ProtocolVersion) {
version = params.ProtocolVersion
}
return map[string]any{
"protocolVersion": version,
"capabilities": map[string]any{"tools": map[string]any{"listChanged": false}},
"serverInfo": map[string]any{"name": ServerName, "title": "Pipelines", "version": h.version()},
"instructions": Instructions,
}, nil
case "ping":
return map[string]any{}, nil
case "tools/list":
return map[string]any{"tools": definitions()}, nil
case "tools/call":
var params struct {
Name string `json:"name"`
Arguments json.RawMessage `json:"arguments"`
}
if err := json.Unmarshal(request.Params, &params); err != nil || params.Name == "" {
return nil, &rpcError{Code: -32602, Message: "tools/call needs a tool name"}
}
if !IsTool(params.Name) {
return nil, &rpcError{Code: -32602, Message: "unknown tool: " + params.Name}
}
if len(params.Arguments) == 0 || string(params.Arguments) == "null" {
params.Arguments = json.RawMessage("{}")
}
result := h.Service.Call(ctx, token, params.Name, params.Arguments)
return map[string]any{
"content": []map[string]any{{"type": "text", "text": result.Text}},
"isError": result.IsError,
}, nil
}
return nil, &rpcError{Code: -32601, Message: "method not found: " + request.Method}
}
func (h Handler) version() string {
if h.Version == "" {
return "dev"
}
return h.Version
}
func writeRPC(w http.ResponseWriter, response rpcResponse) {
w.Header().Set("Content-Type", "application/json")
w.Header().Set("Cache-Control", "no-store")
_ = json.NewEncoder(w).Encode(response)
}
+169
View File
@@ -0,0 +1,169 @@
package chattools
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
)
type fakeService struct {
known map[string]bool
calls []string
}
func (f *fakeService) Known(_ context.Context, token string) bool { return f.known[token] }
func (f *fakeService) Call(_ context.Context, token, tool string, arguments json.RawMessage) Result {
f.calls = append(f.calls, token+" "+tool+" "+string(arguments))
return Result{Text: "ok " + tool}
}
func post(t *testing.T, h Handler, token, body string, mutate func(*http.Request)) *httptest.ResponseRecorder {
t.Helper()
request := httptest.NewRequest(http.MethodPost, "/mcp/chat/"+token, strings.NewReader(body))
request.RemoteAddr = "127.0.0.1:50000"
request.Header.Set("Content-Type", "application/json")
request.Header.Set("Accept", "application/json, text/event-stream")
if mutate != nil {
mutate(request)
}
recorder := httptest.NewRecorder()
h.ServeHTTP(recorder, request, token)
return recorder
}
func decode(t *testing.T, recorder *httptest.ResponseRecorder) map[string]any {
t.Helper()
var out map[string]any
if err := json.Unmarshal(recorder.Body.Bytes(), &out); err != nil {
t.Fatalf("response %d %q: %v", recorder.Code, recorder.Body.String(), err)
}
return out
}
func TestHandshakeListAndCall(t *testing.T) {
service := &fakeService{known: map[string]bool{"tok": true}}
h := Handler{Service: service, Version: "1.2.3"}
init := decode(t, post(t, h, "tok", `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"x","version":"1"}}}`, nil))
result := init["result"].(map[string]any)
if result["protocolVersion"] != "2025-03-26" {
t.Fatalf("a supported requested version must be echoed: %v", result)
}
if result["serverInfo"].(map[string]any)["name"] != ServerName || result["capabilities"].(map[string]any)["tools"] == nil {
t.Fatalf("initialize result = %v", result)
}
unknown := decode(t, post(t, h, "tok", `{"jsonrpc":"2.0","id":2,"method":"initialize","params":{"protocolVersion":"1999-01-01"}}`, nil))
if unknown["result"].(map[string]any)["protocolVersion"] != LatestProtocolVersion {
t.Fatalf("an unknown version must get the latest: %v", unknown)
}
if got := post(t, h, "tok", `{"jsonrpc":"2.0","method":"notifications/initialized"}`, nil); got.Code != http.StatusAccepted || got.Body.Len() != 0 {
t.Fatalf("a notification must be 202 with no body: %d %q", got.Code, got.Body.String())
}
list := decode(t, post(t, h, "tok", `{"jsonrpc":"2.0","id":"l","method":"tools/list"}`, nil))
tools := list["result"].(map[string]any)["tools"].([]any)
var names []string
for _, tool := range tools {
entry := tool.(map[string]any)
names = append(names, entry["name"].(string))
if entry["description"] == "" || entry["inputSchema"].(map[string]any)["type"] != "object" {
t.Fatalf("tool without description or schema: %v", entry)
}
}
if strings.Join(names, ",") != "show_file,show_image,show_html,notify" {
t.Fatalf("tools = %v", names)
}
if list["id"] != "l" {
t.Fatalf("a string id must be echoed: %v", list)
}
call := decode(t, post(t, h, "tok", `{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"show_html","arguments":{"html":"<b>x</b>"}}}`, nil))
content := call["result"].(map[string]any)["content"].([]any)[0].(map[string]any)
if content["type"] != "text" || content["text"] != "ok show_html" || call["result"].(map[string]any)["isError"] != false {
t.Fatalf("call result = %v", call)
}
if len(service.calls) != 1 || service.calls[0] != `tok show_html {"html":"<b>x</b>"}` {
t.Fatalf("service calls = %v", service.calls)
}
bad := decode(t, post(t, h, "tok", `{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"rm_rf"}}`, nil))
if bad["error"].(map[string]any)["code"].(float64) != -32602 {
t.Fatalf("an unknown tool must be invalid params: %v", bad)
}
missing := decode(t, post(t, h, "tok", `{"jsonrpc":"2.0","id":5,"method":"resources/list"}`, nil))
if missing["error"].(map[string]any)["code"].(float64) != -32601 {
t.Fatalf("an unknown method must be method-not-found: %v", missing)
}
parse := decode(t, post(t, h, "tok", `[{"jsonrpc":"2.0","id":6,"method":"ping"}]`, nil))
if parse["error"].(map[string]any)["code"].(float64) != -32700 {
t.Fatalf("a batch is refused: %v", parse)
}
if len(service.calls) != 1 {
t.Fatalf("refused requests must not call tools: %v", service.calls)
}
}
func TestEndpointRefusesUnknownTokensBrowsersRemotePeersAndGET(t *testing.T) {
service := &fakeService{known: map[string]bool{"tok": true}}
h := Handler{Service: service}
ping := `{"jsonrpc":"2.0","id":1,"method":"ping"}`
if got := post(t, h, "other", ping, nil); got.Code != http.StatusNotFound {
t.Fatalf("unknown token = %d", got.Code)
}
if got := post(t, h, "tok", ping, func(r *http.Request) { r.Header.Set("Origin", "https://evil.example") }); got.Code != http.StatusForbidden {
t.Fatalf("browser origin = %d", got.Code)
}
if got := post(t, h, "tok", ping, func(r *http.Request) { r.RemoteAddr = "100.64.0.9:4000" }); got.Code != http.StatusForbidden {
t.Fatalf("remote peer = %d", got.Code)
}
if got := post(t, h, "tok", ping, func(r *http.Request) { r.RemoteAddr = "[::1]:4000" }); got.Code != http.StatusOK {
t.Fatalf("IPv6 loopback = %d", got.Code)
}
if got := post(t, h, "tok", "", func(r *http.Request) { r.Method = http.MethodGet }); got.Code != http.StatusMethodNotAllowed {
t.Fatalf("GET = %d", got.Code)
}
large := `{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"show_html","arguments":{"html":"` + strings.Repeat("a", MaxRequestBytes) + `"}}}`
if got := decode(t, post(t, h, "tok", large, nil)); got["error"] == nil {
t.Fatalf("an oversized request must be refused: %v", got)
}
if len(service.calls) != 0 {
t.Fatalf("refused requests reached the service: %v", service.calls)
}
}
func TestHarnessRegistrationConfig(t *testing.T) {
url := "http://127.0.0.1:8080/mcp/chat/abc"
var claude map[string]map[string]map[string]string
if err := json.Unmarshal([]byte(ClaudeMCPConfig(url)), &claude); err != nil {
t.Fatal(err)
}
if got := claude["mcpServers"]["pipelines"]; got["type"] != "http" || got["url"] != url {
t.Fatalf("claude config = %v", claude)
}
if ClaudeAllowedTools() != "mcp__pipelines" {
t.Fatalf("claude allowed tools = %q", ClaudeAllowedTools())
}
codex := CodexConfig(url)["mcp_servers"].(map[string]any)["pipelines"].(map[string]any)
if codex["url"] != url {
t.Fatalf("codex config = %v", codex)
}
open := OpenCodeConfig(url)["mcp"].(map[string]any)["pipelines"].(map[string]any)
if open["type"] != "remote" || open["url"] != url || open["enabled"] != true {
t.Fatalf("opencode config = %v", open)
}
for _, name := range HarnessToolNames(ToolShowFile) {
if tool, ok := ToolFromHarnessName(name); !ok || tool != ToolShowFile {
t.Fatalf("%s not recognised", name)
}
}
for _, name := range []string{"pipelines_rm", "mcp__other__show_file", "show_file", "bash"} {
if _, ok := ToolFromHarnessName(name); ok {
t.Fatalf("%s must not be a Pipelines tool", name)
}
}
}
+53
View File
@@ -0,0 +1,53 @@
// Package chattools is the harness-neutral half of the Pipelines chat tools:
// the MCP server a chat's model calls to show the operator a file, an image or
// an HTML view, or to notify their phone. The tools act on Pipelines itself,
// never on the harness or the workspace.
//
// The server (internal/server) owns tokens, persistence and the tool effects.
// The harness adapters (claude, codex, opencode) only need the endpoint URL to
// register, which they obtain from the Registry configured here, so none of
// them imports the server.
package chattools
import "sync"
// ServerName is the MCP server name every harness registers. It fixes the tool
// names the harnesses report: Claude "mcp__pipelines__show_file", OpenCode
// "pipelines_show_file", Codex "pipelines/show_file".
const ServerName = "pipelines"
// Registry issues the loopback MCP endpoint URLs harnesses register. Each URL
// embeds an unguessable token the server resolves to the chat it serves.
type Registry interface {
// SessionURL is the endpoint dedicated to one chat session, stable across
// server restarts so a detached harness process keeps working.
SessionURL(sessionID string) (string, error)
// PendingURL is an endpoint for a chat whose id the harness assigns when
// it creates it (a Codex thread). bind attaches it to that id; calls are
// refused until then.
PendingURL() (url string, bind func(sessionID string) error, err error)
// InstanceURL is the endpoint of one harness process that serves many
// chats (the OpenCode service). Its calls are attributed only to the one
// chat whose matching tool call is running at that moment.
InstanceURL(harness string) (string, error)
}
var (
mu sync.RWMutex
current Registry
)
// Configure installs the registry the harness adapters use. A nil registry
// disables registration: chats start without the Pipelines tools.
func Configure(registry Registry) {
mu.Lock()
defer mu.Unlock()
current = registry
}
// Current returns the configured registry, or nil when tools are disabled.
func Current() Registry {
mu.RLock()
defer mu.RUnlock()
return current
}
+101
View File
@@ -0,0 +1,101 @@
package chattools
// The tool names, as the MCP server lists them.
const (
ToolShowFile = "show_file"
ToolShowImage = "show_image"
ToolShowHTML = "show_html"
ToolNotify = "notify"
)
// MaxHTMLBytes bounds one show_html document. A larger one is refused, never
// truncated: a cut document would render as something the model did not write.
const MaxHTMLBytes = 512 << 10
// IsTool reports whether name is one of the Pipelines tools.
func IsTool(name string) bool {
switch name {
case ToolShowFile, ToolShowImage, ToolShowHTML, ToolNotify:
return true
}
return false
}
// Instructions is the MCP initialize instructions text.
const Instructions = "These tools act on Pipelines, the app the operator reads this chat in, not on your workspace. " +
"Use show_file / show_image instead of telling the operator a path to open, show_html for diagrams, charts or small visual views, " +
"and notify only when the operator should look at their phone now."
type toolDefinition struct {
Name string `json:"name"`
Title string `json:"title,omitempty"`
Description string `json:"description"`
InputSchema map[string]any `json:"inputSchema"`
Annotations map[string]any `json:"annotations,omitempty"`
}
func stringProperty(description string) map[string]any {
return map[string]any{"type": "string", "description": description}
}
func objectSchema(required []string, properties map[string]any) map[string]any {
return map[string]any{"type": "object", "properties": properties, "required": required, "additionalProperties": false}
}
// definitions is the tools/list result, in a fixed order.
func definitions() []toolDefinition {
return []toolDefinition{
{
Name: ToolShowFile,
Title: "Show a file in the chat",
Description: "Show the operator an existing file from this machine directly in the Pipelines chat: images appear inline, " +
"documents (PDF, Markdown, text, CSV, HTML, and others) as a preview card they can tap to open or download. " +
"Use this instead of telling the operator a path to navigate to. The file must be inside the operator's home directory. " +
"A relative path is resolved against the chat's working directory.",
InputSchema: objectSchema([]string{"path"}, map[string]any{
"path": stringProperty("Absolute path, ~/path, or a path relative to the chat's working directory."),
"title": stringProperty("Optional short caption shown above the file."),
}),
Annotations: map[string]any{"readOnlyHint": true, "openWorldHint": false},
},
{
Name: ToolShowImage,
Title: "Show an image in the chat",
Description: "Show the operator an image inline in the Pipelines chat, from a file on this machine (inside the operator's home) " +
"or from an https:// URL. The URL is loaded by the operator's device without cookies.",
InputSchema: objectSchema([]string{"url_or_path"}, map[string]any{
"url_or_path": stringProperty("An https:// image URL, or a file path as for show_file."),
"title": stringProperty("Optional short caption."),
"alt": stringProperty("Optional description of the image for accessibility."),
}),
Annotations: map[string]any{"readOnlyHint": true},
},
{
Name: ToolShowHTML,
Title: "Show an HTML view in the chat",
Description: "Render a self-contained HTML or SVG document inline in the Pipelines chat: diagrams, charts, tables, small visual views. " +
"It is shown in a sandbox with no scripts, no network and no access to the app: use inline CSS and inline SVG, " +
"<details> for expandable parts and CSS :hover for interaction; JavaScript does not run and external resources do not load. " +
"The operator can open it full screen. At most 512 KiB.",
InputSchema: objectSchema([]string{"html"}, map[string]any{
"html": stringProperty("The complete HTML (or a bare <svg>) document."),
"title": stringProperty("Optional short caption."),
"height_hint": map[string]any{"type": "integer", "description": "Optional preferred inline height in logical pixels (120-600)."},
}),
Annotations: map[string]any{"readOnlyHint": true, "openWorldHint": false},
},
{
Name: ToolNotify,
Title: "Notify the operator's phone",
Description: "Send a push notification to the operator's phone that opens this chat when tapped. " +
"Use it sparingly, for things they should know now (a long task finished, you are blocked on them). " +
"Limited to 5 per minute per chat. Returns whether delivery was accepted.",
InputSchema: objectSchema([]string{"title", "message"}, map[string]any{
"title": stringProperty("Short notification title (one line)."),
"message": stringProperty("Notification text (one or two sentences)."),
"priority": map[string]any{"type": "string", "enum": []string{"low", "default", "high"}, "description": "Optional priority; default is default."},
}),
Annotations: map[string]any{"readOnlyHint": false, "destructiveHint": false, "openWorldHint": true},
},
}
}
+3
View File
@@ -320,6 +320,9 @@ type session struct {
model string // CLI model selection (alias or full id); "" uses the CLI default
mode string // permission mode id; "" uses the CLI's own default
createdAt int64
// toolsOff is set after a spawn carrying the Pipelines tools failed, so
// the chat keeps starting without them (chattools).
toolsOff bool
proc *process
starting chan struct{}
+43
View File
@@ -0,0 +1,43 @@
package claude
import (
"log"
"git.a-wan.net/alan/pipelines/internal/chattools"
)
// pipelinesToolArgs registers the Pipelines MCP server for one chat: its own
// endpoint (a per-session token) as an inline --mcp-config, added to the
// operator's configured MCP servers rather than replacing them, with the tools
// pre-approved because they only present content in Pipelines. Without a
// configured registry, or when the endpoint cannot be issued, the chat starts
// without them.
func pipelinesToolArgs(sessionID string) []string {
registry := chattools.Current()
if registry == nil {
return nil
}
url, err := registry.SessionURL(sessionID)
if err != nil {
log.Printf("claude chat %s: Pipelines tools not registered: %v", sessionID, err)
return nil
}
return []string{"--mcp-config", chattools.ClaudeMCPConfig(url), "--allowedTools", chattools.ClaudeAllowedTools()}
}
// disableTools reacts to a failed spawn: when the Pipelines tools were part of
// it, they are turned off for this chat (logged with the reason) and true asks
// the caller to retry without them.
func (s *session) disableTools(err error) bool {
if chattools.Current() == nil {
return false
}
s.mu.Lock()
defer s.mu.Unlock()
if s.toolsOff {
return false
}
s.toolsOff = true
log.Printf("claude chat %s: start with the Pipelines tools failed (%v); retrying without them", s.id, err)
return true
}
+68
View File
@@ -0,0 +1,68 @@
package claude
import (
"encoding/json"
"errors"
"slices"
"testing"
"git.a-wan.net/alan/pipelines/internal/chattools"
)
type toolRegistry struct{ fail bool }
func (r toolRegistry) SessionURL(id string) (string, error) {
if r.fail {
return "", errors.New("no store")
}
return "http://127.0.0.1:9/mcp/chat/token-" + id, nil
}
func (toolRegistry) PendingURL() (string, func(string) error, error) {
return "", nil, errors.New("unused")
}
func (toolRegistry) InstanceURL(string) (string, error) { return "", errors.New("unused") }
func TestCLIArgsRegisterThePipelinesToolsPerSession(t *testing.T) {
chat := &Chat{sessions: map[string]*session{}}
s := chat.sessionFor("id-1", "/fixture")
args, _ := s.cliArgs(false)
if slices.Contains(args, "--mcp-config") {
t.Fatalf("no registry must add no MCP config: %q", args)
}
chattools.Configure(toolRegistry{})
t.Cleanup(func() { chattools.Configure(nil) })
args, _ = s.cliArgs(true)
var config struct {
MCPServers map[string]struct {
Type string `json:"type"`
URL string `json:"url"`
} `json:"mcpServers"`
}
if err := json.Unmarshal([]byte(argValue(args, "--mcp-config")), &config); err != nil {
t.Fatalf("--mcp-config is not JSON: %q", args)
}
if got := config.MCPServers["pipelines"]; got.Type != "http" || got.URL != "http://127.0.0.1:9/mcp/chat/token-id-1" {
t.Fatalf("mcp config = %+v", config)
}
if argValue(args, "--allowedTools") != "mcp__pipelines" || argValue(args, "--resume") != "id-1" {
t.Fatalf("args = %q", args)
}
// A start that failed with the tools retries once without them.
if !s.disableTools(errors.New("unknown option --mcp-config")) {
t.Fatal("the first failure must ask for a retry without the tools")
}
if s.disableTools(errors.New("again")) {
t.Fatal("a chat already without the tools must not retry again")
}
if args, _ = s.cliArgs(true); slices.Contains(args, "--mcp-config") {
t.Fatalf("a chat whose start refused the tools must start without them: %q", args)
}
chattools.Configure(toolRegistry{fail: true})
other := chat.sessionFor("id-2", "/fixture")
if args, _ = other.cliArgs(false); slices.Contains(args, "--mcp-config") {
t.Fatalf("an unissued endpoint must start without the tools: %q", args)
}
}
+16 -1
View File
@@ -95,8 +95,11 @@ func (s *session) cliArgs(resume bool) ([]string, string) {
args = append(args, "--session-id", s.id)
}
s.mu.Lock()
model, mode, title := s.model, s.mode, s.title
model, mode, title, toolsOff := s.model, s.mode, s.title, s.toolsOff
s.mu.Unlock()
if !toolsOff {
args = append(args, pipelinesToolArgs(s.id)...)
}
if model != "" {
args = append(args, "--model", model)
}
@@ -130,6 +133,18 @@ func (s *session) spawn(ctx context.Context) (*process, error) {
if p := s.existingHost(); p != nil {
return p, nil
}
p, err := s.spawnOnce(ctx)
if err == nil || ctx.Err() != nil || !s.disableTools(err) {
return p, err
}
if p := s.existingHost(); p != nil {
return p, nil
}
return s.spawnOnce(ctx)
}
// spawnOnce starts and initializes one CLI process with the current arguments.
func (s *session) spawnOnce(ctx context.Context) (*process, error) {
args, mode := s.cliArgs(findTranscriptFile(s.id) != "")
env, notices := s.chat.processEnv(ctx, s.directory)
s.mu.Lock()
+2 -2
View File
@@ -461,7 +461,7 @@ func (c *Chat) PromptWithMessageIDModelFiles(ctx context.Context, id, text, mess
var refused *rpcCallError
if errors.As(err, &refused) && refused.Message == "thread not found: "+id {
var resumed json.RawMessage
resumed, err = c.call(ctx, "thread/resume", map[string]any{"threadId": id, "excludeTurns": true})
resumed, err = c.resumeThread(ctx, map[string]any{"threadId": id, "excludeTurns": true}, id)
if err == nil {
var response struct {
Thread struct {
@@ -549,7 +549,7 @@ func (c *Chat) Create(ctx context.Context, title, directory string) (protocol.Ch
if strings.TrimSpace(directory) == "" {
return protocol.ChatSession{}, errors.New("a directory is required")
}
raw, err := c.call(ctx, "thread/start", map[string]any{
raw, err := c.startThread(ctx, map[string]any{
"cwd": directory,
"sandbox": "workspace-write",
})
+76
View File
@@ -0,0 +1,76 @@
package codex
import (
"context"
"encoding/json"
"errors"
"log"
"maps"
"git.a-wan.net/alan/pipelines/internal/chattools"
)
// withPipelinesTools returns params with the thread config override that
// registers the Pipelines MCP server at url, leaving params unchanged.
func withPipelinesTools(params map[string]any, url string) map[string]any {
next := maps.Clone(params)
next["config"] = chattools.CodexConfig(url)
return next
}
// startThread calls thread/start registering the Pipelines tools for the new
// thread. Its id is assigned by the App Server, so the endpoint is issued
// pending and bound to the id the reply names. An App Server that refuses the
// override still gets the thread, started without the tools (logged).
func (c *Chat) startThread(ctx context.Context, params map[string]any) (json.RawMessage, error) {
registry := chattools.Current()
if registry == nil {
return c.call(ctx, "thread/start", params)
}
url, bind, err := registry.PendingURL()
if err != nil {
log.Printf("codex chat: Pipelines tools not registered: %v", err)
return c.call(ctx, "thread/start", params)
}
raw, err := c.call(ctx, "thread/start", withPipelinesTools(params, url))
var refused *rpcCallError
if errors.As(err, &refused) {
log.Printf("codex chat: thread/start refused the Pipelines tools (%s); starting without them", refused.Message)
return c.call(ctx, "thread/start", params)
}
if err != nil {
return raw, err
}
var reply struct {
Thread struct {
ID string `json:"id"`
} `json:"thread"`
}
if json.Unmarshal(raw, &reply) == nil && reply.Thread.ID != "" {
if err := bind(reply.Thread.ID); err != nil {
log.Printf("codex chat %s: Pipelines tools endpoint not bound: %v", reply.Thread.ID, err)
}
}
return raw, nil
}
// resumeThread calls thread/resume for id, registering the thread's own
// Pipelines tools endpoint; a refusal of the override resumes without it.
func (c *Chat) resumeThread(ctx context.Context, params map[string]any, id string) (json.RawMessage, error) {
registry := chattools.Current()
if registry == nil {
return c.call(ctx, "thread/resume", params)
}
url, err := registry.SessionURL(id)
if err != nil {
log.Printf("codex chat %s: Pipelines tools not registered: %v", id, err)
return c.call(ctx, "thread/resume", params)
}
raw, err := c.call(ctx, "thread/resume", withPipelinesTools(params, url))
var refused *rpcCallError
if errors.As(err, &refused) && refused.Message != "thread not found: "+id {
log.Printf("codex chat %s: thread/resume refused the Pipelines tools (%s); resuming without them", id, refused.Message)
return c.call(ctx, "thread/resume", params)
}
return raw, err
}
+100
View File
@@ -0,0 +1,100 @@
package codex
import (
"context"
"encoding/json"
"errors"
"sync"
"testing"
"git.a-wan.net/alan/pipelines/internal/chattools"
)
type toolRegistry struct {
mu sync.Mutex
bound []string
}
func (r *toolRegistry) SessionURL(id string) (string, error) {
return "http://127.0.0.1:9/mcp/chat/session-" + id, nil
}
func (r *toolRegistry) PendingURL() (string, func(string) error, error) {
return "http://127.0.0.1:9/mcp/chat/pending", func(id string) error {
r.mu.Lock()
defer r.mu.Unlock()
r.bound = append(r.bound, id)
return nil
}, nil
}
func (r *toolRegistry) InstanceURL(string) (string, error) { return "", errors.New("unused") }
func mcpURL(t *testing.T, raw json.RawMessage) string {
t.Helper()
var params struct {
Config struct {
MCPServers map[string]struct {
URL string `json:"url"`
} `json:"mcp_servers"`
} `json:"config"`
}
if err := json.Unmarshal(raw, &params); err != nil {
t.Fatal(err)
}
return params.Config.MCPServers["pipelines"].URL
}
func TestThreadStartRegistersAndBindsThePipelinesTools(t *testing.T) {
registry := &toolRegistry{}
chattools.Configure(registry)
t.Cleanup(func() { chattools.Configure(nil) })
var urls []string
chat := modelTestChat(t, func(method string, raw json.RawMessage) any {
switch method {
case "thread/start":
urls = append(urls, mcpURL(t, raw))
return json.RawMessage(`{"thread":{"id":"thr-1","cwd":"/w"},"model":"gpt","modelProvider":"openai"}`)
case "thread/resume":
urls = append(urls, mcpURL(t, raw))
return json.RawMessage(`{"thread":{"id":"thr-1"}}`)
}
return json.RawMessage(`{}`)
})
if _, err := chat.Create(context.Background(), "", "/w"); err != nil {
t.Fatal(err)
}
if _, err := chat.resumeThread(context.Background(), map[string]any{"threadId": "thr-1"}, "thr-1"); err != nil {
t.Fatal(err)
}
if len(urls) != 2 || urls[0] != "http://127.0.0.1:9/mcp/chat/pending" || urls[1] != "http://127.0.0.1:9/mcp/chat/session-thr-1" {
t.Fatalf("registered urls = %v", urls)
}
if len(registry.bound) != 1 || registry.bound[0] != "thr-1" {
t.Fatalf("the pending endpoint must be bound to the new thread: %v", registry.bound)
}
}
func TestThreadStartWithoutToolsWhenTheAppServerRefusesThem(t *testing.T) {
chattools.Configure(&toolRegistry{})
t.Cleanup(func() { chattools.Configure(nil) })
var attempts []string
chat := modelTestChat(t, func(method string, raw json.RawMessage) any {
if method != "thread/start" {
return json.RawMessage(`{}`)
}
url := mcpURL(t, raw)
attempts = append(attempts, url)
if url != "" {
return &rpcError{Code: -32602, Message: "invalid config: mcp_servers"}
}
return json.RawMessage(`{"thread":{"id":"thr-2","cwd":"/w"}}`)
})
session, err := chat.Create(context.Background(), "", "/w")
if err != nil || session.ID != "thr-2" {
t.Fatalf("the chat must still start: %v %v", session, err)
}
if len(attempts) != 2 || attempts[0] == "" || attempts[1] != "" {
t.Fatalf("attempts = %q", attempts)
}
}
+21 -3
View File
@@ -11,6 +11,7 @@ import (
"errors"
"fmt"
"io"
"log"
"net/http"
"net/url"
"os"
@@ -307,13 +308,30 @@ func OpenChat(ctx context.Context, executable, directory string) (*Connection, e
if err != nil {
return nil, err
}
if overrides != nil && backend == "v2" {
if c.configContent, err = configContent(os.Getenv("OPENCODE_CONFIG_CONTENT"), overrides); err != nil {
if backend != "v2" {
overrides = nil
}
// The Pipelines chat tools are registered on every spawned chat service.
withTools := withPipelinesTools(overrides)
if withTools != nil {
if c.configContent, err = configContent(os.Getenv("OPENCODE_CONFIG_CONTENT"), withTools); err != nil {
return nil, err
}
}
if err := c.startServe(ctx); err != nil {
return nil, err
if withTools == nil || ctx.Err() != nil {
return nil, err
}
log.Printf("OpenCode chat service did not start with the Pipelines tools (%v); starting without them", err)
c.process, c.configContent = nil, ""
if overrides != nil {
if c.configContent, err = configContent(os.Getenv("OPENCODE_CONFIG_CONTENT"), overrides); err != nil {
return nil, err
}
}
if err := c.startServe(ctx); err != nil {
return nil, err
}
}
return c, nil
}
+30
View File
@@ -0,0 +1,30 @@
package opencode
import (
"log"
"git.a-wan.net/alan/pipelines/internal/chattools"
)
// withPipelinesTools adds the Pipelines MCP server to a chat service's config
// overrides. One OpenCode service serves every chat and its MCP requests name
// no session, so it registers the service's instance endpoint; the server
// attributes each call to the chat whose stream shows it running. The
// operator's own overrides win, including a server they named "pipelines".
// It returns overrides unchanged when the tools are not configured.
func withPipelinesTools(overrides map[string]any) map[string]any {
registry := chattools.Current()
if registry == nil {
return overrides
}
url, err := registry.InstanceURL("opencode")
if err != nil {
log.Printf("OpenCode chat: Pipelines tools not registered: %v", err)
return overrides
}
merged := chattools.OpenCodeConfig(url)
if overrides != nil {
mergeConfig(merged, overrides)
}
return merged
}
+52
View File
@@ -0,0 +1,52 @@
package opencode
import (
"encoding/json"
"errors"
"testing"
"git.a-wan.net/alan/pipelines/internal/chattools"
)
type toolRegistry struct{}
func (toolRegistry) SessionURL(string) (string, error) { return "", errors.New("unused") }
func (toolRegistry) PendingURL() (string, func(string) error, error) {
return "", nil, errors.New("unused")
}
func (toolRegistry) InstanceURL(harness string) (string, error) {
return "http://127.0.0.1:9/mcp/chat/instance-" + harness, nil
}
func TestChatServiceConfigRegistersThePipelinesTools(t *testing.T) {
if got := withPipelinesTools(nil); got != nil {
t.Fatalf("no registry must add nothing: %v", got)
}
chattools.Configure(toolRegistry{})
t.Cleanup(func() { chattools.Configure(nil) })
content, err := configContent(`{"model":"x/y","mcp":{"mine":{"type":"local","command":["m"]}}}`, withPipelinesTools(nil))
if err != nil {
t.Fatal(err)
}
var config struct {
Model string `json:"model"`
MCP map[string]map[string]any `json:"mcp"`
}
if err := json.Unmarshal([]byte(content), &config); err != nil {
t.Fatal(err)
}
if config.Model != "x/y" || config.MCP["mine"] == nil {
t.Fatalf("the operator's config must be kept: %s", content)
}
if got := config.MCP["pipelines"]; got["type"] != "remote" || got["url"] != "http://127.0.0.1:9/mcp/chat/instance-opencode" || got["enabled"] != true {
t.Fatalf("pipelines mcp = %v", got)
}
// Chat overrides the operator set win, including their own "pipelines".
merged := withPipelinesTools(map[string]any{"mcp": map[string]any{"pipelines": map[string]any{"enabled": false}}, "limit": 1.0})
server := merged["mcp"].(map[string]any)["pipelines"].(map[string]any)
if server["enabled"] != false || server["url"] == nil || merged["limit"] != 1.0 {
t.Fatalf("merged = %v", merged)
}
}
+13
View File
@@ -179,6 +179,19 @@ func EnsureOwnedChatService(ctx context.Context, executable, directory string) (
return nil, err
}
}
// The Pipelines chat tools are registered on the chat service; a service
// that does not start with them is started without (logged).
if withTools := withPipelinesTools(overrides); withTools != nil {
toolsContent, err := configContent(os.Getenv("OPENCODE_CONFIG_CONTENT"), withTools)
if err != nil {
return nil, err
}
c, err := ensureOwnedService(ctx, chatOwnedService, toolsContent, executable, directory, nil, "")
if err == nil || ctx.Err() != nil {
return c, err
}
log.Printf("OpenCode chat service did not start with the Pipelines tools (%v); starting without them", err)
}
return ensureOwnedService(ctx, chatOwnedService, content, executable, directory, nil, "")
}
+159
View File
@@ -0,0 +1,159 @@
package pipeline
import (
"context"
"crypto/rand"
"database/sql"
"encoding/hex"
"encoding/json"
"errors"
"time"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// The chat tool tables: the MCP endpoint tokens a harness registers (each
// names the scope it serves: "session:<id>", "pending:" until a Codex thread
// id is bound, or "instance:<harness>") and the items a chat's model showed.
func (s *Store) initChatTools() error {
_, err := s.db.Exec(`CREATE TABLE IF NOT EXISTS chat_tool_tokens (
token TEXT PRIMARY KEY,
scope TEXT NOT NULL,
created_at INTEGER NOT NULL);
CREATE INDEX IF NOT EXISTS chat_tool_tokens_scope ON chat_tool_tokens(scope);
CREATE TABLE IF NOT EXISTS chat_shown_items (
id TEXT PRIMARY KEY,
session_id TEXT NOT NULL,
created_at INTEGER NOT NULL,
payload TEXT NOT NULL);
CREATE INDEX IF NOT EXISTS chat_shown_items_session ON chat_shown_items(session_id, created_at);`)
return err
}
// ChatToolToken returns the token issued for scope, issuing one when none is.
func (s *Store) ChatToolToken(ctx context.Context, scope string) (string, error) {
var token string
err := s.db.QueryRowContext(ctx, `SELECT token FROM chat_tool_tokens WHERE scope=? ORDER BY created_at, token LIMIT 1`, scope).Scan(&token)
if err == nil {
return token, nil
}
if !errors.Is(err, sql.ErrNoRows) {
return "", err
}
return s.IssueChatToolToken(ctx, scope)
}
// IssueChatToolToken records a new random token for scope.
func (s *Store) IssueChatToolToken(ctx context.Context, scope string) (string, error) {
var secret [32]byte
if _, err := rand.Read(secret[:]); err != nil {
return "", err
}
token := hex.EncodeToString(secret[:])
if _, err := s.db.ExecContext(ctx, `INSERT INTO chat_tool_tokens(token,scope,created_at) VALUES(?,?,?)`, token, scope, time.Now().UnixMilli()); err != nil {
return "", err
}
return token, nil
}
// ChatToolScope returns the scope a token serves (found false for an unknown
// token).
func (s *Store) ChatToolScope(ctx context.Context, token string) (string, bool, error) {
var scope string
err := s.db.QueryRowContext(ctx, `SELECT scope FROM chat_tool_tokens WHERE token=?`, token).Scan(&scope)
if errors.Is(err, sql.ErrNoRows) {
return "", false, nil
}
if err != nil {
return "", false, err
}
return scope, true, nil
}
// BindChatToolToken moves a token to scope (a pending Codex token to its thread).
func (s *Store) BindChatToolToken(ctx context.Context, token, scope string) error {
result, err := s.db.ExecContext(ctx, `UPDATE chat_tool_tokens SET scope=? WHERE token=?`, scope, token)
if err != nil {
return err
}
if n, _ := result.RowsAffected(); n == 0 {
return errors.New("unknown chat tool token")
}
return nil
}
// AppendChatShownItem records one shown item and applies the retention bounds:
// at most protocol.ChatShownLimit items per chat, and HTML bodies only for the
// newest documents within protocol.ChatShownHTMLBudget.
func (s *Store) AppendChatShownItem(ctx context.Context, sessionID string, item protocol.ChatShownItem) error {
payload, err := json.Marshal(item)
if err != nil {
return err
}
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
return err
}
defer tx.Rollback()
if _, err := tx.ExecContext(ctx, `INSERT INTO chat_shown_items(id,session_id,created_at,payload) VALUES(?,?,?,?)`, item.ID, sessionID, item.CreatedAt, string(payload)); err != nil {
return err
}
if _, err := tx.ExecContext(ctx, `DELETE FROM chat_shown_items WHERE session_id=? AND id NOT IN (
SELECT id FROM chat_shown_items WHERE session_id=? ORDER BY created_at DESC, rowid DESC LIMIT ?)`, sessionID, sessionID, protocol.ChatShownLimit); err != nil {
return err
}
items, err := chatShownItems(ctx, tx, sessionID)
if err != nil {
return err
}
budget := protocol.ChatShownHTMLBudget
for i := len(items) - 1; i >= 0; i-- {
current := items[i]
if current.Kind != protocol.ChatShownHTML || current.Expired {
continue
}
if len(current.HTML) <= budget {
budget -= len(current.HTML)
continue
}
budget = 0
current.HTML, current.Expired = "", true
data, err := json.Marshal(current)
if err != nil {
return err
}
if _, err := tx.ExecContext(ctx, `UPDATE chat_shown_items SET payload=? WHERE id=?`, string(data), current.ID); err != nil {
return err
}
}
return tx.Commit()
}
// ChatShownItems returns a chat's retained items, oldest first.
func (s *Store) ChatShownItems(ctx context.Context, sessionID string) ([]protocol.ChatShownItem, error) {
return chatShownItems(ctx, s.db, sessionID)
}
type chatShownQueryer interface {
QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
}
func chatShownItems(ctx context.Context, db chatShownQueryer, sessionID string) ([]protocol.ChatShownItem, error) {
rows, err := db.QueryContext(ctx, `SELECT payload FROM chat_shown_items WHERE session_id=? ORDER BY created_at, rowid`, sessionID)
if err != nil {
return nil, err
}
defer rows.Close()
var items []protocol.ChatShownItem
for rows.Next() {
var payload string
if err := rows.Scan(&payload); err != nil {
return nil, err
}
var item protocol.ChatShownItem
if json.Unmarshal([]byte(payload), &item) == nil {
items = append(items, item)
}
}
return items, rows.Err()
}
+4
View File
@@ -113,6 +113,10 @@ CREATE TABLE IF NOT EXISTS submissions (id INTEGER PRIMARY KEY, name TEXT NOT NU
db.Close()
return nil, err
}
if err := s.initChatTools(); err != nil {
db.Close()
return nil, err
}
if err := s.initRunSizes(); err != nil {
db.Close()
return nil, err
+55
View File
@@ -0,0 +1,55 @@
package protocol
// ChatShown is the pushed frame type for an item a chat's model showed the
// operator through the Pipelines tools (show_file, show_image, show_html,
// notify). The chat_subscribe reply carries the retained list in the same
// ChatShown field.
const ChatShown = "chat_shown"
// The ChatShownItem kinds.
const (
ChatShownFile = "file"
ChatShownImage = "image"
ChatShownHTML = "html"
ChatShownNotify = "notify"
)
// ChatShownLimit bounds the items retained per chat, and ChatShownHTMLBudget
// the HTML bytes kept across them: older documents beyond it keep their entry
// but drop the body (Expired).
const (
ChatShownLimit = 100
ChatShownHTMLBudget = 2 << 20
)
// ChatShownFrame is one chat's shown items, oldest first.
type ChatShownFrame struct {
SessionID string `json:"session_id"`
Items []ChatShownItem `json:"items"`
}
// ChatShownItem is one entry. A file or image Path is an absolute path on the
// chat's own machine, served by that machine's /files endpoint; URL is an
// https image address the client loads without credentials.
type ChatShownItem struct {
ID string `json:"id"`
Kind string `json:"kind"`
CreatedAt int64 `json:"created_at"`
Title string `json:"title,omitempty"`
Path string `json:"path,omitempty"`
Name string `json:"name,omitempty"`
Size int64 `json:"size,omitempty"`
Mime string `json:"mime,omitempty"`
URL string `json:"url,omitempty"`
Alt string `json:"alt,omitempty"`
HTML string `json:"html,omitempty"`
HTMLBytes int `json:"html_bytes,omitempty"`
// HeightHint is the model's preferred inline height in logical pixels.
HeightHint int `json:"height_hint,omitempty"`
Expired bool `json:"expired,omitempty"`
Message string `json:"message,omitempty"`
Priority string `json:"priority,omitempty"`
Delivered bool `json:"delivered,omitempty"`
// Detail says why a notification was not delivered.
Detail string `json:"detail,omitempty"`
}
+4
View File
@@ -259,6 +259,10 @@ type Message struct {
ChatTurnDiffList *ChatTurnDiffList `json:"chat_turn_diffs,omitempty"`
ChatTurnDiff *ChatTurnDiff `json:"chat_turn_diff,omitempty"`
ChatUnqueue *ChatUnqueueRequest `json:"chat_unqueue,omitempty"`
// ChatShown carries the items the chat's model showed through the Pipelines
// tools: the retained list on the chat_subscribe reply, one new item on a
// pushed chat_shown frame.
ChatShown *ChatShownFrame `json:"chat_shown,omitempty"`
// ChatDirectories carries the operator's directory choices on a
// chat_directories response (home first, then recent operator-session
// directories, deduplicated and bounded). Additive/omitempty so older peers
+3
View File
@@ -86,6 +86,9 @@ type chatHub struct {
// shellRuns runs the operator's own shell commands (chat_shell_runner.go);
// nil refuses them.
shellRuns *chatShellRunner
// shown holds the items chats showed through the Pipelines tools; the
// subscribe reply carries a chat's retained list. nil records none.
shown chatShownStore
}
// chatPart is the retained form of one part. Text and reasoning deltas append to
+1 -1
View File
@@ -241,7 +241,7 @@ func handleChatSubscribe(request protocol.Message, broker chatBroker, hub *chatH
// The reply carries the prompts the server still holds for the session, so
// a reloaded client draws them as Queued without any device storage.
queue := hub.queueFrame(query.SessionID)
_ = write(protocol.Message{Type: protocol.ChatSubscribe, ID: request.ID, ChatQueue: &queue})
_ = write(protocol.Message{Type: protocol.ChatSubscribe, ID: request.ID, ChatQueue: &queue, ChatShown: hub.shownFrame(query.SessionID)})
if err := hub.ensureObserving(sub.room, broker); err != nil {
sub.close()
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "could not observe session " + query.SessionID})
+139
View File
@@ -0,0 +1,139 @@
package server
import (
"context"
"encoding/json"
"reflect"
"slices"
"strings"
"time"
"git.a-wan.net/alan/pipelines/internal/chattools"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// openCodeCodeTool is OpenCode V2's code-mode tool: the model calls MCP tools
// from a script (`tools.pipelines.show_file({...})`) instead of as tool parts
// of their own, so the stream shows one running "execute" part.
const openCodeCodeTool = "execute"
// awaitToolCallSession attributes a call on a shared harness endpoint (one
// OpenCode service serves every chat, and its MCP requests carry no session)
// to the chat whose retained stream shows this call running: a tool part with
// the tool's harness name and exactly these arguments, or a running code-mode
// script that calls the tool. Several scripts are told apart by the argument
// values they contain. The harness reports the part as running before or while
// it calls the tool, so this waits up to wait for it. It returns "" when no
// chat matches, and ambiguous when several distinct chats still do: a call is
// never guessed into a chat.
func (h *chatHub) awaitToolCallSession(ctx context.Context, tool string, arguments json.RawMessage, wait time.Duration) (string, bool) {
var want map[string]any
if json.Unmarshal(arguments, &want) != nil {
return "", false
}
deadline := time.Now().Add(wait)
for {
sessions := h.runningToolCallSessions(tool, want)
switch {
case len(sessions) == 1:
return sessions[0], false
case len(sessions) > 1:
return "", true
}
if time.Now().After(deadline) {
return "", false
}
select {
case <-ctx.Done():
return "", false
case <-time.After(50 * time.Millisecond):
}
}
}
func (h *chatHub) runningToolCallSessions(tool string, want map[string]any) []string {
names := chattools.HarnessToolNames(tool)
h.mu.Lock()
defer h.mu.Unlock()
var exact, scripts, narrowed []string
for sessionID, turn := range h.turns {
match := turnToolCallMatch(turn, names, tool, want)
if match == toolCallExact {
exact = append(exact, sessionID)
}
if match >= toolCallScript {
scripts = append(scripts, sessionID)
}
if match >= toolCallScriptWithArguments {
narrowed = append(narrowed, sessionID)
}
}
for _, candidates := range [][]string{exact, scripts, narrowed} {
if len(candidates) == 1 {
return candidates
}
}
slices.Sort(scripts)
return scripts
}
type toolCallMatch int
const (
toolCallNone toolCallMatch = iota
toolCallScript
toolCallScriptWithArguments
toolCallExact
)
// turnToolCallMatch is the strongest evidence one chat's running tool parts
// give that it is making this call.
func turnToolCallMatch(turn *chatTurn, names []string, tool string, want map[string]any) toolCallMatch {
best := toolCallNone
for _, message := range turn.messages {
for _, part := range message.parts {
p := part.part
if p.Type != "tool" || p.State == nil || (p.State.Status != protocol.ChatToolRunning && p.State.Status != "pending") {
continue
}
if slices.Contains(names, p.Name) {
var got map[string]any
if json.Unmarshal(p.State.Input, &got) == nil && reflect.DeepEqual(got, want) {
return toolCallExact
}
continue
}
if p.Name != openCodeCodeTool {
continue
}
var script struct {
Code string `json:"code"`
}
if json.Unmarshal(p.State.Input, &script) != nil || !strings.Contains(script.Code, chattools.ServerName+"."+tool+"(") {
continue
}
match := toolCallScript
if scriptHasArguments(script.Code, want) {
match = toolCallScriptWithArguments
}
best = max(best, match)
}
}
return best
}
// scriptHasArguments reports whether every string argument appears in code,
// literally or JSON-escaped.
func scriptHasArguments(code string, want map[string]any) bool {
for _, value := range want {
text, ok := value.(string)
if !ok || text == "" {
continue
}
escaped, _ := json.Marshal(text)
if !strings.Contains(code, text) && !strings.Contains(code, strings.Trim(string(escaped), `"`)) {
return false
}
}
return true
}
+143
View File
@@ -0,0 +1,143 @@
package server
import (
"context"
"errors"
"io"
"log"
"mime"
"net/http"
"net/url"
"os"
"path/filepath"
"strings"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// shownFile is a resolved file inside the operator's home.
type shownFile struct {
path string
name string
size int64
mime string
}
func (f shownFile) item(kind, title string) protocol.ChatShownItem {
return protocol.ChatShownItem{Kind: kind, Title: title, Path: f.path, Name: f.name, Size: f.size, Mime: f.mime}
}
// resolveShownFile applies the /files endpoint's containment rules to a model
// supplied path: it must name an existing regular file whose real path (every
// symlink resolved) is inside the operator's home and not on a special
// filesystem. A relative path is taken from the chat's working directory.
func (s *chatToolService) resolveShownFile(ctx context.Context, sessionID, requested string) (shownFile, error) {
requested = strings.TrimSpace(requested)
if requested == "" {
return shownFile{}, errors.New("a path is required")
}
home, err := s.home()
if err != nil {
return shownFile{}, err
}
home = filepath.Clean(home)
realHome, err := filepath.EvalSymlinks(home)
if err != nil {
return shownFile{}, errors.New("the operator's home directory is not available")
}
if !filepath.IsAbs(requested) && !strings.HasPrefix(requested, "~") {
directory := s.chatSessionDirectory(ctx, sessionID)
if directory == "" {
return shownFile{}, errors.New("path " + requested + " is relative and this chat has no recorded working directory; pass an absolute path")
}
requested = filepath.Join(directory, requested)
}
target, err := expandHomePath(home, requested)
if err != nil {
return shownFile{}, err
}
_, realTarget, err := resolveInsideHome(realHome, target)
if err != nil {
if strings.Contains(err.Error(), "outside the home directory") {
return shownFile{}, errors.New("path " + requested + " is outside the operator's home directory; only files inside home can be shown")
}
return shownFile{}, err
}
info, err := os.Stat(realTarget)
if err != nil {
return shownFile{}, describePathError(requested, err)
}
if info.IsDir() {
return shownFile{}, errors.New(requested + " is a directory; show one file")
}
if !info.Mode().IsRegular() || specialFilesystem(realTarget) {
return shownFile{}, errors.New(requested + " is not a regular file")
}
return shownFile{path: realTarget, name: filepath.Base(realTarget), size: info.Size(), mime: shownFileMime(realTarget)}, nil
}
// shownFileMime is the type the /files endpoint will serve: by extension, else
// sniffed from the first bytes.
func shownFileMime(path string) string {
if byExtension := mime.TypeByExtension(filepath.Ext(path)); byExtension != "" {
media, _, err := mime.ParseMediaType(byExtension)
if err == nil {
return media
}
}
file, err := os.Open(path)
if err != nil {
return "application/octet-stream"
}
defer file.Close()
var sample [512]byte
n, err := file.Read(sample[:])
if err != nil && !errors.Is(err, io.EOF) {
return "application/octet-stream"
}
media, _, _ := mime.ParseMediaType(http.DetectContentType(sample[:n]))
if media == "" {
return "application/octet-stream"
}
return media
}
// shownImageURL accepts only an absolute https URL without credentials.
func shownImageURL(raw string) (string, error) {
if len(raw) > 2048 {
return "", errors.New("the image URL is longer than 2048 characters")
}
parsed, err := url.Parse(raw)
if err != nil || parsed.Host == "" {
return "", errors.New("the image URL is not a valid absolute URL")
}
if parsed.Scheme != "https" {
return "", errors.New("only https:// image URLs can be shown")
}
if parsed.User != nil {
return "", errors.New("the image URL must not carry credentials")
}
return parsed.String(), nil
}
// chatToolNotifier sends one model-requested phone notification for a chat and
// reports whether ntfy accepted it, or why not.
type chatToolNotifier func(ctx context.Context, sessionID, title, message string) (bool, string)
// publishToolNotification publishes through the operator's existing "system"
// ntfy destination (the one chat attention uses), honoring their ntfy switch.
// Tapping it opens the chat (pipelines://chat/<id>).
func (h *chatHub) publishToolNotification(ctx context.Context, sessionID, title, message string) (bool, string) {
if !chatAttentionConfigured() {
return false, "phone notifications (ntfy) are not configured on this Pipelines server"
}
if !chatNotificationSettings(ctx, h.settings).NtfyEnabled {
return false, "the operator has turned phone notifications off"
}
click, views := chatAttentionLinks(sessionID)
if _, err := chatAttentionPublish(ctx, "system", truncateUTF8(title, 256), truncateUTF8(message, 2000), "", nil, click, views...); err != nil {
log.Printf("chat tool notification session=%s: %v", sessionID, err)
return false, "the notification service refused it: " + err.Error()
}
return true, ""
}
+84
View File
@@ -0,0 +1,84 @@
package server
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"path/filepath"
"strings"
"testing"
"time"
"git.a-wan.net/alan/pipelines/internal/chattools"
"git.a-wan.net/alan/pipelines/internal/pipeline"
)
// The endpoint is served on the server's own listener: a harness registers
// the URL the registry issues and calls show_html over it.
func TestChatToolsEndpointOnTheServerListener(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
store, err := pipeline.Open(filepath.Join(t.TempDir(), "tools-http.db"))
if err != nil {
t.Fatal(err)
}
defer store.Close()
handler := HandlerWithOptions(ctx, Options{}, store)
defer func() { cancel(); WaitRuns(handler) }()
srv := httptest.NewServer(handler)
defer srv.Close()
if err := ConfigureChatTools(store, strings.TrimPrefix(srv.URL, "http://")); err != nil {
t.Fatal(err)
}
defer chattools.Configure(nil)
url, err := chattools.Current().SessionURL("ses_http")
if err != nil || !strings.HasPrefix(url, srv.URL+"/mcp/chat/") {
t.Fatalf("session url = %q %v", url, err)
}
rpc := func(target, body string) (int, map[string]any) {
request, _ := http.NewRequestWithContext(ctx, http.MethodPost, target, strings.NewReader(body))
request.Header.Set("Content-Type", "application/json")
request.Header.Set("Accept", "application/json, text/event-stream")
response, err := http.DefaultClient.Do(request)
if err != nil {
t.Fatal(err)
}
defer response.Body.Close()
var out map[string]any
_ = json.NewDecoder(response.Body).Decode(&out)
return response.StatusCode, out
}
if code, out := rpc(url, `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}`); code != 200 || out["result"] == nil {
t.Fatalf("initialize = %d %v", code, out)
}
code, out := rpc(url, `{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"show_html","arguments":{"html":"<svg/>"}}}`)
if code != 200 || out["result"].(map[string]any)["isError"] != false {
t.Fatalf("tools/call = %d %v", code, out)
}
if items, _ := store.ChatShownItems(ctx, "ses_http"); len(items) != 1 {
t.Fatalf("items = %v", items)
}
if code, _ := rpc(srv.URL+"/mcp/chat/"+strings.Repeat("f", 64), `{"jsonrpc":"2.0","id":1,"method":"ping"}`); code != http.StatusNotFound {
t.Fatalf("unknown token = %d", code)
}
}
func TestLoopbackBase(t *testing.T) {
for addr, want := range map[string]string{
"127.0.0.1:8080": "http://127.0.0.1:8080",
":8080": "http://127.0.0.1:8080",
"0.0.0.0:9": "http://127.0.0.1:9",
"[::]:9": "http://127.0.0.1:9",
"[::1]:9": "http://[::1]:9",
"localhost:7": "http://localhost:7",
} {
if got, err := loopbackBase(addr); err != nil || got != want {
t.Fatalf("%s = %q %v", addr, got, err)
}
}
if _, err := loopbackBase("100.64.0.2:8080"); err == nil {
t.Fatal("a non-loopback listener cannot serve the loopback-only endpoint")
}
}
+129
View File
@@ -0,0 +1,129 @@
package server
import (
"context"
"encoding/json"
"fmt"
"strings"
"unicode/utf8"
"git.a-wan.net/alan/pipelines/internal/chattools"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// run executes one tool for sessionID. A non-nil item is recorded and shown;
// the result is the short text the model reads.
func (s *chatToolService) run(ctx context.Context, sessionID, tool string, arguments json.RawMessage) (*protocol.ChatShownItem, chattools.Result) {
fail := func(format string, args ...any) (*protocol.ChatShownItem, chattools.Result) {
return nil, chattools.Result{Text: fmt.Sprintf(format, args...), IsError: true}
}
var in struct {
Path string `json:"path"`
URLOrPath string `json:"url_or_path"`
Title string `json:"title"`
Alt string `json:"alt"`
HTML string `json:"html"`
HeightHint int `json:"height_hint"`
Message string `json:"message"`
Priority string `json:"priority"`
}
if err := json.Unmarshal(arguments, &in); err != nil {
return fail("The arguments must be a JSON object matching the %s schema: %v", tool, err)
}
title := boundedLine(in.Title, 200)
switch tool {
case chattools.ToolShowFile:
file, err := s.resolveShownFile(ctx, sessionID, in.Path)
if err != nil {
return fail("Nothing was shown: %v", err)
}
item := file.item(protocol.ChatShownFile, title)
return &item, chattools.Result{Text: fmt.Sprintf("Shown in the operator's Pipelines chat: %s (%s).", file.name, humanBytes(file.size))}
case chattools.ToolShowImage:
source := strings.TrimSpace(in.URLOrPath)
alt := boundedLine(in.Alt, 500)
if strings.Contains(source, "://") {
address, err := shownImageURL(source)
if err != nil {
return fail("Nothing was shown: %v", err)
}
item := protocol.ChatShownItem{Kind: protocol.ChatShownImage, Title: title, URL: address, Alt: alt}
return &item, chattools.Result{Text: "Shown in the operator's Pipelines chat: the image at " + address + "."}
}
file, err := s.resolveShownFile(ctx, sessionID, source)
if err != nil {
return fail("Nothing was shown: %v", err)
}
if !strings.HasPrefix(file.mime, "image/") {
return fail("Nothing was shown: %s is %s, not an image; use show_file for documents.", file.name, file.mime)
}
item := file.item(protocol.ChatShownImage, title)
item.Alt = alt
return &item, chattools.Result{Text: fmt.Sprintf("Shown in the operator's Pipelines chat: the image %s (%s).", file.name, humanBytes(file.size))}
case chattools.ToolShowHTML:
if strings.TrimSpace(in.HTML) == "" {
return fail("Nothing was shown: html is empty.")
}
if len(in.HTML) > chattools.MaxHTMLBytes {
return fail("Nothing was shown: the document is %s; the limit is 512 KiB. Simplify it (inline SVG, fewer data points) and call show_html again.", humanBytes(int64(len(in.HTML))))
}
if !utf8.ValidString(in.HTML) {
return fail("Nothing was shown: html is not valid UTF-8.")
}
item := protocol.ChatShownItem{Kind: protocol.ChatShownHTML, Title: title, HTML: in.HTML, HTMLBytes: len(in.HTML), HeightHint: clampHeightHint(in.HeightHint)}
return &item, chattools.Result{Text: fmt.Sprintf("Shown in the operator's Pipelines chat (%s, sandboxed: scripts and network are disabled).", humanBytes(int64(len(in.HTML))))}
case chattools.ToolNotify:
return s.runNotify(ctx, sessionID, title, in.Message, in.Priority)
}
return fail("Unknown tool %s.", tool)
}
func (s *chatToolService) runNotify(ctx context.Context, sessionID, title, message, priority string) (*protocol.ChatShownItem, chattools.Result) {
message = boundedLine(message, 2000)
if title == "" || message == "" {
return nil, chattools.Result{Text: "Not sent: title and message are both required.", IsError: true}
}
switch priority {
case "":
priority = "default"
case "low", "default", "high":
default:
return nil, chattools.Result{Text: "Not sent: priority must be low, default or high.", IsError: true}
}
if !s.limiter.allow(sessionID, s.now()) {
return nil, chattools.Result{Text: "Not sent: this chat already sent 5 notifications in the last minute. Wait before notifying again.", IsError: true}
}
delivered, detail := s.notify(ctx, sessionID, title, message)
item := protocol.ChatShownItem{Kind: protocol.ChatShownNotify, Title: title, Message: message, Priority: priority, Delivered: delivered, Detail: detail}
if !delivered {
return &item, chattools.Result{Text: "Not delivered: " + detail + ".", IsError: true}
}
return &item, chattools.Result{Text: "Delivery accepted: the notification was handed to the operator's phone notification service (ntfy)."}
}
// boundedLine folds text to one line of at most limit bytes.
func boundedLine(text string, limit int) string {
return truncateUTF8(singleLine(text), limit)
}
func clampHeightHint(hint int) int {
switch {
case hint <= 0:
return 0
case hint < 120:
return 120
case hint > 600:
return 600
}
return hint
}
func humanBytes(n int64) string {
switch {
case n >= 1<<20:
return fmt.Sprintf("%.1f MiB", float64(n)/(1<<20))
case n >= 1<<10:
return fmt.Sprintf("%.1f KiB", float64(n)/(1<<10))
}
return fmt.Sprintf("%d bytes", n)
}
+190
View File
@@ -0,0 +1,190 @@
package server
import (
"context"
"crypto/rand"
"encoding/hex"
"encoding/json"
"log"
"net/http"
"strings"
"sync"
"time"
"git.a-wan.net/alan/pipelines/internal/chattools"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// chatShownStore persists the items a chat's model showed (pipeline.Store).
type chatShownStore interface {
AppendChatShownItem(ctx context.Context, sessionID string, item protocol.ChatShownItem) error
ChatShownItems(ctx context.Context, sessionID string) ([]protocol.ChatShownItem, error)
}
// chatToolCorrelationWait is how long a call on a shared (instance) endpoint
// waits for the harness stream to report the matching running tool call.
var chatToolCorrelationWait = 3 * time.Second
// chatToolService runs the Pipelines tools (chattools.Service) for the chat an
// endpoint token serves, records each shown item and pushes it to the chat's
// subscribers.
type chatToolService struct {
tokens chatToolTokenStore
shown chatShownStore
hub *chatHub
registry operatorRegistry
home func() (string, error)
notify chatToolNotifier
limiter *chatNotifyLimiter
now func() time.Time
}
func newChatToolService(tokens chatToolTokenStore, shown chatShownStore, hub *chatHub, registry operatorRegistry) *chatToolService {
return &chatToolService{tokens: tokens, shown: shown, hub: hub, registry: registry, home: OperatorHomeDirectory,
notify: hub.publishToolNotification, limiter: newChatNotifyLimiter(5, time.Minute), now: time.Now}
}
// registerChatTools serves the MCP endpoint on mux. The route exists only on
// the server's own listener; neither the web proxy nor the peer relay forwards
// it.
func registerChatTools(mux *http.ServeMux, service *chatToolService, version string) {
handler := chattools.Handler{Service: service, Version: version}
mux.HandleFunc(chatToolPath+"{token}", func(w http.ResponseWriter, r *http.Request) {
handler.ServeHTTP(w, r, r.PathValue("token"))
})
}
func (s *chatToolService) Known(ctx context.Context, token string) bool {
if s == nil || s.tokens == nil || len(token) != 64 {
return false
}
_, found, err := s.tokens.ChatToolScope(ctx, token)
return err == nil && found
}
func (s *chatToolService) Call(ctx context.Context, token, tool string, arguments json.RawMessage) chattools.Result {
sessionID, refusal := s.session(ctx, token, tool, arguments)
if refusal != "" {
return chattools.Result{Text: refusal, IsError: true}
}
item, result := s.run(ctx, sessionID, tool, arguments)
if item == nil {
return result
}
item.ID = newChatShownID()
item.CreatedAt = s.now().UnixMilli()
if s.shown != nil {
if err := s.shown.AppendChatShownItem(ctx, sessionID, *item); err != nil {
log.Printf("chat tools session=%s: record %s: %v", sessionID, tool, err)
return chattools.Result{Text: "Pipelines could not record this item: " + err.Error(), IsError: true}
}
}
if s.hub != nil {
s.hub.fanout(sessionID, protocol.Message{Type: protocol.ChatShown,
ChatShown: &protocol.ChatShownFrame{SessionID: sessionID, Items: []protocol.ChatShownItem{*item}}}, "")
}
return result
}
// session resolves the chat a call belongs to. A session token names it; a
// shared harness instance token is attributed to the one chat whose stream
// shows this exact call running, and refused when none or several do.
func (s *chatToolService) session(ctx context.Context, token, tool string, arguments json.RawMessage) (string, string) {
scope, found, err := s.tokens.ChatToolScope(ctx, token)
if err != nil || !found {
return "", "This Pipelines endpoint is not recognised."
}
if id, ok := strings.CutPrefix(scope, chatToolSessionScope); ok && id != "" {
return id, ""
}
if _, ok := strings.CutPrefix(scope, chatToolInstanceScope); ok && s.hub != nil {
id, ambiguous := s.hub.awaitToolCallSession(ctx, tool, arguments, chatToolCorrelationWait)
if ambiguous {
return "", "Pipelines could not tell which chat made this call (another chat made an identical one); retry with a different title."
}
if id == "" {
return "", "Pipelines could not match this call to a chat it is showing; the tools work only in chats opened through Pipelines."
}
return id, ""
}
return "", "This chat is not ready for Pipelines tools yet."
}
// chatSessionDirectory is the chat's recorded working directory, or "".
func (s *chatToolService) chatSessionDirectory(ctx context.Context, sessionID string) string {
if s.registry == nil {
return ""
}
session, found, err := s.registry.OperatorSession(ctx, sessionID)
if err != nil || !found {
return ""
}
return session.Directory
}
func (s *chatToolService) chatTitle(ctx context.Context, sessionID string) string {
if s.registry == nil {
return ""
}
session, found, err := s.registry.OperatorSession(ctx, sessionID)
if err != nil || !found {
return ""
}
return session.Title
}
func newChatShownID() string {
var b [12]byte
_, _ = rand.Read(b[:])
return "shown_" + hex.EncodeToString(b[:])
}
// chatNotifyLimiter is a per-chat sliding-window rate limit.
type chatNotifyLimiter struct {
mu sync.Mutex
limit int
window time.Duration
sent map[string][]time.Time
}
func newChatNotifyLimiter(limit int, window time.Duration) *chatNotifyLimiter {
return &chatNotifyLimiter{limit: limit, window: window, sent: map[string][]time.Time{}}
}
// allow records one notification for sessionID at now unless the window is
// full.
func (l *chatNotifyLimiter) allow(sessionID string, now time.Time) bool {
l.mu.Lock()
defer l.mu.Unlock()
kept := l.sent[sessionID][:0]
for _, at := range l.sent[sessionID] {
if now.Sub(at) < l.window {
kept = append(kept, at)
}
}
if len(kept) >= l.limit {
l.sent[sessionID] = kept
return false
}
l.sent[sessionID] = append(kept, now)
return true
}
// shownFrame is a chat's retained shown items for its subscribe reply, or nil
// when it has none (or none are recorded on this server).
func (h *chatHub) shownFrame(sessionID string) *protocol.ChatShownFrame {
if h == nil || h.shown == nil {
return nil
}
ctx, cancel := context.WithTimeout(h.baseCtx, 5*time.Second)
defer cancel()
items, err := h.shown.ChatShownItems(ctx, sessionID)
if err != nil {
log.Printf("chat shown items session=%s: %v", sessionID, err)
return nil
}
if len(items) == 0 {
return nil
}
return &protocol.ChatShownFrame{SessionID: sessionID, Items: items}
}
+330
View File
@@ -0,0 +1,330 @@
package server
import (
"context"
"encoding/json"
"os"
"path/filepath"
"strings"
"testing"
"time"
"git.a-wan.net/alan/pipelines/internal/chattools"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
type chatToolFixture struct {
store *pipeline.Store
service *chatToolService
hub *chatHub
home string
notified []string
}
func newChatToolFixture(t *testing.T) *chatToolFixture {
t.Helper()
store, err := pipeline.Open(filepath.Join(t.TempDir(), "tools.db"))
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { store.Close() })
f := &chatToolFixture{store: store, hub: newChatHub(), home: t.TempDir()}
f.hub.shown = store
f.service = newChatToolService(store, store, f.hub, store)
f.service.home = func() (string, error) { return f.home, nil }
f.service.notify = func(_ context.Context, sessionID, title, message string) (bool, string) {
f.notified = append(f.notified, sessionID+": "+title)
return true, ""
}
return f
}
func (f *chatToolFixture) token(t *testing.T, scope string) string {
t.Helper()
token, err := f.store.ChatToolToken(context.Background(), scope)
if err != nil {
t.Fatal(err)
}
return token
}
func (f *chatToolFixture) call(token, tool, arguments string) chattools.Result {
return f.service.Call(context.Background(), token, tool, json.RawMessage(arguments))
}
func (f *chatToolFixture) items(t *testing.T, sessionID string) []protocol.ChatShownItem {
t.Helper()
items, err := f.store.ChatShownItems(context.Background(), sessionID)
if err != nil {
t.Fatal(err)
}
return items
}
func TestChatToolTokensAttributeCallsToExactlyOneChat(t *testing.T) {
f := newChatToolFixture(t)
a, b := f.token(t, chatToolSessionScope+"ses_a"), f.token(t, chatToolSessionScope+"ses_b")
if a == b || len(a) != 64 || !f.service.Known(context.Background(), a) {
t.Fatalf("tokens must be distinct 256-bit values: %q %q", a, b)
}
if again := f.token(t, chatToolSessionScope+"ses_a"); again != a {
t.Fatal("a session keeps its token (a detached harness keeps its endpoint)")
}
if f.service.Known(context.Background(), strings.Repeat("0", 64)) {
t.Fatal("an unknown token must be refused")
}
if r := f.call(a, "show_html", `{"html":"<p>A</p>","title":"For A"}`); r.IsError {
t.Fatal(r.Text)
}
if got := f.items(t, "ses_a"); len(got) != 1 || got[0].Kind != protocol.ChatShownHTML || got[0].Title != "For A" || got[0].HTML != "<p>A</p>" || got[0].ID == "" || got[0].CreatedAt == 0 {
t.Fatalf("ses_a items = %+v", got)
}
if got := f.items(t, "ses_b"); len(got) != 0 {
t.Fatalf("another chat must not receive the item: %+v", got)
}
frame := f.hub.shownFrame("ses_a")
if frame == nil || frame.SessionID != "ses_a" || len(frame.Items) != 1 {
t.Fatalf("subscribe frame = %+v", frame)
}
if f.hub.shownFrame("ses_b") != nil {
t.Fatal("a chat with no items has no frame")
}
registry := chatToolRegistry{store: f.store, base: "http://127.0.0.1:1"}
url, bind, err := registry.PendingURL()
if err != nil {
t.Fatal(err)
}
pending := strings.TrimPrefix(url, "http://127.0.0.1:1"+chatToolPath)
if r := f.call(pending, "show_html", `{"html":"x"}`); !r.IsError {
t.Fatal("an unbound pending token must not show anything")
}
if err := bind("019a6f7e-1c2d-7e3f-8a9b-0c1d2e3f4a5b"); err != nil {
t.Fatal(err)
}
if r := f.call(pending, "show_html", `{"html":"x"}`); r.IsError || len(f.items(t, "019a6f7e-1c2d-7e3f-8a9b-0c1d2e3f4a5b")) != 1 {
t.Fatalf("a bound token serves its thread: %v", r)
}
}
func TestShowFileStaysInsideHome(t *testing.T) {
f := newChatToolFixture(t)
token := f.token(t, chatToolSessionScope+"ses_f")
inside := filepath.Join(f.home, "work", "report.md")
if err := os.MkdirAll(filepath.Dir(inside), 0o700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(inside, []byte("# Report\n"), 0o600); err != nil {
t.Fatal(err)
}
outside := filepath.Join(t.TempDir(), "secret.txt")
if err := os.WriteFile(outside, []byte("secret"), 0o600); err != nil {
t.Fatal(err)
}
if err := os.Symlink(outside, filepath.Join(f.home, "link.txt")); err != nil {
t.Fatal(err)
}
if err := f.store.RecordOperatorSession(context.Background(), "ses_f", filepath.Join(f.home, "work"), "Files", protocol.ChatSessionTagOperator); err != nil {
t.Fatal(err)
}
r := f.call(token, "show_file", `{"path":"`+inside+`","title":"The report"}`)
if r.IsError || !strings.Contains(r.Text, "report.md") {
t.Fatalf("inside home: %v", r)
}
realHome, _ := filepath.EvalSymlinks(f.home)
got := f.items(t, "ses_f")
if len(got) != 1 || got[0].Path != filepath.Join(realHome, "work", "report.md") || got[0].Name != "report.md" || got[0].Size != 9 || !strings.HasPrefix(got[0].Mime, "text/") {
t.Fatalf("item = %+v", got)
}
if r := f.call(token, "show_file", `{"path":"report.md"}`); r.IsError {
t.Fatalf("a relative path resolves against the chat's directory: %v", r)
}
if r := f.call(token, "show_file", `{"path":"~/work/report.md"}`); r.IsError {
t.Fatalf("a ~/ path resolves in home: %v", r)
}
for _, refused := range []string{outside, filepath.Join(f.home, "link.txt"), filepath.Join(f.home, "work"), filepath.Join(f.home, "missing.png"), "../../../etc/passwd", ""} {
if r := f.call(token, "show_file", `{"path":"`+refused+`"}`); !r.IsError {
t.Fatalf("%q must be refused: %v", refused, r)
}
}
if len(f.items(t, "ses_f")) != 3 {
t.Fatal("refused paths must record nothing")
}
}
func TestShowImageAcceptsHomeImagesAndHTTPSOnly(t *testing.T) {
f := newChatToolFixture(t)
token := f.token(t, chatToolSessionScope+"ses_i")
image := filepath.Join(f.home, "plot.png")
if err := os.WriteFile(image, []byte("\x89PNG\r\n\x1a\n"), 0o600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(f.home, "notes.txt"), []byte("x"), 0o600); err != nil {
t.Fatal(err)
}
if r := f.call(token, "show_image", `{"url_or_path":"`+image+`","alt":"A plot"}`); r.IsError {
t.Fatal(r.Text)
}
if r := f.call(token, "show_image", `{"url_or_path":"https://example.com/a.png","title":"Remote"}`); r.IsError {
t.Fatal(r.Text)
}
for _, refused := range []string{"http://example.com/a.png", "https://user:pw@example.com/a.png", "javascript:alert(1)", "file:///etc/passwd", filepath.Join(f.home, "notes.txt")} {
if r := f.call(token, "show_image", `{"url_or_path":"`+refused+`"}`); !r.IsError {
t.Fatalf("%q must be refused: %v", refused, r)
}
}
got := f.items(t, "ses_i")
if len(got) != 2 || got[0].Kind != protocol.ChatShownImage || got[0].Mime != "image/png" || got[0].Alt != "A plot" || got[1].URL != "https://example.com/a.png" || got[1].Path != "" {
t.Fatalf("items = %+v", got)
}
}
func TestShowHTMLSizeLimitAndRetention(t *testing.T) {
f := newChatToolFixture(t)
token := f.token(t, chatToolSessionScope+"ses_h")
if r := f.call(token, "show_html", `{"html":"`+strings.Repeat("a", chattools.MaxHTMLBytes+1)+`"}`); !r.IsError || !strings.Contains(r.Text, "512 KiB") {
t.Fatalf("an oversized document must be refused with the limit: %v", r)
}
if r := f.call(token, "show_html", `{"html":" "}`); !r.IsError {
t.Fatal("an empty document must be refused")
}
if len(f.items(t, "ses_h")) != 0 {
t.Fatal("refused documents must record nothing")
}
full := strings.Repeat("b", chattools.MaxHTMLBytes)
for range 5 {
if r := f.call(token, "show_html", `{"html":"`+full+`","height_hint":5000}`); r.IsError {
t.Fatal(r.Text)
}
}
got := f.items(t, "ses_h")
if len(got) != 5 || got[0].HeightHint != 600 {
t.Fatalf("items = %d, hint %d", len(got), got[0].HeightHint)
}
// 2 MiB of HTML is retained: the newest four bodies, the oldest expired.
if !got[0].Expired || got[0].HTML != "" || got[0].HTMLBytes != chattools.MaxHTMLBytes {
t.Fatalf("the oldest body must be dropped under the budget: expired=%v len=%d", got[0].Expired, len(got[0].HTML))
}
for _, item := range got[1:] {
if item.Expired || len(item.HTML) != chattools.MaxHTMLBytes {
t.Fatal("the newest bodies must be kept")
}
}
for range protocol.ChatShownLimit + 5 {
f.service.now = func() time.Time { return time.Now().Add(time.Hour) }
if r := f.call(token, "show_html", `{"html":"<i>x</i>"}`); r.IsError {
t.Fatal(r.Text)
}
}
if got := f.items(t, "ses_h"); len(got) != protocol.ChatShownLimit {
t.Fatalf("a chat retains at most %d items, got %d", protocol.ChatShownLimit, len(got))
}
}
func TestNotifyIsRateLimitedPerChat(t *testing.T) {
f := newChatToolFixture(t)
a, b := f.token(t, chatToolSessionScope+"ses_n1"), f.token(t, chatToolSessionScope+"ses_n2")
now := time.Unix(1_800_000_000, 0)
f.service.now = func() time.Time { return now }
for i := range 5 {
if r := f.call(a, "notify", `{"title":"Done","message":"Build finished","priority":"high"}`); r.IsError {
t.Fatalf("notification %d: %v", i, r)
}
}
if r := f.call(a, "notify", `{"title":"Done","message":"again"}`); !r.IsError || !strings.Contains(r.Text, "5 notifications") {
t.Fatalf("the sixth in a minute must be refused: %v", r)
}
if r := f.call(b, "notify", `{"title":"Other","message":"chat"}`); r.IsError {
t.Fatalf("another chat has its own limit: %v", r)
}
now = now.Add(61 * time.Second)
if r := f.call(a, "notify", `{"title":"Later","message":"ok"}`); r.IsError {
t.Fatalf("the window slides: %v", r)
}
if r := f.call(a, "notify", `{"title":"Bad","message":"x","priority":"urgent"}`); !r.IsError {
t.Fatal("an unknown priority must be refused")
}
if len(f.notified) != 7 || f.notified[0] != "ses_n1: Done" {
t.Fatalf("notified = %v", f.notified)
}
got := f.items(t, "ses_n1")
if len(got) != 6 || got[0].Kind != protocol.ChatShownNotify || !got[0].Delivered || got[0].Priority != "high" {
t.Fatalf("items = %+v", got)
}
f.service.notify = func(context.Context, string, string, string) (bool, string) { return false, "ntfy is not configured" }
r := f.call(b, "notify", `{"title":"Fails","message":"x"}`)
if !r.IsError || !strings.Contains(r.Text, "ntfy is not configured") {
t.Fatalf("an undelivered notification is reported: %v", r)
}
if last := f.items(t, "ses_n2"); len(last) != 2 || last[1].Delivered || last[1].Detail != "ntfy is not configured" {
t.Fatalf("the undelivered entry is recorded: %+v", last)
}
}
func TestInstanceTokenCallsNeedOneMatchingRunningToolCall(t *testing.T) {
f := newChatToolFixture(t)
token := f.token(t, chatToolInstanceScope+"opencode")
saved := chatToolCorrelationWait
chatToolCorrelationWait = 100 * time.Millisecond
t.Cleanup(func() { chatToolCorrelationWait = saved })
arguments := `{"html":"<p>diagram</p>","title":"Plan"}`
if r := f.call(token, "show_html", arguments); !r.IsError {
t.Fatal("a shared-instance call with no running tool call must be refused")
}
running := func(sessionID, name, input string) {
f.hub.apply(protocol.ChatEventFrame{SessionID: sessionID, MessageID: "msg_" + sessionID, Kind: protocol.ChatEventTool,
Part: &protocol.ChatPart{Type: "tool", ID: "prt_" + sessionID, Name: name, State: &protocol.ChatToolState{Status: protocol.ChatToolRunning, Input: json.RawMessage(input)}}})
}
running("ses_x", "pipelines_show_html", `{"title":"Plan","html":"<p>diagram</p>"}`)
running("ses_y", "pipelines_show_html", `{"html":"<p>other</p>"}`)
running("ses_z", "bash", arguments)
if r := f.call(token, "show_html", arguments); r.IsError {
t.Fatal(r.Text)
}
if len(f.items(t, "ses_x")) != 1 || len(f.items(t, "ses_y"))+len(f.items(t, "ses_z")) != 0 {
t.Fatal("the call belongs to the chat running exactly this call")
}
running("ses_y", "pipelines_show_html", arguments)
if r := f.call(token, "show_html", arguments); !r.IsError || !strings.Contains(r.Text, "identical") {
t.Fatalf("two chats running the same call must be refused: %v", r)
}
}
// OpenCode V2 calls MCP tools from its code-mode "execute" script, so the
// stream shows the script, not a tool part of the Pipelines tool's own name.
func TestInstanceTokenCallsMatchOpenCodeCodeModeScripts(t *testing.T) {
f := newChatToolFixture(t)
token := f.token(t, chatToolInstanceScope+"opencode")
saved := chatToolCorrelationWait
chatToolCorrelationWait = 100 * time.Millisecond
t.Cleanup(func() { chatToolCorrelationWait = saved })
script := func(sessionID, part, code string) {
input, _ := json.Marshal(map[string]string{"code": code})
f.hub.apply(protocol.ChatEventFrame{SessionID: sessionID, MessageID: "msg_" + sessionID, Kind: protocol.ChatEventTool,
Part: &protocol.ChatPart{Type: "tool", ID: part, Name: "execute", State: &protocol.ChatToolState{Status: protocol.ChatToolRunning, Input: input}}})
}
if err := os.WriteFile(filepath.Join(f.home, "a.png"), []byte("\x89PNG\r\n\x1a\n"), 0o600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(f.home, "b.png"), []byte("\x89PNG\r\n\x1a\n"), 0o600); err != nil {
t.Fatal(err)
}
script("ses_p", "prt_p", `return tools.pipelines.show_file({ path: "~/a.png", title: "Checker" })`)
script("ses_q", "prt_q", `return tools.other.show_file({ path: "~/a.png" })`)
if r := f.call(token, "show_file", `{"path":"~/a.png","title":"Checker"}`); r.IsError {
t.Fatal(r.Text)
}
if len(f.items(t, "ses_p")) != 1 || len(f.items(t, "ses_q")) != 0 {
t.Fatal("the script calling the Pipelines tool owns the call")
}
script("ses_q", "prt_q2", `await tools.pipelines.show_file({ path: "~/b.png" })`)
if r := f.call(token, "show_file", `{"path":"~/b.png"}`); r.IsError || len(f.items(t, "ses_q")) != 1 {
t.Fatalf("two scripts are told apart by their arguments: %v", r)
}
if r := f.call(token, "show_file", `{"path":"~/c.png"}`); !r.IsError {
t.Fatal("arguments neither script contains must not be guessed into a chat")
}
}
+110
View File
@@ -0,0 +1,110 @@
package server
import (
"context"
"errors"
"net"
"time"
"git.a-wan.net/alan/pipelines/internal/chattools"
)
// chatToolTokenStore persists the MCP endpoint tokens (pipeline.Store).
type chatToolTokenStore interface {
ChatToolToken(ctx context.Context, scope string) (string, error)
IssueChatToolToken(ctx context.Context, scope string) (string, error)
ChatToolScope(ctx context.Context, token string) (string, bool, error)
BindChatToolToken(ctx context.Context, token, scope string) error
}
// The token scopes.
const (
chatToolSessionScope = "session:"
chatToolPendingScope = "pending:"
chatToolInstanceScope = "instance:"
)
// chatToolPath is the loopback route prefix of the MCP endpoint. The web proxy
// and the peer relay forward an allowlist that does not include it.
const chatToolPath = "/mcp/chat/"
// chatToolRegistry issues the endpoint URLs harnesses register
// (chattools.Registry) on the server's own loopback listener.
type chatToolRegistry struct {
store chatToolTokenStore
base string
}
func (r chatToolRegistry) url(token string) string { return r.base + chatToolPath + token }
func (r chatToolRegistry) SessionURL(sessionID string) (string, error) {
if !validChatSessionID(sessionID) {
return "", errors.New("invalid chat session id")
}
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
token, err := r.store.ChatToolToken(ctx, chatToolSessionScope+sessionID)
if err != nil {
return "", err
}
return r.url(token), nil
}
func (r chatToolRegistry) PendingURL() (string, func(string) error, error) {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
token, err := r.store.IssueChatToolToken(ctx, chatToolPendingScope)
if err != nil {
return "", nil, err
}
bind := func(sessionID string) error {
if !validChatSessionID(sessionID) {
return errors.New("invalid chat session id")
}
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
return r.store.BindChatToolToken(ctx, token, chatToolSessionScope+sessionID)
}
return r.url(token), bind, nil
}
func (r chatToolRegistry) InstanceURL(harness string) (string, error) {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
token, err := r.store.ChatToolToken(ctx, chatToolInstanceScope+harness)
if err != nil {
return "", err
}
return r.url(token), nil
}
// loopbackBase is the http origin harnesses on this machine use to reach a
// server listening on addr: a wildcard or blank host becomes 127.0.0.1. A
// server bound only to a non-loopback address cannot serve the tools: the
// endpoint answers loopback peers alone.
func loopbackBase(addr string) (string, error) {
host, port, err := net.SplitHostPort(addr)
if err != nil {
return "", err
}
ip := net.ParseIP(host)
switch {
case host == "localhost" || (ip != nil && ip.IsLoopback()):
return "http://" + net.JoinHostPort(host, port), nil
case host == "" || (ip != nil && ip.IsUnspecified()):
return "http://" + net.JoinHostPort("127.0.0.1", port), nil
}
return "", errors.New("the chat tools need a loopback or wildcard listen address, not " + addr)
}
// ConfigureChatTools makes every chat harness Pipelines launches register the
// Pipelines MCP server on the listener at addr. It is called once at startup,
// before any harness starts.
func ConfigureChatTools(store chatToolTokenStore, addr string) error {
base, err := loopbackBase(addr)
if err != nil {
return err
}
chattools.Configure(chatToolRegistry{store: store, base: base})
return nil
}
+5
View File
@@ -161,6 +161,11 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin
}
runs.serveArtifact(w, r)
})
if len(stores) > 0 {
// The Pipelines chat tools' MCP endpoint, for harnesses on this machine.
hub.shown = stores[0]
registerChatTools(mux, newChatToolService(stores[0], stores[0], hub, registry), build.Version)
}
mux.HandleFunc("GET /discovery", serveServerDiscovery)
mux.HandleFunc("GET /files", serveHomeFile)
mux.HandleFunc("POST /files", serveHomeFileUpload)
+63
View File
@@ -0,0 +1,63 @@
import test from "node:test";
import assert from "node:assert/strict";
import { spawn } from "node:child_process";
import { mkdtemp, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import net from "node:net";
import { createServer } from "node:http";
import { once } from "node:events";
// The Pipelines chat tools' MCP endpoint (/mcp/chat/<token>) is for harness
// processes on the server's own machine. The authenticated proxy must never
// forward it, even for a signed-in browser.
const here = fileURLToPath(new URL("..", import.meta.url));
async function freePort() {
const server = net.createServer().listen(0, "127.0.0.1");
await once(server, "listening");
const { port } = server.address();
await new Promise((done) => server.close(done));
return port;
}
test("the proxy does not expose the loopback MCP chat-tools endpoint", async (t) => {
const requests = [];
const upstream = createServer((req, res) => {
requests.push(`${req.method} ${req.url}`);
res.writeHead(200, { "Content-Type": "application/json" }).end('{"jsonrpc":"2.0","id":1,"result":{}}');
}).listen(0, "127.0.0.1");
await once(upstream, "listening");
t.after(() => new Promise((done) => upstream.close(done)));
const dir = await mkdtemp(join(tmpdir(), "serve-mcp-"));
const auth = join(dir, "auth.json");
await writeFile(auth, JSON.stringify({ password: "password-1", secret: "s".repeat(40) }));
const port = await freePort();
const child = spawn(process.execPath, ["serve.mjs", "--port", String(port),
"--pipelines", `127.0.0.1:${upstream.address().port}`], {
cwd: here,
env: { ...process.env, PIPELINES_WEB_AUTH: "", PIPELINES_WEB_AUTH_FILE: auth },
stdio: ["ignore", "pipe", "inherit"],
});
t.after(async () => { const exited = once(child, "exit"); child.kill(); await exited; });
await once(child.stdout, "data");
const base = `http://127.0.0.1:${port}`;
const login = await fetch(base + "/login", {
method: "POST", body: new URLSearchParams({ password: "password-1" }), redirect: "manual",
});
const cookie = login.headers.get("set-cookie").split(";")[0];
const token = "a".repeat(64);
for (const path of [`/mcp/chat/${token}`, "/mcp", "/mcp/", `/%6dcp/chat/${token}`]) {
for (const method of ["GET", "POST"]) {
const reply = await fetch(base + path, {
method,
headers: { Cookie: cookie, "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
body: method === "POST" ? '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' : undefined,
});
const text = await reply.text();
assert.ok(!text.includes('"jsonrpc"'), `${method} ${path} reached the server: ${reply.status} ${text}`);
}
}
assert.deepEqual(requests, []);
});
+15
View File
@@ -585,3 +585,18 @@ test("raw peer HTML and legacy SVG files retain a local sandbox and no cookie au
assert.match(await response.text(), /<script>/);
}
});
test("the relay never forwards a machine's loopback MCP chat-tools endpoint", async (t) => {
const f = await fixture(t);
await f.register("one", { endpoints: [f.remotes[0]], password: "password-one" });
const before = f.observations.length;
for (const method of ["GET", "POST"]) {
const reply = await fetch(f.base + "/peers/one/mcp/chat/" + "a".repeat(64), {
method,
headers: { Cookie: f.cookie, "Content-Type": "application/json" },
body: method === "POST" ? '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' : undefined,
});
assert.equal(reply.status, 404);
}
assert.equal(f.observations.length, before);
});