Merge branch 'worktree-agent-a672970b929d7358c'

# Conflicts:
#	internal/pipeline/store.go
#	internal/server/chat_hub.go
This commit is contained in:
2026-11-09 16:21:55 +00:00
39 changed files with 3581 additions and 11 deletions
@@ -32,6 +32,8 @@ import 'composer_focus_request.dart';
import 'composer_focus_restore.dart';
import 'composer_focus_ring.dart';
import '../ui/sessions/chat_color_palette.dart';
import '../shell/chat_shell_command.dart';
import '../shell/chat_shell_mode_indicator.dart';
/// The composer's placeholder when the chat names no working directory.
const String chatComposerPlaceholder = 'Message the agent';
@@ -74,6 +76,9 @@ double chatComposerBottomMargin([TargetPlatform? platform]) =>
const String chatSendLabel = 'Send';
const String chatStopLabel = 'Stop';
/// The primary control's words while the draft is a `!` shell command.
const String chatRunShellLabel = 'Run command';
/// The attach control's accessible name, verbatim from the web composer.
const String chatAttachLabel = 'Attach file';
@@ -122,6 +127,7 @@ class ChatComposerBar extends StatefulWidget {
this.paste,
this.pasteTarget = true,
this.backgroundTasks,
this.runShell,
this.placeholder = chatComposerPlaceholder,
this.enterSends,
this.images,
@@ -161,6 +167,11 @@ class ChatComposerBar extends StatefulWidget {
final bool pasteTarget;
final Widget? backgroundTasks;
/// Runs a `!` draft's command in the chat's folder (never a prompt);
/// resolves to the server's refusal, or null once it started. Null (no
/// session) reports shell mode as unavailable and sends nothing.
final Future<String?> Function(String command)? runShell;
@override
State<ChatComposerBar> createState() => _ChatComposerBarState();
}
@@ -206,6 +217,9 @@ class _ChatComposerBarState extends State<ChatComposerBar> {
String? _commandOffer;
bool _commandFailed = false;
/// True while a `!` command is being started.
bool _shellStarting = false;
ChatAttachmentPicker get _picker => widget.picker ?? hostChatAttachmentPicker;
ChatClipboardPaste get _paste => widget.paste ?? hostChatClipboardPaste;
@@ -487,6 +501,10 @@ class _ChatComposerBarState extends State<ChatComposerBar> {
_completeCommand(commands[_selectedCommand % commands.length]);
return;
}
if (chatDraftIsShell(widget.composer.draft)) {
unawaited(_runShellDraft());
return;
}
if (chatCommandWord(widget.composer.draft) != null) {
_runSlashDraft();
return;
@@ -494,6 +512,38 @@ class _ChatComposerBarState extends State<ChatComposerBar> {
unawaited(_send());
}
/// A `!` draft runs as a shell command and is never sent to the agent. The
/// draft is cleared once the server started it; a refusal keeps it.
Future<void> _runShellDraft() async {
final draft = widget.composer.draft;
final command = chatShellCommandOf(draft) ?? '';
final run = widget.runShell;
if (run == null) {
_showCommandNotice(
'Shell commands are not available here, so nothing was sent.',
failed: true,
);
return;
}
if (command.isEmpty) {
_showCommandNotice('Type a command after !.', failed: true);
return;
}
if (_shellStarting) return;
setState(() {
_shellStarting = true;
_dismissCommandReport();
});
final refusal = await run(command);
if (!mounted) return;
setState(() => _shellStarting = false);
if (refusal != null) {
_showCommandNotice(refusal, failed: true);
return;
}
if (widget.composer.draft == draft) _consumeCommandDraft();
}
/// Routes a slash draft locally or through the existing Stop controller path.
void _runSlashDraft() {
final draft = widget.composer.draft;
@@ -767,6 +817,8 @@ class _ChatComposerBarState extends State<ChatComposerBar> {
// inside the glass with the field, as one floating composer; only the
// command palette, a separate menu, floats above it.
final extras = <Widget>[
if (chatDraftIsShell(composer.draft))
ChatShellModeIndicator(cupertino: cupertino),
if (!_attachments.isEmpty) _attachmentStrip(context, cupertino),
if (_uploading)
_notice(
@@ -1261,7 +1313,10 @@ class _ChatComposerBarState extends State<ChatComposerBar> {
final composer = widget.composer;
final enabled = stop
? !composer.stopping
: !_uploading && !composer.sending && composer.draft.trim().isNotEmpty;
: !_uploading &&
!_shellStarting &&
!composer.sending &&
composer.draft.trim().isNotEmpty;
void press() {
if (stop) {
unawaited(composer.stop());
@@ -1270,6 +1325,8 @@ class _ChatComposerBarState extends State<ChatComposerBar> {
final commands = _paletteCommands();
if (commands.isNotEmpty) {
_completeCommand(commands[_selectedCommand % commands.length]);
} else if (chatDraftIsShell(composer.draft)) {
unawaited(_runShellDraft());
} else if (chatCommandWord(composer.draft) != null) {
_runSlashDraft();
} else {
@@ -1279,7 +1336,11 @@ class _ChatComposerBarState extends State<ChatComposerBar> {
// Sending while the turn runs uses the server's existing queued-prompt path.
// Stopping is always a separate, explicitly named action.
final label = stop ? chatStopLabel : chatSendLabel;
final label = stop
? chatStopLabel
: chatDraftIsShell(composer.draft)
? chatRunShellLabel
: chatSendLabel;
final key = Key(stop ? 'chat-composer-stop' : 'chat-composer-primary');
if (cupertino) {
return Semantics(
@@ -59,6 +59,11 @@ import 'chat_transcript_cache.dart';
import '../files/files_controller.dart';
import '../files/files_panel.dart';
import '../files/files_preferences.dart';
import '../shell/chat_shell_command.dart';
import '../shell/chat_shell_run.dart';
import '../shell/chat_shell_run_card.dart';
import '../shell/chat_shell_runs_controller.dart';
import '../shell/chat_shell_thread_support.dart';
import 'chat_transcript_scroll_view.dart';
import 'chat_permission_card_model.dart';
import 'chat_permission_group.dart';
@@ -184,6 +189,11 @@ class ChatThreadView extends StatefulWidget {
class _ChatThreadViewState extends State<ChatThreadView> {
late ChatThreadController _controller = _attach();
late ChatComposerController _composer = _attachComposer();
/// The operator's own shell commands in this chat (see `../shell/`).
late ChatShellRunsController _shellRuns = _attachShellRuns();
ChatShellRunsController _attachShellRuns() =>
ChatShellRunsController(widget.gateway, widget.sessionId);
late ChatRowKeys _rowKeys = ChatRowKeys();
final _sentEntrances = ChatSentEntrances();
final _rowWidgets = ChatRowWidgets();
@@ -577,6 +587,8 @@ class _ChatThreadViewState extends State<ChatThreadView> {
}
_controller.dispose();
_composer.dispose();
_shellRuns.dispose();
_shellRuns = _attachShellRuns();
_files.removeListener(_persistFilesPreferences);
_files.dispose();
_files = _newFilesController()..addListener(_persistFilesPreferences);
@@ -613,6 +625,7 @@ class _ChatThreadViewState extends State<ChatThreadView> {
// so no earlier dismissal survives and nothing recorded before the gap is
// painted while the repair runs.
_dismissals.clear();
unawaited(_shellRuns.refresh());
_preGapMessages = _controller.messages;
_reconnecting = true;
final generation = ++_syncGeneration;
@@ -650,6 +663,7 @@ class _ChatThreadViewState extends State<ChatThreadView> {
_scroll.dispose();
_composer.dispose();
_controller.dispose();
_shellRuns.dispose();
_files.removeListener(_persistFilesPreferences);
_files.dispose();
super.dispose();
@@ -965,6 +979,7 @@ class _ChatThreadViewState extends State<ChatThreadView> {
animation: Listenable.merge([
_controller.transcriptChanges,
_composer.deliveries,
_shellRuns.membership,
]),
builder: (context, _) {
final cupertino =
@@ -1020,10 +1035,11 @@ class _ChatThreadViewState extends State<ChatThreadView> {
);
final notices = _dismissals.visible(allNotices);
final compactionNotice = _noticeOf(notices, ChatNoticeKind.compaction);
final rows = [
// The operator's own shell commands sit among the turns by start time.
final rows = withChatShellRunRows([
for (final row in allRows)
if (!_hiddenRunningCompaction(row)) row,
];
], _shellRuns.runs);
// Older pages prepend messages and a live frame can append one, so a
// folded assistant turn's first message id is not a stable identity.
// ChatRowKeys carries a turn's key forward while it still holds any of
@@ -1072,6 +1088,7 @@ class _ChatThreadViewState extends State<ChatThreadView> {
),
chatColor: chatSessionColor(widget.session),
pasteTarget: widget.pasteTarget,
runShell: _shellRuns.start,
backgroundTasks: ChatBackgroundTasks(
key: ValueKey('chat-background-tasks-${widget.sessionId}'),
gateway: widget.gateway,
@@ -1368,7 +1385,11 @@ class _ChatThreadViewState extends State<ChatThreadView> {
: CupertinoIcons.folder,
),
],
moreActions: [?widget.sidebarControl, ...widget.paneControls],
moreActions: [
?widget.sidebarControl,
...widget.paneControls,
chatShellRunMenuAction(onPressed: _runShellFromMenu),
],
controls: [
if (hasModel)
ChatModelControl(
@@ -1395,6 +1416,15 @@ class _ChatThreadViewState extends State<ChatThreadView> {
onChanged: widget.onModeChanged,
);
void _runShellFromMenu() => unawaited(
runChatShellFromMenu(
context,
_shellRuns,
cupertino: chatControlsStyleOf(context) == ChatControlsStyle.cupertino,
showNotice: _showCommandNotice,
),
);
ChatNotice? _noticeOf(List<ChatNotice> notices, ChatNoticeKind kind) {
for (final notice in notices) {
if (notice.kind == kind) return notice;
@@ -1446,6 +1476,12 @@ class _ChatThreadViewState extends State<ChatThreadView> {
return ChatAgentReportCard(row: row, textBuilder: chatMarkdownText);
}
if (kind == 'system_notice') return ChatSystemNoticeLine(row: row);
if (kind == chatShellRunRowKind) {
return ChatShellRunCard(
controller: _shellRuns,
runId: '${row['run_id']}',
);
}
if (kind == 'task_notices') return ChatTaskNoticesGroup(row: row);
if (kind == 'questions') return ChatQuestionsRow(row: row);
if (kind == 'permission' || kind == 'question') {
@@ -1,3 +1,5 @@
import '../shell/chat_shell_command.dart';
/// One command the chat composer offers. [name] is the word after the slash,
/// [usage] is what the operator types (including any argument) and [summary] is
/// the few-word description shown beside it. [takesArgument] is false for the
@@ -113,10 +115,12 @@ String chatCommandArgument(String draft) {
return draft.trimLeft().substring(word.length).trim();
}
/// `/help`'s local listing, in the same order and wording as the palette.
String chatCommandHelpText() => chatCommands
.map((command) => '${command.usage} — ${command.summary}')
.join('\n');
/// `/help`'s local listing, in the same order and wording as the palette,
/// then the `!` shell-command hint.
String chatCommandHelpText() => [
for (final command in chatCommands) '${command.usage} — ${command.summary}',
chatShellHelpLine,
].join('\n');
/// The local no-send report for a slash draft naming no recorded command,
/// verbatim from the web client's unknown-command notice. The report offers the
@@ -0,0 +1,177 @@
import 'dart:async';
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'chat_shell_metrics.dart';
import 'chat_shell_run.dart';
import 'chat_shell_runs_controller.dart';
const String chatShellStopLabel = 'Stop';
const String chatShellStoppingLabel = 'Stopping…';
const String chatShellCopyLabel = 'Copy output';
const String chatShellCopiedLabel = 'Copied';
const String chatShellShareLabel = 'Send to agent';
const String chatShellSharingLabel = 'Sending…';
const String chatShellSharedLabel = 'Sent to agent';
const String chatShellExpandLabel = 'Expand';
const String chatShellCollapseLabel = 'Collapse';
/// The card's host buttons: Stop while running; Copy output, Send to agent
/// once finished; Expand/Collapse for the output area.
class ChatShellCardActions extends StatefulWidget {
const ChatShellCardActions({
super.key,
required this.run,
required this.controller,
required this.cupertino,
required this.expanded,
required this.onToggleExpanded,
});
final ChatShellRun run;
final ChatShellRunsController controller;
final bool cupertino;
final bool expanded;
final VoidCallback onToggleExpanded;
@override
State<ChatShellCardActions> createState() => _ChatShellCardActionsState();
}
class _ChatShellCardActionsState extends State<ChatShellCardActions> {
bool _copied = false;
Timer? _reset;
@override
void dispose() {
_reset?.cancel();
super.dispose();
}
/// Copies everything the server kept, reading it first when this card
/// holds only the newest part.
Future<void> _copy() async {
final full = await widget.controller.loadAll(widget.run.id);
if (full == null) return;
await Clipboard.setData(ClipboardData(text: full.output));
if (!mounted) return;
setState(() => _copied = true);
_reset?.cancel();
_reset = Timer(const Duration(seconds: 2), () {
if (mounted) setState(() => _copied = false);
});
}
@override
Widget build(BuildContext context) {
final run = widget.run;
final controller = widget.controller;
final share = controller.shareState(run.id);
final stopping = controller.stopping(run.id);
return Wrap(
spacing: 8,
runSpacing: 4,
crossAxisAlignment: WrapCrossAlignment.center,
children: [
if (run.running)
_button(
key: const Key('chat-shell-run-stop'),
label: stopping ? chatShellStoppingLabel : chatShellStopLabel,
material: Icons.stop,
cupertino: CupertinoIcons.stop_fill,
destructive: true,
onPressed: stopping
? null
: () => unawaited(controller.stop(run.id)),
),
if (!run.running && run.outputBytes > 0)
_button(
key: const Key('chat-shell-run-copy'),
label: _copied ? chatShellCopiedLabel : chatShellCopyLabel,
material: _copied ? Icons.check : Icons.copy_outlined,
cupertino: _copied
? CupertinoIcons.checkmark
: CupertinoIcons.doc_on_doc,
onPressed: () => unawaited(_copy()),
),
if (!run.running)
_button(
key: const Key('chat-shell-run-share'),
label: switch (share) {
ChatShellShareState.idle => chatShellShareLabel,
ChatShellShareState.sending => chatShellSharingLabel,
ChatShellShareState.sent => chatShellSharedLabel,
},
material: share == ChatShellShareState.sent
? Icons.check
: Icons.send_outlined,
cupertino: share == ChatShellShareState.sent
? CupertinoIcons.checkmark
: CupertinoIcons.paperplane,
onPressed: share == ChatShellShareState.idle
? () => unawaited(controller.share(run.id))
: null,
),
if (widget.expanded || chatShellOutputMayOverflow(run.output))
_button(
key: const Key('chat-shell-run-expand'),
label: widget.expanded
? chatShellCollapseLabel
: chatShellExpandLabel,
material: widget.expanded ? Icons.unfold_less : Icons.unfold_more,
cupertino: widget.expanded
? CupertinoIcons.chevron_up
: CupertinoIcons.chevron_down,
onPressed: widget.onToggleExpanded,
),
],
);
}
Widget _button({
required Key key,
required String label,
required IconData material,
required IconData cupertino,
required VoidCallback? onPressed,
bool destructive = false,
}) {
if (widget.cupertino) {
final color = destructive
? CupertinoColors.systemRed.resolveFrom(context)
: null;
return CupertinoButton(
key: key,
padding: const EdgeInsets.symmetric(horizontal: 8),
onPressed: onPressed,
child: Row(
mainAxisSize: MainAxisSize.min,
children: [
Icon(cupertino, color: onPressed == null ? null : color),
const SizedBox(width: 6),
Text(
label,
style: onPressed == null || color == null
? null
: TextStyle(color: color),
),
],
),
);
}
final style = destructive
? TextButton.styleFrom(
foregroundColor: Theme.of(context).colorScheme.error,
)
: null;
return TextButton.icon(
key: key,
style: style,
onPressed: onPressed,
icon: Icon(material),
label: Text(label),
);
}
}
@@ -0,0 +1,92 @@
import '../../../core/api_gateway.dart';
import '../domain/chat_transcript.dart';
import 'chat_shell_run.dart';
/// The composer's shell prefix: a draft starting with it runs as a command in
/// the chat's directory instead of being sent to the agent.
const String chatShellPrefix = '!';
/// The `/help` line for shell mode.
const String chatShellHelpLine =
'!<command> — Run a shell command in this chat’s folder; '
'the agent does not see it unless you send it';
/// Shell mode's visible label and its explanation beside the composer.
const String chatShellModeLabel = 'Shell';
const String chatShellModeHint =
'Runs in this chat’s folder on its machine. The agent does not see it.';
/// The chat actions menu entry and its dialog.
const String chatShellRunActionLabel = 'Run command…';
const String chatShellRunDialogTitle = 'Run command';
const String chatShellRunDialogConfirm = 'Run';
/// Whether [draft] is in shell mode: its first non-blank character is `!`.
bool chatDraftIsShell(String draft) =>
draft.trimLeft().startsWith(chatShellPrefix);
/// The command a shell-mode draft runs (trimmed, without the `!`), or null
/// when [draft] is not in shell mode. An empty string means only `!` was typed.
String? chatShellCommandOf(String draft) {
if (!chatDraftIsShell(draft)) return null;
return draft.trimLeft().substring(chatShellPrefix.length).trim();
}
/// [rows] with one card row per run, placed by start time among the rows
/// that carry a recorded time. Rows without a time (a just-sent message, the
/// pending reply) keep their place; runs newer than every timed row follow.
List<JsonMap> withChatShellRunRows(
List<JsonMap> rows,
List<ChatShellRun> runs,
) {
if (runs.isEmpty) return rows;
final ordered = [...runs]..sort((a, b) => a.startedAt.compareTo(b.startedAt));
final merged = <JsonMap>[];
var next = 0;
for (final row in rows) {
final time = _rowTime(row);
while (time != null &&
next < ordered.length &&
ordered[next].startedAt < time) {
merged.add(ordered[next++].toRow());
}
merged.add(row);
}
while (next < ordered.length) {
merged.add(ordered[next++].toRow());
}
return merged;
}
int? _rowTime(JsonMap row) {
final created = row['created_at'];
if (created is int && created > 0) return created;
final message = row['message'];
if (message is Map) {
return chatMessageCreatedAt(Map<String, dynamic>.from(message));
}
return null;
}
/// The finished card's status words.
String chatShellStatusLabel(ChatShellRun run) => switch (run.state) {
ChatShellRunState.running => 'Running',
ChatShellRunState.succeeded => 'Exit 0',
ChatShellRunState.stopped => 'Stopped',
ChatShellRunState.interrupted => 'Interrupted',
ChatShellRunState.failed =>
run.signal.isNotEmpty
? 'Killed (${run.signal})'
: run.exitCode != null
? 'Exit ${run.exitCode}'
: 'Failed',
};
/// How long the command ran, as the status chip's tail.
String chatShellDuration(int milliseconds) {
if (milliseconds < 1000) return '$milliseconds ms';
final seconds = milliseconds / 1000;
if (seconds < 60) return '${seconds.toStringAsFixed(1)} s';
final minutes = seconds ~/ 60;
return '${minutes}m ${(seconds % 60).round()}s';
}
@@ -0,0 +1,43 @@
import 'package:flutter/widgets.dart';
/// The one layout bound of a shell command card: how tall its output area
/// may grow. Collapsed it shows about [kChatShellOutputCollapsedLines] lines
/// of the host's (scaled) monospace text; expanded it may take
/// [kChatShellOutputExpandedShare] of the window height. Everything else in
/// the card is content-sized.
const int kChatShellOutputCollapsedLines = 12;
const double kChatShellOutputExpandedShare = 0.6;
/// The monospace line height factor the output text is set at.
const double kChatShellOutputLineHeight = 1.35;
/// Characters of output drawn at once. A command can print far more than a
/// text layout should carry; the card says when it shows only the newest
/// part, and Copy output still copies everything the server kept.
const int kChatShellRenderedOutputLimit = 64 * 1024;
/// Whether [output] may be taller than the collapsed area, so Expand is worth
/// offering. Counted in lines, with long lines counted as wrapping.
bool chatShellOutputMayOverflow(String output) {
var lines = 0;
for (final line in output.split('\n')) {
lines += 1 + line.length ~/ 80;
if (lines > kChatShellOutputCollapsedLines) return true;
}
return false;
}
/// The output area's maximum height for this window, text scale and font.
double chatShellOutputMaxHeight(
BuildContext context, {
required double fontSize,
required bool expanded,
}) {
if (expanded) {
return MediaQuery.sizeOf(context).height * kChatShellOutputExpandedShare;
}
final line =
MediaQuery.textScalerOf(context).scale(fontSize) *
kChatShellOutputLineHeight;
return line * kChatShellOutputCollapsedLines;
}
@@ -0,0 +1,60 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../conversation/chat_card_styles.dart';
import 'chat_shell_command.dart';
/// Shown inside the composer while its draft starts with `!`: the draft is a
/// shell command for this chat's folder, not a message to the agent.
class ChatShellModeIndicator extends StatelessWidget {
const ChatShellModeIndicator({super.key, required this.cupertino});
final bool cupertino;
@override
Widget build(BuildContext context) {
final accent = cupertino
? CupertinoTheme.of(context).primaryColor
: Theme.of(context).colorScheme.primary;
final label = (chatCardBodyStyle(context, cupertino) ?? const TextStyle())
.copyWith(color: accent, fontWeight: FontWeight.w600);
return Semantics(
key: const Key('chat-composer-shell-mode'),
container: true,
liveRegion: true,
label: '$chatShellModeLabel mode. $chatShellModeHint',
child: ExcludeSemantics(
child: Padding(
padding: const EdgeInsets.only(bottom: 8),
child: Wrap(
spacing: 8,
runSpacing: 2,
crossAxisAlignment: WrapCrossAlignment.center,
children: [
Row(
mainAxisSize: MainAxisSize.min,
children: [
Icon(
cupertino
? CupertinoIcons.chevron_left_slash_chevron_right
: Icons.terminal,
color: accent,
size: MediaQuery.textScalerOf(
context,
).scale(label.fontSize ?? 14),
),
const SizedBox(width: 4),
Text(chatShellModeLabel, style: label),
],
),
Text(
chatShellModeHint,
style: chatCardSecondaryStyle(context, cupertino),
),
],
),
),
),
);
}
}
@@ -0,0 +1,119 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../../../ui/text/monospace.dart';
import '../conversation/chat_card_styles.dart';
import 'chat_shell_metrics.dart';
import 'chat_shell_run.dart';
/// The terminal-style output area of one command card: the host's monospace
/// body on a quiet inset surface, scrollable inside a bounded height and
/// anchored at the newest line while the command runs.
class ChatShellOutputView extends StatefulWidget {
const ChatShellOutputView({
super.key,
required this.run,
required this.cupertino,
required this.expanded,
});
final ChatShellRun run;
final bool cupertino;
final bool expanded;
@override
State<ChatShellOutputView> createState() => _ChatShellOutputViewState();
}
class _ChatShellOutputViewState extends State<ChatShellOutputView> {
final ScrollController _scroll = ScrollController();
@override
void dispose() {
_scroll.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
final run = widget.run;
final cupertino = widget.cupertino;
final body = chatCardBodyStyle(context, cupertino) ?? const TextStyle();
final fontSize = (body.fontSize ?? 14) * 0.95;
final style = body.copyWith(
fontFamily: appMonospaceFamily,
fontSize: fontSize,
height: kChatShellOutputLineHeight,
);
final secondary = chatCardSecondaryStyle(context, cupertino);
var text = run.output;
final clipped = text.length > kChatShellRenderedOutputLimit;
if (clipped) {
text = text.substring(text.length - kChatShellRenderedOutputLimit);
}
// The final newline ends the last line; it is not an empty line to draw.
if (text.endsWith('\n')) text = text.substring(0, text.length - 1);
final notes = [
if (run.truncated) 'Earlier output was dropped.',
if (clipped)
'Showing only the newest part; Copy output copies all of it.',
];
return Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
if (notes.isNotEmpty)
Padding(
padding: const EdgeInsets.only(bottom: 4),
child: Text(
notes.join(' '),
key: const Key('chat-shell-output-truncated'),
style: secondary,
),
),
DecoratedBox(
decoration: BoxDecoration(
color: chatCardFillColor(context, cupertino),
borderRadius: BorderRadius.circular(8),
),
child: ConstrainedBox(
constraints: BoxConstraints(
maxHeight: chatShellOutputMaxHeight(
context,
fontSize: fontSize,
expanded: widget.expanded,
),
),
child: _scrollable(
Padding(
padding: const EdgeInsets.all(10),
child: text.isEmpty
? Text(
run.running ? 'No output yet.' : 'No output.',
style: secondary,
)
: Text(
text,
key: const Key('chat-shell-output-text'),
style: style,
),
),
),
),
),
],
);
}
/// A short output sizes the box to itself; a long one scrolls inside it,
/// starting from (and following) the newest line.
Widget _scrollable(Widget child) {
final scroll = SingleChildScrollView(
controller: _scroll,
reverse: true,
child: SizedBox(width: double.infinity, child: child),
);
return widget.cupertino
? CupertinoScrollbar(controller: _scroll, child: scroll)
: Scrollbar(controller: _scroll, child: scroll);
}
}
@@ -0,0 +1,161 @@
import '../../../core/api_gateway.dart';
/// How an operator shell command stands, as the card shows it.
enum ChatShellRunState { running, succeeded, failed, stopped, interrupted }
/// Characters of live output one card keeps; older text is dropped (and said
/// to be) so a flooding command cannot grow the transcript without bound. The
/// server keeps its own 1 MiB tail, which Copy output and Load all read.
const int chatShellLiveOutputLimit = 256 * 1024;
/// One command the operator ran in this chat (`chat_shell_run`), as recorded
/// by the server: never part of the agent's transcript.
class ChatShellRun {
const ChatShellRun({
required this.id,
required this.command,
required this.directory,
required this.status,
required this.startedAt,
this.exitCode,
this.signal = '',
this.error = '',
this.endedAt = 0,
this.durationMs = 0,
this.output = '',
this.outputStart = 0,
this.outputEnd = 0,
this.outputBytes = 0,
this.gap = false,
});
final String id;
final String command;
final String directory;
/// The server's status word: running, exited, stopped, failed, interrupted.
final String status;
final int startedAt;
final int? exitCode;
final String signal;
final String error;
final int endedAt;
final int durationMs;
/// The text held here, covering absolute output bytes from [outputStart]
/// to [outputEnd] (0 when unknown, for a readback).
final String output;
final int outputStart;
final int outputEnd;
final int outputBytes;
/// True when live frames were missed, so [output] is not one contiguous
/// stretch of what the command wrote.
final bool gap;
/// Whether earlier output is not shown here.
bool get truncated => outputStart > 0 || gap;
ChatShellRunState get state => switch (status) {
'running' => ChatShellRunState.running,
'stopped' => ChatShellRunState.stopped,
'interrupted' => ChatShellRunState.interrupted,
'exited' when exitCode == 0 && signal.isEmpty =>
ChatShellRunState.succeeded,
_ => ChatShellRunState.failed,
};
bool get running => state == ChatShellRunState.running;
static ChatShellRun? fromJson(Object? value) {
if (value is! Map) return null;
final id = '${value['id'] ?? ''}'.trim();
if (id.isEmpty) return null;
final output = '${value['output'] ?? ''}';
final start = _int(value['output_start']);
final bytes = _int(value['output_bytes']);
return ChatShellRun(
id: id,
command: '${value['command'] ?? ''}',
directory: '${value['directory'] ?? ''}',
status: '${value['status'] ?? ''}',
startedAt: _int(value['started_at']),
exitCode: value['exit_code'] is num
? (value['exit_code'] as num).toInt()
: null,
signal: '${value['signal'] ?? ''}',
error: '${value['error'] ?? ''}',
endedAt: _int(value['ended_at']),
durationMs: _int(value['duration_ms']),
output: output,
outputStart: start,
// A readback's text runs to the newest byte the server had.
outputEnd: output.isEmpty && start == 0 ? 0 : bytes,
outputBytes: bytes,
);
}
/// This run with a lifecycle frame's facts; the held output stays.
ChatShellRun withLifecycle(ChatShellRun next) => ChatShellRun(
id: id,
command: next.command.isEmpty ? command : next.command,
directory: next.directory.isEmpty ? directory : next.directory,
status: next.status,
startedAt: next.startedAt == 0 ? startedAt : next.startedAt,
exitCode: next.exitCode,
signal: next.signal,
error: next.error,
endedAt: next.endedAt,
durationMs: next.durationMs,
output: output,
outputStart: outputStart,
outputEnd: outputEnd,
outputBytes: next.outputBytes > outputBytes
? next.outputBytes
: outputBytes,
gap: gap,
);
/// This run with one live output chunk covering bytes [offset, end). A
/// chunk this copy already holds is ignored; one after a hole starts a new
/// stretch and marks the gap rather than joining unrelated text.
ChatShellRun withChunk(String text, int offset, int end) {
if (end <= outputEnd) return this;
final contiguous = offset == outputEnd;
var joined = contiguous ? output + text : text;
var dropped = !contiguous && outputEnd > 0;
if (joined.length > chatShellLiveOutputLimit) {
joined = joined.substring(joined.length - chatShellLiveOutputLimit);
dropped = true;
}
return ChatShellRun(
id: id,
command: command,
directory: directory,
status: status,
startedAt: startedAt,
exitCode: exitCode,
signal: signal,
error: error,
endedAt: endedAt,
durationMs: durationMs,
output: joined,
outputStart: contiguous ? outputStart : offset,
outputEnd: end,
outputBytes: end > outputBytes ? end : outputBytes,
gap: gap || dropped || (!contiguous && offset > 0),
);
}
JsonMap toRow() => {
'kind': chatShellRunRowKind,
'key': 'chat-shell-run-$id',
'run_id': id,
'created_at': startedAt,
};
}
/// The transcript row kind of one operator command card.
const String chatShellRunRowKind = 'shell_run';
int _int(Object? value) => value is num ? value.toInt() : 0;
@@ -0,0 +1,149 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../../../ui/text/monospace.dart';
import '../../../ui/theme/app_theme.dart';
import '../conversation/chat_card_styles.dart';
import '../ui/sessions/chat_adaptive.dart';
import 'chat_shell_card_actions.dart';
import 'chat_shell_output_view.dart';
import 'chat_shell_run.dart';
import 'chat_shell_runs_controller.dart';
import 'chat_shell_status.dart';
/// One operator command in the transcript, as a terminal-style card in the
/// reading column: the command and folder, its live output, a spinner and
/// Stop while it runs, then its exit status, Copy output and Send to agent.
///
/// It listens to [controller] itself, so streamed output rebuilds only this
/// card, never the transcript.
class ChatShellRunCard extends StatefulWidget {
const ChatShellRunCard({
super.key,
required this.controller,
required this.runId,
});
final ChatShellRunsController controller;
final String runId;
@override
State<ChatShellRunCard> createState() => _ChatShellRunCardState();
}
class _ChatShellRunCardState extends State<ChatShellRunCard> {
bool _expanded = false;
@override
Widget build(BuildContext context) {
final cupertino =
chatControlsStyleOf(context) == ChatControlsStyle.cupertino;
return ListenableBuilder(
listenable: widget.controller,
builder: (context, _) {
final run = widget.controller.run(widget.runId);
if (run == null) return const SizedBox.shrink();
final body = _body(context, run, cupertino);
return Semantics(
identifier: 'chat-shell-run-card',
container: true,
child: cupertino
? CupertinoListSection.insetGrouped(
backgroundColor: AppColors.groupedBackground,
margin: const EdgeInsets.only(bottom: 12),
children: [
Padding(padding: const EdgeInsets.all(16), child: body),
],
)
: Card(
margin: const EdgeInsets.only(bottom: 12),
child: Padding(
padding: const EdgeInsets.all(16),
child: body,
),
),
);
},
);
}
Widget _body(BuildContext context, ChatShellRun run, bool cupertino) {
final controller = widget.controller;
final error = controller.errorFor(run.id);
final command = (chatCardBodyStyle(context, cupertino) ?? const TextStyle())
.copyWith(fontFamily: appMonospaceFamily, fontWeight: FontWeight.w600);
return Column(
key: ValueKey<String>('chat-shell-run-${run.id}'),
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
Row(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Padding(
padding: const EdgeInsetsDirectional.only(end: 12),
child: Icon(
cupertino
? CupertinoIcons.chevron_left_slash_chevron_right
: Icons.terminal,
color: chatCardSecondaryColor(context, cupertino),
),
),
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
'\$ ${run.command}',
key: const Key('chat-shell-run-command'),
style: command,
),
if (run.directory.isNotEmpty)
Text(
run.directory,
style: chatCardSecondaryStyle(context, cupertino),
),
],
),
),
const SizedBox(width: 8),
ChatShellStatus(run: run, cupertino: cupertino),
],
),
const SizedBox(height: 12),
ChatShellOutputView(
run: run,
cupertino: cupertino,
expanded: _expanded,
),
if (run.error.isNotEmpty && !run.running)
Padding(
padding: const EdgeInsets.only(top: 8),
child: Text(
run.error,
style: chatCardSecondaryStyle(context, cupertino),
),
),
const SizedBox(height: 4),
ChatShellCardActions(
run: run,
controller: controller,
cupertino: cupertino,
expanded: _expanded,
onToggleExpanded: () => setState(() => _expanded = !_expanded),
),
if (error != null)
Semantics(
liveRegion: true,
child: Text(
error,
key: const Key('chat-shell-run-error'),
style:
(chatCardBodyStyle(context, cupertino) ?? const TextStyle())
.copyWith(color: chatCardErrorColor(context, cupertino)),
),
),
],
);
}
}
@@ -0,0 +1,113 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../../../ui/text/monospace.dart';
import 'chat_shell_command.dart';
/// The chat actions menu's "Run command…": a small host dialog with one
/// command field. Returns the trimmed command, or null when cancelled.
Future<String?> showChatShellRunDialog(
BuildContext context, {
required bool cupertino,
}) => cupertino
? showCupertinoDialog<String>(
context: context,
barrierDismissible: true,
builder: (_) => const ChatShellRunDialog(cupertino: true),
)
: showDialog<String>(
context: context,
builder: (_) => const ChatShellRunDialog(cupertino: false),
);
class ChatShellRunDialog extends StatefulWidget {
const ChatShellRunDialog({super.key, required this.cupertino});
final bool cupertino;
@override
State<ChatShellRunDialog> createState() => _ChatShellRunDialogState();
}
class _ChatShellRunDialogState extends State<ChatShellRunDialog> {
final TextEditingController _text = TextEditingController();
@override
void dispose() {
_text.dispose();
super.dispose();
}
void _submit() {
final command = _text.text.trim();
Navigator.pop(context, command.isEmpty ? null : command);
}
void _cancel() => Navigator.pop(context);
@override
Widget build(BuildContext context) {
const mono = TextStyle(fontFamily: appMonospaceFamily);
if (widget.cupertino) {
return CupertinoAlertDialog(
title: const Text(chatShellRunDialogTitle),
content: Column(
children: [
const Text(chatShellModeHint),
const SizedBox(height: 12),
CupertinoTextField(
key: const Key('chat-shell-run-field'),
controller: _text,
autofocus: true,
placeholder: 'Command',
style: mono,
onSubmitted: (_) => _submit(),
),
],
),
actions: [
CupertinoDialogAction(
onPressed: _cancel,
child: const Text('Cancel'),
),
CupertinoDialogAction(
key: const Key('chat-shell-run-confirm'),
isDefaultAction: true,
onPressed: _submit,
child: const Text(chatShellRunDialogConfirm),
),
],
);
}
return AlertDialog(
title: const Text(chatShellRunDialogTitle),
content: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
const Text(chatShellModeHint),
const SizedBox(height: 12),
TextField(
key: const Key('chat-shell-run-field'),
controller: _text,
autofocus: true,
style: mono,
decoration: const InputDecoration(
labelText: 'Command',
prefixText: '\$ ',
),
onSubmitted: (_) => _submit(),
),
],
),
actions: [
TextButton(onPressed: _cancel, child: const Text('Cancel')),
FilledButton(
key: const Key('chat-shell-run-confirm'),
onPressed: _submit,
child: const Text(chatShellRunDialogConfirm),
),
],
);
}
}
@@ -0,0 +1,176 @@
import 'dart:async';
import 'package:flutter/foundation.dart';
import '../../../core/api_gateway.dart';
import '../../../core/error_reason.dart';
import 'chat_shell_run.dart';
import 'chat_shell_runs_repository.dart';
/// Where one run's "Send to agent" stands.
enum ChatShellShareState { idle, sending, sent }
/// One chat's operator shell commands: the recorded runs, their live output
/// from `chat_shell_run_event` frames, and the card actions.
///
/// It notifies on every change (cards listen to it); [membership] notifies
/// only when the set of runs changes, so the transcript is not rebuilt for
/// every output chunk.
class ChatShellRunsController extends ChangeNotifier {
ChatShellRunsController(this.gateway, this.sessionId)
: _repository = ChatShellRunsRepository(gateway) {
_frames = gateway.frames.listen(_onFrame, onError: (_) {});
unawaited(refresh());
}
final ApiGateway gateway;
final String sessionId;
final ChatShellRunsRepository _repository;
StreamSubscription<JsonMap>? _frames;
final Map<String, ChatShellRun> _runs = {};
final ValueNotifier<int> _membership = ValueNotifier<int>(0);
final Set<String> _stopping = {};
final Map<String, ChatShellShareState> _shares = {};
final Map<String, String> _errors = {};
bool _disposed = false;
int _generation = 0;
Listenable get membership => _membership;
List<ChatShellRun> get runs => List.unmodifiable(_runs.values);
ChatShellRun? run(String id) => _runs[id];
bool stopping(String id) => _stopping.contains(id);
ChatShellShareState shareState(String id) =>
_shares[id] ?? ChatShellShareState.idle;
/// The last refused card action of [id], in the server's words.
String? errorFor(String id) => _errors[id];
/// Reads the recorded runs again (open, reconnect). Runs this copy holds
/// with newer output than the readback keep their own copy.
Future<void> refresh() async {
final token = ++_generation;
try {
final listed = await _repository.runs(sessionId);
if (_disposed || token != _generation) return;
for (final run in listed) {
final held = _runs[run.id];
_runs[run.id] = held != null && held.outputEnd > run.outputEnd
? held.withLifecycle(run)
: run;
}
_changed(membership: true);
} catch (_) {
// An older server has no shell commands; the transcript is unchanged.
}
}
/// Starts [command] in the chat's directory. Returns the refusal, or null.
Future<String?> start(String command) async {
try {
final run = await _repository.run(sessionId, command);
if (_disposed) return null;
_runs.putIfAbsent(run.id, () => run);
_changed(membership: true);
return null;
} catch (error) {
return _reason(error);
}
}
Future<void> stop(String id) async {
if (_stopping.contains(id)) return;
_stopping.add(id);
_errors.remove(id);
_changed();
try {
await _repository.stop(sessionId, id);
} catch (error) {
_stopping.remove(id);
_errors[id] = _reason(error);
_changed();
}
}
/// Queues the run's command and output tail as an ordinary prompt.
Future<void> share(String id) async {
if (shareState(id) == ChatShellShareState.sending) return;
_shares[id] = ChatShellShareState.sending;
_errors.remove(id);
_changed();
try {
await _repository.share(sessionId, id);
_shares[id] = ChatShellShareState.sent;
} catch (error) {
_shares.remove(id);
_errors[id] = _reason(error);
}
_changed();
}
/// Every byte the server retained for [id]: what Copy output copies and
/// Show all draws. Null when it cannot be read (the error is recorded).
Future<ChatShellRun?> loadAll(String id) async {
final held = _runs[id];
if (held == null) return null;
if (!held.truncated && !held.running) return held;
try {
final full = await _repository.output(sessionId, id);
if (_disposed) return null;
final latest = _runs[id] ?? held;
// A frame newer than the read keeps the card's own lifecycle facts.
final merged = full.withLifecycle(latest.running ? full : latest);
_runs[id] = merged;
_changed();
return merged;
} catch (error) {
_errors[id] = _reason(error);
_changed();
return null;
}
}
void _onFrame(JsonMap envelope) {
if (_disposed || envelope['type'] != 'chat_shell_run_event') return;
final frame = envelope['chat_shell_run_event'];
if (frame is! Map || frame['session_id'] != sessionId) return;
final id = '${frame['run_id'] ?? ''}';
final record = ChatShellRun.fromJson(frame['run']);
if (record != null) {
final held = _runs[record.id];
_runs[record.id] = held == null ? record : held.withLifecycle(record);
if (!record.running) _stopping.remove(record.id);
_changed(membership: held == null);
return;
}
final held = _runs[id];
if (held == null) {
// Output for a run this copy has not seen yet: read the record.
unawaited(refresh());
return;
}
_runs[id] = held.withChunk(
'${frame['output'] ?? ''}',
(frame['offset'] as num?)?.toInt() ?? 0,
(frame['end'] as num?)?.toInt() ?? 0,
);
_changed();
}
void _changed({bool membership = false}) {
if (_disposed) return;
if (membership) _membership.value++;
notifyListeners();
}
String _reason(Object error) =>
describeErrorReason(error, fallback: 'The server did not answer.');
@override
void dispose() {
_disposed = true;
_generation++;
unawaited(_frames?.cancel());
_membership.dispose();
super.dispose();
}
}
@@ -0,0 +1,53 @@
import '../../../core/api_gateway.dart';
import 'chat_shell_run.dart';
/// Wire adapter for the server's operator shell commands.
class ChatShellRunsRepository {
const ChatShellRunsRepository(this.gateway);
final ApiGateway gateway;
JsonMap _body(String sessionId, {String? command, String? runId}) => {
'chat_shell_run_request': {
'session_id': sessionId,
'command': ?command,
'run_id': ?runId,
},
};
/// Starts [command]; the reply is its running record.
Future<ChatShellRun> run(String sessionId, String command) async => _record(
await gateway.call('chat_shell_run', _body(sessionId, command: command)),
);
Future<void> stop(String sessionId, String runId) =>
gateway.call('chat_shell_stop', _body(sessionId, runId: runId));
/// The session's recorded runs, oldest first, each with its output tail.
Future<List<ChatShellRun>> runs(String sessionId) async {
final reply = await gateway.call('chat_shell_runs', {
'chat_query': {'session_id': sessionId},
});
final value = reply['chat_shell_runs'];
return [
if (value is List)
for (final item in value) ?ChatShellRun.fromJson(item),
];
}
/// One run with the whole output the server retained.
Future<ChatShellRun> output(String sessionId, String runId) async => _record(
await gateway.call('chat_shell_run_output', _body(sessionId, runId: runId)),
);
/// Queues an ordinary prompt carrying the run for the agent.
Future<void> share(String sessionId, String runId) =>
gateway.call('chat_shell_share', _body(sessionId, runId: runId));
ChatShellRun _record(JsonMap reply) {
final run = ChatShellRun.fromJson(reply['chat_shell_run']);
if (run == null) {
throw const FormatException('The server did not return the command.');
}
return run;
}
}
@@ -0,0 +1,74 @@
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../conversation/chat_card_styles.dart';
import 'chat_shell_command.dart';
import 'chat_shell_run.dart';
/// A command's state at the card's top end: the host's activity indicator
/// while it runs, then a status chip (exit code, stopped, interrupted) with
/// how long it ran. The words carry the state; colour only repeats it.
class ChatShellStatus extends StatelessWidget {
const ChatShellStatus({
super.key,
required this.run,
required this.cupertino,
});
final ChatShellRun run;
final bool cupertino;
@override
Widget build(BuildContext context) {
if (run.running) {
return Semantics(
key: const Key('chat-shell-run-running'),
label: chatShellStatusLabel(run),
child: cupertino
? const CupertinoActivityIndicator()
// As tall as the line of text beside it, at any text scale.
: SizedBox.square(
dimension: MediaQuery.textScalerOf(context).scale(20),
child: const CircularProgressIndicator(strokeWidth: 2),
),
);
}
final label = run.durationMs > 0
? '${chatShellStatusLabel(run)} · ${chatShellDuration(run.durationMs)}'
: chatShellStatusLabel(run);
final color = switch (run.state) {
ChatShellRunState.succeeded =>
cupertino
? CupertinoColors.systemGreen.resolveFrom(context)
: Theme.of(context).colorScheme.primary,
ChatShellRunState.failed => chatCardErrorColor(context, cupertino),
_ => chatCardSecondaryColor(context, cupertino),
};
final icon = switch (run.state) {
ChatShellRunState.succeeded =>
cupertino
? CupertinoIcons.checkmark_circle
: Icons.check_circle_outline,
ChatShellRunState.failed =>
cupertino ? CupertinoIcons.xmark_circle : Icons.error_outline,
_ => cupertino ? CupertinoIcons.stop_circle : Icons.stop_circle_outlined,
};
if (cupertino) {
return Row(
key: const Key('chat-shell-run-status'),
mainAxisSize: MainAxisSize.min,
children: [
Icon(icon, color: color, size: 18),
const SizedBox(width: 4),
Text(label, style: chatCardSecondaryStyle(context, true)),
],
);
}
return Chip(
key: const Key('chat-shell-run-status'),
avatar: Icon(icon, color: color),
label: Text(label),
visualDensity: VisualDensity.compact,
);
}
}
@@ -0,0 +1,34 @@
import 'package:flutter/material.dart';
import '../../../ui/adaptive/segmented_bar_overflow.dart';
import 'chat_shell_command.dart';
import 'chat_shell_run_dialog.dart';
import 'chat_shell_runs_controller.dart';
/// The conversation's "Run command…" entry in its actions (More) menu.
Widget chatShellRunMenuAction({required VoidCallback onPressed}) =>
SegmentedOverflowAction(
key: const ValueKey<String>('chat-shell-run-action'),
overflowEntry: SegmentedOverflowEntry(
label: chatShellRunActionLabel,
icon: Icons.terminal,
onPressed: onPressed,
),
child: const SizedBox.shrink(),
);
/// Asks for a command and starts it; a refusal becomes the conversation's
/// own failed notice. Nothing reaches the agent.
Future<void> runChatShellFromMenu(
BuildContext context,
ChatShellRunsController controller, {
required bool cupertino,
required void Function(String text, {bool failed}) showNotice,
}) async {
final command = await showChatShellRunDialog(context, cupertino: cupertino);
if (command == null) return;
final refusal = await controller.start(command);
if (refusal != null) {
showNotice("Couldn't run the command: $refusal", failed: true);
}
}
+195
View File
@@ -0,0 +1,195 @@
# Chat shell commands
The operator can run their own shell commands inside a chat, like Codex's
`!cmd` or Claude Code's `!` bash mode. A command runs in the chat's working
directory on the chat's machine (the Pipelines server that owns the chat). It
is Pipelines' own feature and does not go through the harness. The model never
sees a command or its output unless the operator chooses **Send to agent**.
## Behaviour
- **Composer.** If a draft starts with `!` (leading blanks allowed), the
composer shows a **Shell** indicator: "Runs in this chat's folder on its
machine. The agent does not see it." The primary control's name changes to
"Run command". Enter or the button runs the text after the `!` through
`chat_shell_run`. Such a draft is never sent as a prompt. The draft is
cleared once the server has started the command. If the server refuses it
(limit reached, missing folder), the draft stays and the reason appears as
a failed command notice. A bare `!` reports "Type a command after !." and
sends nothing. `/help` lists `!<command>` after the slash commands.
- **Actions menu.** The conversation's More menu has **Run command…**. It
opens a small Material or Cupertino dialog with a monospace field and the
same hint. A refusal appears as the conversation's failed notice.
- **Transcript card.** Each run is a card in the normal reading column. Runs
are placed by start time among the timed turns, and a run newer than every
turn comes last. The card shows:
- `$ command` in monospace, with the resolved folder under it.
- The host's activity indicator and **Stop** while the command runs.
"Stopping…" shows until the final frame arrives.
- A status chip when it ends: `Exit 0 · 37 ms`, `Exit 1 · 4.2 s`,
`Stopped · 15.2 s`, `Interrupted` or `Killed (signal)`. The words carry
the state and colour only repeats it.
- Live output in the host's monospace on an inset surface. It scrolls
inside a bounded height, stays anchored at the newest line, and has
**Expand**/**Collapse** when it can overflow.
- **Copy output**, which copies the server's whole retained output and
reads it first when the card holds only a tail.
- **Send to agent**: Sending…, then Sent to agent. A second tap does
nothing.
- A line saying when earlier output was dropped.
- **Several clients.** Output and lifecycle frames go to every client
watching the chat (`chat_subscribe` room). A reload or reconnect reads the
runs back with `chat_shell_runs`.
## Wire (internal/protocol/chat_shell_run.go)
| request | body | reply |
| --- | --- | --- |
| `chat_shell_run` | `chat_shell_run_request{session_id, command}` | `chat_shell_run` (the running record) |
| `chat_shell_stop` | `chat_shell_run_request{session_id, run_id}` | `chat_shell_run` |
| `chat_shell_runs` | `chat_query{session_id}` | `chat_shell_runs` (oldest first, ≤64 KiB tail each) |
| `chat_shell_run_output` | `chat_shell_run_request{session_id, run_id}` | `chat_shell_run` with the full retained output |
| `chat_shell_share` | `chat_shell_run_request{session_id, run_id[, operation_id]}` | the ordinary `chat_prompt` ack |
Pushed: `chat_shell_run_event{session_id, run_id, run}` for each lifecycle
change, and `{session_id, run_id, output, offset, end}` for output chunks.
`offset` and `end` are absolute byte offsets. A client whose copy ends before
`offset` marks a gap instead of joining unrelated text.
## Server (internal/server/chat_shell_*.go)
- The server runs `$SHELL -lc <command>`. It uses `/bin/sh` when `$SHELL` is
not an absolute path to an existing file. The command gets the server's
environment, stdin `/dev/null` and its own process group (`Setpgid`), with
stdout and stderr merged into one pipe.
- The working directory is the chat session's recorded directory from the
operator-session registry. Symlinks are resolved, and the directory must
still exist and be a directory. Otherwise the run is refused ("the chat's
directory … is not available").
- Output is sent in batches every 100 ms, at most 64 KiB per frame. If more
is waiting, the newest bytes are sent and the client sees a gap. A
character is never split. Invalid UTF-8 is replaced by U+FFFD on the wire.
- **Stop** sends SIGINT to the group, then SIGKILL after 3 s. After the shell
itself exits, output from its descendants is still read for 1 s, then
anything left in the group is killed. Nothing in the group outlives the run
(use `setsid`/`nohup` from a terminal for daemons).
- **Statuses:**
- `exited` with `exit_code`, or with `signal` if a signal killed it.
- `stopped`: an operator Stop. This status wins over the exit it caused.
- `failed`: a wait error.
- `interrupted`: the server stopped while the command ran. A server
shutdown kills running groups and records them as interrupted. A starting
server also marks any run still recorded as running as `interrupted`
("The server stopped while this command was running.").
- **Persistence:** the `chat_shell_runs` table in the server store. It holds
the command, folder, status, exit code or signal, start and end times,
duration, the retained output tail, its start offset and total bytes. The
row is written at start, every 2 s while the command runs, and at the end.
The 50 newest runs per session are kept, and a running run is never
pruned.
- **Share:** `chat_shell_share` refuses a run that is still running. It then
composes an ordinary prompt: the folder, the command in a fence, how the run
ended, and at most the last 16 KiB of output. Fences are longer than any
backtick run in the content. The prompt goes through the normal admission
path (queue, steer, durable queue). The user turn is echoed to the sender
too, because the sender has no local copy.
## Limits
| limit | value |
| --- | --- |
| concurrent runs per chat | 4 |
| command length | 16 KiB |
| retained/persisted output per run | 1 MiB (tail) |
| output per readback list entry | 64 KiB (tail) |
| live frame | 64 KiB, 100 ms batching |
| shared with the agent | last 16 KiB |
| runs kept per chat | 50 |
| Stop grace before SIGKILL | 3 s |
| client live text per card | 256 K chars; 64 K chars drawn |
## Security
- This is a terminal for the authenticated operator, with the server user's
full privileges. It is reachable only through the existing authenticated
`/connect` websocket. No new HTTP endpoint or listener was added.
- Every request must name a syntactically valid chat session id that the
operator-session registry records. Other requests are refused before
anything runs: unknown ids, pipeline stage sessions, and requests with
malformed ids or no body. Runs are looked up by session and id. Another
session cannot stop, read or share a run, even with its id.
- The command runs on the server that owns the chat, in that chat's
recorded directory, and nowhere else. No remote host is ever named. A
command can still `cd` anywhere the server user may, as in any terminal.
The directory is not restricted to the home folder because chats may
legitimately live outside it (`chat_create` accepts any absolute
directory). Restricting only the starting folder would not contain a
shell, so the honest boundary is the authenticated session.
- Commands and output never reach the model implicitly. Only an explicit
`chat_shell_share` queues a prompt, and it is bounded.
- The process group is killed on Stop, on server shutdown and after the
command exits, so a run cannot leave an orphan holding the server's pipe.
## Files
- Server: `internal/protocol/chat_shell_run.go`,
`internal/pipeline/chat_shell_runs.go`,
`internal/server/chat_shell_{runner,supervise,run_output,run_handlers,share}.go`,
and small hooks in `chat.go`, `chat_hub.go`, `chat_stream.go`
(`admitChatPrompt`, `echoSender`) and `websocket.go`.
- App: `lib/features/chat/shell/`: the model, controller, repository, card,
output view, status, actions, dialog, mode indicator and metrics. The
centralized height bound is `chat_shell_metrics.dart`. There are small
hooks in `conversation/chat_thread_view.dart` (controller, rows, card, menu
entry), `conversation/chat_composer_bar.dart` (`runShell`, Shell indicator,
Run label) and `domain/chat_commands.dart` (`/help` line).
- Capture fixture: `tool/perf/chat_shell_fixture.dart` (`?shell=1` with
`?chats=N`).
## Verification
- `go test ./internal/protocol ./internal/pipeline ./internal/server`:
`ok …/internal/protocol 0.327s`, `ok …/internal/pipeline 8.092s`,
`ok …/internal/server 82.708s`.
- The new tests also pass under `go test -race -run 'ChatShell(Run|Stop|Share|Retains|Shutdown|Output|SharePrompt)'`.
The race failures in that pattern are the pre-existing
`TestChatShellOutputRealHandler*` tests, which race in
`internal/opencode/connection.go`. They are unrelated to these files.
- New Go tests:
- streaming to two watchers plus persistence (`pwd; echo; >&2; exit 3`);
- Stop reaching the child `sleep` in the group;
- the 4-run limit, blank, oversized, unknown-session, malformed and
foreign-stop refusals, and refusing to share a running run;
- a deleted folder refused;
- share echoing the composed prompt to both clients;
- SIGKILL after the grace period for a SIGINT-ignoring command;
- the 1 MiB tail with a 64 KiB list tail, and no frame over 64 KiB;
- shutdown and restart marking runs interrupted;
- UTF-8 boundaries in chunking;
- share fencing;
- store persistence, pruning and interruption.
- `tool/memwatch/full.sh test/features/chat`:
`memwatch: PASS: 1079 passed, 0 failed, 0 skipped; peak 2206 MB; 186s; exit 0 (test/features/chat)`.
- New widget tests in `test/features/chat/shell/`:
- `!` detection, the Shell indicator and Run label, and that Enter runs
without a `chat_prompt`;
- a refusal keeping the draft, and a bare `!`;
- Run command… from the More menu;
- card states (running with streamed output, stopped, failed with Exit 1,
succeeded with Exit 0) in Material and Cupertino;
- Stop, Send to agent (once), Copy output, and a 2× text scale with
Expand.
- `tool/analyze.sh`: `analyze: 0 errors, 8 warnings, 0 infos`. All 8
warnings are pre-existing, in the untouched
`integration_test/discovery_probe_test.dart`.
- Real Chrome captures used `tool/capture` over
`tool/search_selection_probe_entry.dart` with `chats=1&msgs=2&shell=1`.
There were two sets: Material light at 880x1000 and Cupertino dark at
560x1000. Each set has the recorded cards, the Shell indicator with
`!git status --short`, the run started by Enter and finished by its
frames, the More menu with Run command…, and the dialog. The PNGs were
inspected.
Not verified: a live server and browser session running a real command
end to end. The Go websocket tests cover the server with real processes, and
the browser captures use the fixture channel. Mobile devices were not tested.
@@ -256,7 +256,9 @@ void main() {
'/close — Finish this session for every client, keeping its history\n'
'/rename <title> — Rename this session\n'
'/stop — Stop the turn that is running\n'
'/help — List every command',
'/help — List every command\n'
'!<command> — Run a shell command in this chat’s folder; '
'the agent does not see it unless you send it',
),
findsOneWidget,
);
@@ -0,0 +1,103 @@
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/chat/domain/chat_commands.dart';
import 'package:pipelines_app/features/chat/shell/chat_shell_command.dart';
import 'package:pipelines_app/features/chat/shell/chat_shell_run.dart';
ChatShellRun _run(String id, int started, {String status = 'running'}) =>
ChatShellRun(
id: id,
command: 'ls',
directory: '/w',
status: status,
startedAt: started,
);
void main() {
test('a leading ! (after blanks) is shell mode and names the command', () {
expect(chatDraftIsShell('!ls -la'), isTrue);
expect(chatDraftIsShell(' ! git status'), isTrue);
expect(chatDraftIsShell('say !hi'), isFalse);
expect(chatDraftIsShell('/help'), isFalse);
expect(chatShellCommandOf(' ! git status '), 'git status');
expect(chatShellCommandOf('!'), '');
expect(chatShellCommandOf('hello'), isNull);
});
test('/help lists the shell hint after the commands', () {
expect(chatCommandHelpText().split('\n').last, chatShellHelpLine);
});
test('runs are placed among timed rows by start time', () {
final rows = [
{
'kind': 'user',
'key': 'u1',
'message': {'created_at': 100},
},
{'kind': 'assistant', 'key': 'a1', 'created_at': 200},
{'kind': 'user', 'key': 'local', 'message': <String, dynamic>{}},
{'kind': 'assistant', 'key': 'a2', 'created_at': 400},
];
final merged = withChatShellRunRows(rows, [
_run('late', 500),
_run('early', 150),
_run('mid', 300),
]);
expect(merged.map((row) => row['key']), [
'u1',
'chat-shell-run-early',
'a1',
'local',
'chat-shell-run-mid',
'a2',
'chat-shell-run-late',
]);
expect(withChatShellRunRows(rows, const []), same(rows));
});
test('status words follow the recorded outcome', () {
ChatShellRun ended(String status, {int? code, String signal = ''}) =>
ChatShellRun(
id: 'r',
command: 'x',
directory: '/',
status: status,
startedAt: 1,
exitCode: code,
signal: signal,
);
expect(ended('exited', code: 0).state, ChatShellRunState.succeeded);
expect(chatShellStatusLabel(ended('exited', code: 2)), 'Exit 2');
expect(ended('exited', code: 2).state, ChatShellRunState.failed);
expect(
chatShellStatusLabel(ended('exited', signal: 'killed')),
'Killed (killed)',
);
expect(chatShellStatusLabel(ended('stopped')), 'Stopped');
expect(chatShellStatusLabel(ended('interrupted')), 'Interrupted');
expect(chatShellDuration(250), '250 ms');
expect(chatShellDuration(1500), '1.5 s');
expect(chatShellDuration(125000), '2m 5s');
});
test('live chunks join only when contiguous and mark a gap otherwise', () {
var run = _run('r', 1);
run = run.withChunk('abc', 0, 3).withChunk('def', 3, 6);
expect(run.output, 'abcdef');
expect(run.truncated, isFalse);
expect(run.withChunk('abc', 0, 3).output, 'abcdef', reason: 'a repeat');
final gapped = run.withChunk('xyz', 10, 13);
expect(gapped.output, 'xyz');
expect(gapped.truncated, isTrue);
final read = ChatShellRun.fromJson({
'id': 'r',
'status': 'exited',
'exit_code': 0,
'output': 'tail',
'output_start': 6,
'output_bytes': 10,
})!;
expect(read.truncated, isTrue);
expect(read.withChunk('more', 10, 14).output, 'tailmore');
});
}
@@ -0,0 +1,90 @@
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/ui/adaptive/segmented_bar_overflow.dart';
import 'chat_shell_fixtures.dart';
/// A desktop keyboard, where Enter sends.
final _desktop = TargetPlatformVariant.only(TargetPlatform.linux);
void main() {
late ShellGateway gateway;
setUp(() => gateway = ShellGateway());
tearDown(() => gateway.close());
final field = find.byKey(const Key('chat-composer-field'));
final shellMode = find.byKey(const Key('chat-composer-shell-mode'));
testWidgets('a leading ! shows Shell mode and runs instead of sending', (
tester,
) async {
await tester.pumpWidget(shellThread(gateway));
await tester.pump();
await tester.enterText(field, 'hello');
await tester.pump();
expect(shellMode, findsNothing);
await tester.enterText(field, '!git status');
await tester.pump();
expect(shellMode, findsOneWidget);
expect(find.text('Shell'), findsOneWidget);
expect(find.byTooltip('Run command'), findsOneWidget);
await tester.sendKeyEvent(LogicalKeyboardKey.enter);
await tester.pump();
await tester.pump();
expect(gateway.bodies('chat_shell_run').single['command'], 'git status');
expect(gateway.calls.where((c) => c.type == 'chat_prompt'), isEmpty);
expect(shellMode, findsNothing, reason: 'the draft was consumed');
// The started run is drawn as a card at once.
expect(find.text('\$ git status'), findsOneWidget);
}, variant: _desktop);
testWidgets('a refused command keeps the draft and says why', (tester) async {
gateway.refusal = 'this chat already runs 4 commands';
await tester.pumpWidget(shellThread(gateway));
await tester.pump();
await tester.enterText(field, '!sleep 9');
await tester.pump();
await tester.tap(find.byKey(const Key('chat-composer-primary')));
await tester.pump();
await tester.pump();
expect(find.textContaining('already runs 4 commands'), findsOneWidget);
expect(shellMode, findsOneWidget);
expect(gateway.calls.where((c) => c.type == 'chat_prompt'), isEmpty);
});
testWidgets('a bare ! asks for a command and sends nothing', (tester) async {
await tester.pumpWidget(shellThread(gateway));
await tester.pump();
await tester.enterText(field, '!');
await tester.pump();
await tester.tap(find.byKey(const Key('chat-composer-primary')));
await tester.pump();
expect(find.text('Type a command after !.'), findsOneWidget);
expect(gateway.bodies('chat_shell_run'), isEmpty);
});
testWidgets('Run command… in the actions menu runs the typed command', (
tester,
) async {
await tester.pumpWidget(shellThread(gateway));
await tester.pump();
await tester.tap(find.byKey(segmentedMoreKey).hitTestable().first);
await tester.pumpAndSettle();
await tester.tap(find.text('Run command…'));
await tester.pumpAndSettle();
await tester.enterText(
find.byKey(const Key('chat-shell-run-field')),
' ls -la ',
);
await tester.tap(find.byKey(const Key('chat-shell-run-confirm')));
// The running card's indicator never settles; let the dialog close.
await tester.pump();
await tester.pump(const Duration(seconds: 1));
expect(gateway.bodies('chat_shell_run').single['command'], 'ls -la');
expect(find.text('\$ ls -la'), findsOneWidget);
});
}
@@ -0,0 +1,112 @@
import 'dart:async';
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:pipelines_app/core/api_gateway.dart';
import 'package:pipelines_app/features/chat/conversation/chat_draft_store.dart';
import 'package:pipelines_app/features/chat/conversation/chat_thread_view.dart';
import '../conversation/chat_thread_fixtures.dart';
/// A gateway for one open conversation (session `s`) that answers the shell
/// command requests from recorded state and lets a test push their frames.
class ShellGateway implements ApiGateway {
final calls = <({String type, JsonMap fields})>[];
final _frames = StreamController<JsonMap>.broadcast();
List<JsonMap> runs = const [];
String? refusal;
int _serial = 0;
@override
Stream<JsonMap> get frames => _frames.stream;
List<JsonMap> bodies(String type) => [
for (final call in calls)
if (call.type == type)
(call.fields['chat_shell_run_request'] ??
call.fields['chat_prompt'] ??
call.fields['chat_query'])
as JsonMap,
];
@override
Future<JsonMap> call(String type, [JsonMap fields = const {}]) async {
calls.add((type: type, fields: fields));
final body = fields['chat_shell_run_request'] as JsonMap? ?? const {};
switch (type) {
case 'chat_messages':
return chatPage(const []);
case 'chat_shell_runs':
return {'chat_shell_runs': runs};
case 'chat_shell_run':
if (refusal != null) throw StateError(refusal!);
return {
'chat_shell_run': shellRecord(
'run_${++_serial}',
command: '${body['command']}',
),
};
case 'chat_shell_run_output':
return {
'chat_shell_run': runs.firstWhere((r) => r['id'] == body['run_id']),
};
}
return <String, dynamic>{};
}
void emitRun(JsonMap run) => _frames.add({
'type': 'chat_shell_run_event',
'chat_shell_run_event': {
'session_id': 's',
'run_id': run['id'],
'run': run,
},
});
void emitOutput(String id, String text, int offset) => _frames.add({
'type': 'chat_shell_run_event',
'chat_shell_run_event': {
'session_id': 's',
'run_id': id,
'output': text,
'offset': offset,
'end': offset + text.length,
},
});
void close() => _frames.close();
}
JsonMap shellRecord(
String id, {
String command = 'make test',
String status = 'running',
int? exitCode,
String output = '',
int durationMs = 0,
}) => {
'id': id,
'session_id': 's',
'command': command,
'directory': '/home/op/project',
'status': status,
'exit_code': ?exitCode,
'started_at': 1000,
'ended_at': ?(status == 'running' ? null : 1000 + durationMs),
'duration_ms': durationMs,
'output': output,
'output_bytes': output.length,
};
Widget shellThread(ShellGateway gateway, {bool cupertino = false}) {
final thread = ChatThreadView(
gateway: gateway,
sessionId: 's',
syncToken: 0,
onBack: () {},
drafts: MemoryChatDraftStore(),
);
return cupertino
? CupertinoApp(home: CupertinoPageScaffold(child: thread))
: MaterialApp(home: Scaffold(body: thread));
}
@@ -0,0 +1,157 @@
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'chat_shell_fixtures.dart';
void main() {
late ShellGateway gateway;
setUp(() => gateway = ShellGateway());
tearDown(() => gateway.close());
Finder card() => find.bySemanticsIdentifier('chat-shell-run-card');
for (final cupertino in [false, true]) {
final host = cupertino ? 'Cupertino' : 'Material';
testWidgets('$host: a running command streams output and stops', (
tester,
) async {
gateway.runs = [shellRecord('run_a', output: 'line 1\n')];
await tester.pumpWidget(shellThread(gateway, cupertino: cupertino));
await tester.pump();
expect(card(), findsOneWidget);
expect(find.text('\$ make test'), findsOneWidget);
expect(find.byKey(const Key('chat-shell-run-running')), findsOneWidget);
gateway.emitOutput('run_a', 'line 2\n', 7);
await tester.pump();
expect(find.text('line 1\nline 2'), findsOneWidget);
expect(find.byKey(const Key('chat-shell-run-share')), findsNothing);
await tester.tap(find.byKey(const Key('chat-shell-run-stop')));
await tester.pump();
expect(gateway.bodies('chat_shell_stop').single['run_id'], 'run_a');
expect(find.text('Stopping…'), findsOneWidget);
gateway.emitRun(
shellRecord('run_a', status: 'stopped', durationMs: 2400),
);
await tester.pump();
expect(find.byKey(const Key('chat-shell-run-running')), findsNothing);
expect(find.text('Stopped · 2.4 s'), findsOneWidget);
expect(find.byKey(const Key('chat-shell-run-stop')), findsNothing);
// The streamed output stays after the lifecycle frame.
expect(find.text('line 1\nline 2'), findsOneWidget);
});
testWidgets('$host: finished commands show their exit status', (
tester,
) async {
gateway.runs = [
shellRecord(
'run_ok',
command: 'true',
status: 'exited',
exitCode: 0,
output: 'fine\n',
durationMs: 120,
),
shellRecord(
'run_bad',
command: 'false',
status: 'exited',
exitCode: 1,
output: 'broken\n',
durationMs: 3000,
),
];
await tester.pumpWidget(shellThread(gateway, cupertino: cupertino));
await tester.pump();
expect(card(), findsNWidgets(2));
expect(find.text('Exit 0 · 120 ms'), findsOneWidget);
expect(find.text('Exit 1 · 3.0 s'), findsOneWidget);
expect(find.byKey(const Key('chat-shell-run-copy')), findsNWidgets(2));
});
testWidgets('$host: Send to agent shares the run once', (tester) async {
gateway.runs = [
shellRecord('run_a', status: 'exited', exitCode: 0, output: 'ok\n'),
];
await tester.pumpWidget(shellThread(gateway, cupertino: cupertino));
await tester.pump();
expect(gateway.calls.where((c) => c.type == 'chat_prompt'), isEmpty);
await tester.tap(find.byKey(const Key('chat-shell-run-share')));
await tester.pump();
expect(gateway.bodies('chat_shell_share').single['run_id'], 'run_a');
expect(find.text('Sent to agent'), findsOneWidget);
await tester.tap(find.byKey(const Key('chat-shell-run-share')));
await tester.pump();
expect(gateway.bodies('chat_shell_share'), hasLength(1));
});
}
testWidgets('Copy output copies the retained output', (tester) async {
final copied = <String>[];
tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(
SystemChannels.platform,
(call) async {
if (call.method == 'Clipboard.setData') {
copied.add('${(call.arguments as Map)['text']}');
}
return null;
},
);
addTearDown(
() => tester.binding.defaultBinaryMessenger.setMockMethodCallHandler(
SystemChannels.platform,
null,
),
);
gateway.runs = [
shellRecord('run_a', status: 'exited', exitCode: 0, output: 'a\nb\n'),
];
await tester.pumpWidget(shellThread(gateway));
await tester.pump();
await tester.tap(find.byKey(const Key('chat-shell-run-copy')));
await tester.pump();
expect(copied, ['a\nb\n']);
expect(find.text('Copied'), findsOneWidget);
await tester.pump(const Duration(seconds: 3));
});
testWidgets('a large text scale keeps the card readable', (tester) async {
gateway.runs = [
shellRecord(
'run_a',
status: 'exited',
exitCode: 2,
output: List.generate(80, (i) => 'line $i').join('\n'),
),
];
tester.view.physicalSize = const Size(400, 900);
tester.view.devicePixelRatio = 1;
addTearDown(tester.view.reset);
await tester.pumpWidget(
MediaQuery(
data: const MediaQueryData(
size: Size(400, 900),
textScaler: TextScaler.linear(2),
),
child: shellThread(gateway),
),
);
await tester.pump();
expect(tester.takeException(), isNull);
expect(find.textContaining('Exit 2'), findsOneWidget);
final expand = find.byKey(const Key('chat-shell-run-expand'));
await tester.ensureVisible(expand);
await tester.pump();
await tester.tap(expand);
await tester.pump();
expect(find.text('Collapse'), findsOneWidget);
});
}
+185
View File
@@ -0,0 +1,185 @@
// Operator shell commands for the full-app probe (`?shell=1`, with
// `?chats=N`): every fixture chat lists four recorded runs (succeeded, failed,
// stopped and one still running), and chat_shell_run/stop/share answer as the
// server does, with the frames that follow.
import 'package:pipelines_app/core/api_gateway.dart';
bool _enabled = false;
DateTime _base = DateTime.now();
void configureChatShellFixture(Map<String, String> params) {
_enabled = params['shell'] == '1';
_base = DateTime.now().subtract(const Duration(minutes: 3));
}
int _at(int seconds) =>
_base.add(Duration(seconds: seconds)).millisecondsSinceEpoch;
String _session(JsonMap request) {
final body = request['chat_shell_run_request'] ?? request['chat_query'];
return body is Map ? '${body['session_id'] ?? ''}' : '';
}
JsonMap _run(
String session,
String id,
String command,
int started, {
String status = 'exited',
int? exitCode,
int duration = 0,
String output = '',
}) => {
'id': id,
'session_id': session,
'command': command,
'directory': '/Users/operator/src/pipelines',
'status': status,
'exit_code': ?exitCode,
'started_at': _at(started),
if (status != 'running') 'ended_at': _at(started) + duration,
'duration_ms': duration,
'output': output,
'output_bytes': output.length,
};
List<JsonMap> _runs(String session) => [
_run(
session,
'run_status',
'git status --short',
0,
exitCode: 0,
duration: 84,
output:
' M app/lib/features/chat/shell/chat_shell_run_card.dart\n'
'?? app/notes/chat-shell-commands.md\n',
),
_run(
session,
'run_tests',
'go test ./internal/server -run ChatShell',
20,
exitCode: 1,
duration: 4210,
output:
'${[for (final name in _tests) '=== RUN TestChatShell$name\n--- PASS: TestChatShell$name (0.0${name.length % 9}s)\n'].join()}'
'--- FAIL: TestChatShellStopInterruptsTheGroup (0.21s)\n'
' chat_shell_run_test.go:112: stopped record = {Status:exited}\n'
'FAIL\n'
'FAIL\tgit.a-wan.net/alan/pipelines/internal/server\t0.611s\n'
'FAIL\n',
),
_run(
session,
'run_watch',
'tail -f /var/log/system.log',
40,
status: 'stopped',
duration: 15200,
output: 'Nov 9 15:58:01 host kernel[0]: wake reason: EC.LidOpen\n',
),
_run(
session,
'run_build',
'flutter build web --target tool/search_selection_probe_entry.dart',
60,
status: 'running',
output:
'Compiling lib/main.dart for the Web...\n'
'Font asset "CupertinoIcons.ttf" was tree-shaken.\n',
),
];
JsonMap? chatShellReply(JsonMap request) {
if (!_enabled) return null;
final id = request['id'];
final session = _session(request);
final body = request['chat_shell_run_request'];
final runId = body is Map ? '${body['run_id'] ?? ''}' : '';
switch ('${request['type']}') {
case 'chat_shell_runs':
return {
'id': id,
'type': 'chat_shell_runs',
'chat_shell_runs': _runs(session),
};
case 'chat_shell_run':
return {
'id': id,
'type': 'chat_shell_run',
'chat_shell_run': _run(
session,
'run_new',
body is Map ? '${body['command'] ?? ''}' : '',
180,
status: 'running',
),
};
case 'chat_shell_stop':
return {'id': id, 'type': 'chat_shell_stop'};
case 'chat_shell_run_output':
return {
'id': id,
'type': 'chat_shell_run_output',
'chat_shell_run': _runs(session).firstWhere(
(run) => run['id'] == runId,
orElse: () => _runs(session).first,
),
};
case 'chat_shell_share':
return {'id': id, 'type': 'chat_prompt'};
}
return null;
}
/// The frames the server pushes after a run starts or is stopped.
List<JsonMap> chatShellFollowUps(JsonMap request) {
if (!_enabled) return const [];
final session = _session(request);
JsonMap frame(JsonMap body) => {
'type': 'chat_shell_run_event',
'chat_shell_run_event': {'session_id': session, ...body},
};
switch ('${request['type']}') {
case 'chat_shell_run':
const text = 'hello from the fixture shell\n';
final body = request['chat_shell_run_request'];
return [
frame({
'run_id': 'run_new',
'output': text,
'offset': 0,
'end': text.length,
}),
frame({
'run_id': 'run_new',
'run': _run(
session,
'run_new',
body is Map ? '${body['command'] ?? ''}' : '',
180,
exitCode: 0,
duration: 37,
),
}),
];
case 'chat_shell_stop':
final run = _runs(session).last
..['status'] = 'stopped'
..['duration_ms'] = 9100;
return [
frame({'run_id': run['id'], 'run': run}),
];
}
return const [];
}
const _tests = [
'RunStreamsToEveryWatcherAndPersists',
'RunLimitsAndRefusals',
'ShareQueuesAnOrdinaryPrompt',
'RetainsBoundedTail',
'ShutdownAndRestartInterrupt',
'OutputKeepsCharactersWhole',
];
+8
View File
@@ -16,6 +16,8 @@
// `?msgs=`, `?rich=1`, `?older=1`, `?live=N` vary the chat transcripts for
// scroll captures (tool/perf/chat_scroll_fixture.dart).
// `?question=` pushes an agent question (tool/perf/chat_question_fixture.dart).
// `?shell=1` lists operator shell commands in every chat
// (tool/perf/chat_shell_fixture.dart).
// `/new` in a fixture chat moves it to a fresh, empty session
// (tool/perf/chat_new_session_fixture.dart).
import 'package:pipelines_app/core/api_gateway.dart';
@@ -23,6 +25,7 @@ import 'package:pipelines_app/core/api_gateway.dart';
import 'chat_new_session_fixture.dart';
import 'chat_turn_diff_fixture.dart';
import 'chat_question_fixture.dart';
import 'chat_shell_fixture.dart';
import 'chat_scroll_fixture.dart';
Map<String, String> _params = const {};
@@ -36,6 +39,7 @@ void configurePerfFixture(Map<String, String> params) {
);
configureChatScrollFixture(params);
configureChatQuestionFixture(params);
configureChatShellFixture(params);
}
int get _hits => int.tryParse(_params['hits'] ?? '') ?? 0;
@@ -127,6 +131,8 @@ bool get _scrollVariety => ['msgs', 'rich', 'older'].any(_params.containsKey);
List<JsonMap> perfChatFollowUps(JsonMap request) {
final answered = chatQuestionFollowUps(request);
if (answered.isNotEmpty) return answered;
final shell = chatShellFollowUps(request);
if (shell.isNotEmpty) return shell;
final quota = _params['quota'];
if (_chats == 0 || quota == null || request['type'] != 'chat_subscribe') {
return const [];
@@ -227,6 +233,8 @@ JsonMap? perfChatReply(JsonMap request) {
if (_chats == 0) return null;
final question = chatQuestionReply(request);
if (question != null) return question;
final shell = chatShellReply(request);
if (shell != null) return shell;
final id = request['id'];
switch ('${request['type']}') {
case 'chat_sessions':
+123
View File
@@ -0,0 +1,123 @@
package pipeline
import (
"context"
"database/sql"
"errors"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// initChatShellRuns creates the additive table of operator shell commands. A
// run belongs to its chat session and is Pipelines' own record: it is never
// part of the harness transcript. Output holds only the retained tail.
func (s *Store) initChatShellRuns() error {
_, err := s.db.Exec(`CREATE TABLE IF NOT EXISTS chat_shell_runs (
id TEXT PRIMARY KEY,
session_id TEXT NOT NULL,
command TEXT NOT NULL,
directory TEXT NOT NULL,
status TEXT NOT NULL,
exit_code INTEGER,
signal TEXT NOT NULL DEFAULT '',
error TEXT NOT NULL DEFAULT '',
started_at INTEGER NOT NULL,
ended_at INTEGER NOT NULL DEFAULT 0,
duration_ms INTEGER NOT NULL DEFAULT 0,
output TEXT NOT NULL DEFAULT '',
output_start INTEGER NOT NULL DEFAULT 0,
output_bytes INTEGER NOT NULL DEFAULT 0);
CREATE INDEX IF NOT EXISTS chat_shell_runs_session ON chat_shell_runs(session_id, started_at);`)
return err
}
// SaveChatShellRun inserts or replaces one run. Inserting a new run prunes the
// session's oldest finished runs beyond keep (keep <= 0 keeps everything).
func (s *Store) SaveChatShellRun(ctx context.Context, run protocol.ChatShellRunRecord, keep int) error {
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
return err
}
defer tx.Rollback()
var exit any
if run.ExitCode != nil {
exit = *run.ExitCode
}
if _, err := tx.ExecContext(ctx, `INSERT INTO chat_shell_runs
(id, session_id, command, directory, status, exit_code, signal, error, started_at, ended_at, duration_ms, output, output_start, output_bytes)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(id) DO UPDATE SET status = excluded.status, exit_code = excluded.exit_code, signal = excluded.signal,
error = excluded.error, ended_at = excluded.ended_at, duration_ms = excluded.duration_ms, output = excluded.output,
output_start = excluded.output_start, output_bytes = excluded.output_bytes`,
run.ID, run.SessionID, run.Command, run.Directory, run.Status, exit, run.Signal, run.Error,
run.StartedAt, run.EndedAt, run.DurationMS, run.Output, run.OutputStart, run.OutputBytes); err != nil {
return err
}
if keep > 0 {
if _, err := tx.ExecContext(ctx, `DELETE FROM chat_shell_runs WHERE session_id = ? AND status != ? AND id NOT IN
(SELECT id FROM chat_shell_runs WHERE session_id = ? ORDER BY started_at DESC, id DESC LIMIT ?)`,
run.SessionID, protocol.ChatShellRunRunning, run.SessionID, keep); err != nil {
return err
}
}
return tx.Commit()
}
// ChatShellRuns lists one session's runs, oldest first.
func (s *Store) ChatShellRuns(ctx context.Context, sessionID string) ([]protocol.ChatShellRunRecord, error) {
rows, err := s.db.QueryContext(ctx, chatShellRunSelect+` WHERE session_id = ? ORDER BY started_at, id`, sessionID)
if err != nil {
return nil, err
}
defer rows.Close()
var runs []protocol.ChatShellRunRecord
for rows.Next() {
run, err := scanChatShellRun(rows)
if err != nil {
return nil, err
}
runs = append(runs, run)
}
return runs, rows.Err()
}
// ChatShellRun returns one run of sessionID; found is false when that session
// has no run with this id.
func (s *Store) ChatShellRun(ctx context.Context, sessionID, id string) (protocol.ChatShellRunRecord, bool, error) {
run, err := scanChatShellRun(s.db.QueryRowContext(ctx, chatShellRunSelect+` WHERE session_id = ? AND id = ?`, sessionID, id))
if errors.Is(err, sql.ErrNoRows) {
return protocol.ChatShellRunRecord{}, false, nil
}
return run, err == nil, err
}
// InterruptChatShellRuns marks every run still recorded as running as
// interrupted at endedAt. A starting server calls it: no process of a previous
// server is still owned by anyone.
func (s *Store) InterruptChatShellRuns(ctx context.Context, endedAt int64, reason string) (int64, error) {
result, err := s.db.ExecContext(ctx, `UPDATE chat_shell_runs SET status = ?, error = ?, ended_at = ?,
duration_ms = CASE WHEN ? > started_at THEN ? - started_at ELSE 0 END WHERE status = ?`,
protocol.ChatShellRunInterrupted, reason, endedAt, endedAt, endedAt, protocol.ChatShellRunRunning)
if err != nil {
return 0, err
}
return result.RowsAffected()
}
const chatShellRunSelect = `SELECT id, session_id, command, directory, status, exit_code, signal, error, started_at, ended_at, duration_ms, output, output_start, output_bytes FROM chat_shell_runs`
func scanChatShellRun(row chatQueueScanner) (protocol.ChatShellRunRecord, error) {
var run protocol.ChatShellRunRecord
var exit sql.NullInt64
err := row.Scan(&run.ID, &run.SessionID, &run.Command, &run.Directory, &run.Status, &exit, &run.Signal, &run.Error,
&run.StartedAt, &run.EndedAt, &run.DurationMS, &run.Output, &run.OutputStart, &run.OutputBytes)
if err != nil {
return protocol.ChatShellRunRecord{}, err
}
if exit.Valid {
code := int(exit.Int64)
run.ExitCode = &code
}
run.Truncated = run.OutputStart > 0
return run, nil
}
+66
View File
@@ -0,0 +1,66 @@
package pipeline
import (
"context"
"fmt"
"path/filepath"
"testing"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
func TestChatShellRunsPersistPruneAndInterrupt(t *testing.T) {
ctx := context.Background()
path := filepath.Join(t.TempDir(), "shell.db")
store, err := Open(path)
if err != nil {
t.Fatal(err)
}
running := protocol.ChatShellRunRecord{ID: "run_live", SessionID: "ses_1", Command: "sleep 9", Directory: "/w", Status: protocol.ChatShellRunRunning, StartedAt: 1000}
if err := store.SaveChatShellRun(ctx, running, 2); err != nil {
t.Fatal(err)
}
code := 3
for i := 0; i < 3; i++ {
run := protocol.ChatShellRunRecord{ID: fmt.Sprintf("run_%d", i), SessionID: "ses_1", Command: "false", Directory: "/w", Status: protocol.ChatShellRunExited, ExitCode: &code, StartedAt: int64(2000 + i), EndedAt: int64(2500 + i), Output: "tail", OutputStart: 10, OutputBytes: 14}
if err := store.SaveChatShellRun(ctx, run, 2); err != nil {
t.Fatal(err)
}
}
if err := store.SaveChatShellRun(ctx, protocol.ChatShellRunRecord{ID: "other", SessionID: "ses_2", Command: "ls", Directory: "/w", Status: protocol.ChatShellRunExited, StartedAt: 1}, 2); err != nil {
t.Fatal(err)
}
runs, err := store.ChatShellRuns(ctx, "ses_1")
if err != nil {
t.Fatal(err)
}
// The running run is never pruned; keep counts the newest runs, so only
// the finished ones outside the newest two are dropped.
ids := []string{}
for _, run := range runs {
ids = append(ids, run.ID)
}
if fmt.Sprint(ids) != "[run_live run_1 run_2]" {
t.Fatalf("runs = %v", ids)
}
if got := runs[2]; got.ExitCode == nil || *got.ExitCode != 3 || !got.Truncated || got.Output != "tail" || got.OutputBytes != 14 {
t.Fatalf("finished run = %+v", got)
}
store.Close()
store, err = Open(path)
if err != nil {
t.Fatal(err)
}
defer store.Close()
n, err := store.InterruptChatShellRuns(ctx, 4000, "server restarted")
if err != nil || n != 1 {
t.Fatalf("interrupt = %d, %v", n, err)
}
live, found, err := store.ChatShellRun(ctx, "ses_1", "run_live")
if err != nil || !found || live.Status != protocol.ChatShellRunInterrupted || live.EndedAt != 4000 || live.DurationMS != 3000 || live.ExitCode != nil {
t.Fatalf("interrupted run = %+v found=%v err=%v", live, found, err)
}
if _, found, _ := store.ChatShellRun(ctx, "ses_2", "run_live"); found {
t.Fatal("a run was readable through another session")
}
}
+4
View File
@@ -105,6 +105,10 @@ CREATE TABLE IF NOT EXISTS submissions (id INTEGER PRIMARY KEY, name TEXT NOT NU
db.Close()
return nil, err
}
if err := s.initChatShellRuns(); err != nil {
db.Close()
return nil, err
}
if err := s.initAppNotifications(); err != nil {
db.Close()
return nil, err
+107
View File
@@ -0,0 +1,107 @@
package protocol
// Operator shell commands: commands the operator runs themselves inside one
// chat's working directory (the chat's `!cmd`). They are owned by Pipelines,
// not by the chat harness: the model never sees a command or its output unless
// the operator explicitly shares it (chat_shell_share), which queues an
// ordinary prompt.
const (
// ChatShellRun starts one command. The body is ChatShellRunRequest
// (session_id, command); the reply carries the new run in ChatShellRun.
ChatShellRun = "chat_shell_run"
// ChatShellStop interrupts one running command (SIGINT to its process
// group, then SIGKILL after a grace period). The body is
// ChatShellRunRequest (session_id, run_id); the reply echoes the run.
ChatShellStop = "chat_shell_stop"
// ChatShellRuns lists the session's recorded runs, oldest first, each with
// at most ChatShellRunListOutput bytes of its retained output tail. The
// body is ChatQuery.
ChatShellRuns = "chat_shell_runs"
// ChatShellRunOutput reads one run with its whole retained output (at most
// ChatShellRunRetained bytes). The body is ChatShellRunRequest.
ChatShellRunOutput = "chat_shell_run_output"
// ChatShellShare queues an ordinary prompt carrying the run's command, exit
// status and bounded output tail. The body is ChatShellRunRequest; the
// reply is the chat_prompt acknowledgement.
ChatShellShare = "chat_shell_share"
// ChatShellRunEvent is pushed to every client watching the session: a
// lifecycle change (Run set) or an output chunk (Output set).
ChatShellRunEvent = "chat_shell_run_event"
)
// ChatShellRunRecord status values. Running is the only non-final status.
const (
ChatShellRunRunning = "running"
ChatShellRunExited = "exited"
ChatShellRunStopped = "stopped"
ChatShellRunFailed = "failed"
ChatShellRunInterrupted = "interrupted"
)
// Bounds of operator shell commands.
const (
// ChatShellRunCommandLimit bounds one command line.
ChatShellRunCommandLimit = 16 << 10
// ChatShellRunRetained is the retained (and persisted) output tail of one
// run: older output is dropped and the record says so.
ChatShellRunRetained = 1 << 20
// ChatShellRunListOutput bounds the output tail each run carries in a
// chat_shell_runs list, so a long history stays one small frame.
ChatShellRunListOutput = 64 << 10
// ChatShellRunChunkLimit bounds one live output frame.
ChatShellRunChunkLimit = 64 << 10
// ChatShellRunShareOutput bounds the output tail shared with the agent.
ChatShellRunShareOutput = 16 << 10
// ChatShellRunConcurrent bounds the commands one session runs at once.
ChatShellRunConcurrent = 4
// ChatShellRunHistory bounds the finished runs kept per session.
ChatShellRunHistory = 50
)
// ChatShellRunRequest names one session and either a new command or a run.
// OperationID is the optional retry identity of chat_shell_share's prompt.
type ChatShellRunRequest struct {
SessionID string `json:"session_id"`
Command string `json:"command,omitempty"`
RunID string `json:"run_id,omitempty"`
OperationID string `json:"operation_id,omitempty"`
}
// ChatShellRunRecord is one operator command and what it produced. Output is
// the retained text starting at absolute byte OutputStart of everything the
// command wrote (stdout and stderr merged); OutputBytes is that total. A record
// with OutputStart > 0 dropped its beginning. Times are epoch milliseconds.
// ExitCode is set once the process exited with a code; a signal-terminated
// or never-started command has none.
type ChatShellRunRecord struct {
ID string `json:"id"`
SessionID string `json:"session_id"`
Command string `json:"command"`
Directory string `json:"directory"`
Status string `json:"status"`
ExitCode *int `json:"exit_code,omitempty"`
Signal string `json:"signal,omitempty"`
Error string `json:"error,omitempty"`
StartedAt int64 `json:"started_at"`
EndedAt int64 `json:"ended_at,omitempty"`
DurationMS int64 `json:"duration_ms,omitempty"`
Output string `json:"output,omitempty"`
OutputStart int64 `json:"output_start,omitempty"`
OutputBytes int64 `json:"output_bytes,omitempty"`
// Truncated is true when Output does not hold everything the command
// wrote (OutputStart > 0).
Truncated bool `json:"truncated,omitempty"`
}
// ChatShellRunEventFrame is one live change to a run. A lifecycle frame sets
// Run (without output); an output frame sets Output covering absolute bytes
// [Offset, End). A client whose own copy ends before Offset missed output and
// shows that gap rather than joining unrelated text.
type ChatShellRunEventFrame struct {
SessionID string `json:"session_id"`
RunID string `json:"run_id"`
Run *ChatShellRunRecord `json:"run,omitempty"`
Output string `json:"output,omitempty"`
Offset int64 `json:"offset,omitempty"`
End int64 `json:"end,omitempty"`
}
+6
View File
@@ -267,6 +267,12 @@ type Message struct {
ChatShellOutputQuery *ChatShellOutputQuery `json:"chat_shell_output_query,omitempty"`
ChatShells []ChatShell `json:"chat_shells,omitempty"`
ChatShellOutput *ChatShellOutputPage `json:"chat_shell_output,omitempty"`
// Operator shell commands (chat_shell_run.go): the request body, one run,
// a session's runs and the pushed live change.
ChatShellRunRequest *ChatShellRunRequest `json:"chat_shell_run_request,omitempty"`
ChatShellRun *ChatShellRunRecord `json:"chat_shell_run,omitempty"`
ChatShellRuns []ChatShellRunRecord `json:"chat_shell_runs,omitempty"`
ChatShellRunEvent *ChatShellRunEventFrame `json:"chat_shell_run_event,omitempty"`
// ListDirectory is the list_directory body and DirectoryListing its reply:
// the home-restricted folder picker listing (see directories.go).
ListDirectory *DirectoryListRequest `json:"list_directory,omitempty"`
+3
View File
@@ -255,6 +255,9 @@ func handleChat(ctx context.Context, request protocol.Message, broker chatBroker
case protocol.ChatShellOutput:
handleChatShellOutput(ctx, request, broker, registry, write)
return true
case protocol.ChatShellRun, protocol.ChatShellStop, protocol.ChatShellRuns, protocol.ChatShellRunOutput, protocol.ChatShellShare:
handleChatShellRunRequest(ctx, request, broker, hub, registry, clientID, write)
return true
case protocol.ChatAttachmentImage:
handleChatAttachmentImage(request, broker, write)
return true
+3
View File
@@ -83,6 +83,9 @@ type chatHub struct {
finishingTurns map[string]*chatTurnCapture
turnDiffWG sync.WaitGroup
turnDiffDirectory func(context.Context, string) string
// shellRuns runs the operator's own shell commands (chat_shell_runner.go);
// nil refuses them.
shellRuns *chatShellRunner
}
// chatPart is the retained form of one part. Text and reasoning deltas append to
+141
View File
@@ -0,0 +1,141 @@
package server
import (
"context"
"errors"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// handleChatShellRunRequest answers the operator shell-command requests. Every
// one names an operator chat session the registry records: the command runs
// only in that chat's own directory on this server's machine, and a run is
// only readable or stoppable through the session that started it.
func handleChatShellRunRequest(ctx context.Context, request protocol.Message, broker chatBroker, hub *chatHub, registry operatorRegistry, clientID string, write func(protocol.Message) error) {
fail := func(err error) { _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) }
runner := hub.shellRunner()
if runner == nil {
fail(errors.New("shell commands are not configured on this server"))
return
}
var sessionID string
body := request.ChatShellRunRequest
switch {
case request.Type == protocol.ChatShellRuns && request.ChatQuery != nil:
sessionID = request.ChatQuery.SessionID
case body != nil:
sessionID = body.SessionID
}
if !validChatSessionID(sessionID) {
fail(errors.New("a valid chat session id is required"))
return
}
if registry == nil {
fail(errors.New("operator session registry is not configured on this server"))
return
}
session, found, err := registry.OperatorSession(ctx, sessionID)
if err != nil {
fail(err)
return
}
if !found {
fail(errors.New("operator session is not available"))
return
}
if request.Type != protocol.ChatShellRuns && body == nil {
fail(errors.New("a chat shell request body is required"))
return
}
switch request.Type {
case protocol.ChatShellRun:
record, err := runner.Start(ctx, sessionID, session.Directory, body.Command)
if err != nil {
fail(err)
return
}
_ = write(protocol.Message{Type: protocol.ChatShellRun, ID: request.ID, ChatShellRun: &record})
case protocol.ChatShellStop:
record, err := runner.Stop(sessionID, body.RunID)
if err != nil {
fail(err)
return
}
_ = write(protocol.Message{Type: protocol.ChatShellStop, ID: request.ID, ChatShellRun: &record})
case protocol.ChatShellRuns:
runs, err := runner.List(ctx, sessionID)
if err != nil {
fail(err)
return
}
_ = write(protocol.Message{Type: protocol.ChatShellRuns, ID: request.ID, ChatShellRuns: runs})
case protocol.ChatShellRunOutput:
record, err := runner.Read(ctx, sessionID, body.RunID)
if err != nil {
fail(err)
return
}
_ = write(protocol.Message{Type: protocol.ChatShellRunOutput, ID: request.ID, ChatShellRun: &record})
case protocol.ChatShellShare:
record, err := runner.Read(ctx, sessionID, body.RunID)
if err != nil {
fail(err)
return
}
if record.Status == protocol.ChatShellRunRunning {
fail(errors.New("wait for the command to finish before sending it to the agent"))
return
}
prompt := protocol.Message{Type: protocol.ChatPrompt, ID: request.ID, ChatPrompt: &protocol.ChatPromptRequest{
SessionID: sessionID, Text: chatShellSharePrompt(record), OperationID: body.OperationID,
}}
admitChatPrompt(ctx, prompt, broker, hub, registry, clientID, write, true)
}
}
// List is the session's recorded runs, oldest first. A running run carries
// its live output rather than the last periodic save; every run carries at
// most protocol.ChatShellRunListOutput bytes of its tail.
func (r *chatShellRunner) List(ctx context.Context, sessionID string) ([]protocol.ChatShellRunRecord, error) {
runs, err := r.store.ChatShellRuns(ctx, sessionID)
if err != nil {
return nil, err
}
for i, run := range runs {
if p := r.activeProcess(sessionID, run.ID); p != nil {
runs[i] = p.snapshot(protocol.ChatShellRunListOutput)
continue
}
runs[i] = chatShellRecordTail(run, protocol.ChatShellRunListOutput)
}
return runs, nil
}
// Read is one run of sessionID with its whole retained output.
func (r *chatShellRunner) Read(ctx context.Context, sessionID, runID string) (protocol.ChatShellRunRecord, error) {
if p := r.activeProcess(sessionID, runID); p != nil {
return p.snapshot(protocol.ChatShellRunRetained), nil
}
record, found, err := r.store.ChatShellRun(ctx, sessionID, runID)
if err != nil {
return protocol.ChatShellRunRecord{}, err
}
if !found {
return protocol.ChatShellRunRecord{}, errors.New("this chat has no such command")
}
return record, nil
}
// chatShellRecordTail trims a stored record's output to its last max bytes.
func chatShellRecordTail(record protocol.ChatShellRunRecord, max int) protocol.ChatShellRunRecord {
if len(record.Output) <= max {
return record
}
out := newChatShellOutput(len(record.Output))
out.write([]byte(record.Output))
text, from := out.tail(max)
record.Output = text
record.OutputStart += from
record.Truncated = true
return record
}
+96
View File
@@ -0,0 +1,96 @@
package server
import (
"strings"
"unicode/utf8"
)
// chatShellOutput is the bounded tail of one operator command's merged output.
// Offsets are absolute bytes of everything the command wrote, so a client can
// tell a continuation from a gap. The buffer may grow to twice its limit before
// compacting, which keeps a flooding command from copying the tail per write.
type chatShellOutput struct {
limit int
data []byte
start int64
total int64
emitted int64
}
func newChatShellOutput(limit int) *chatShellOutput {
return &chatShellOutput{limit: limit}
}
func (o *chatShellOutput) write(p []byte) {
o.data = append(o.data, p...)
o.total += int64(len(p))
if len(o.data) <= 2*o.limit {
return
}
cut := runeStartAfter(o.data, len(o.data)-o.limit)
o.data = append([]byte(nil), o.data[cut:]...)
o.start += int64(cut)
}
// tail returns at most max retained bytes ending at the newest byte, starting
// on a character boundary, with the absolute offset of its first byte.
func (o *chatShellOutput) tail(max int) (string, int64) {
from := 0
if len(o.data) > max {
from = runeStartAfter(o.data, len(o.data)-max)
}
return validChatShellText(o.data[from:]), o.start + int64(from)
}
// pending returns the output not yet emitted, at most max bytes (the newest
// ones when more is waiting: the skipped bytes are a visible gap to clients).
// An incomplete trailing character is held back unless final is set.
func (o *chatShellOutput) pending(max int, final bool) (text string, offset, end int64, ok bool) {
from := o.emitted
if from < o.start {
from = o.start
}
available := o.data[from-o.start:]
if !final {
available = available[:completeUTF8Prefix(available)]
}
if len(available) == 0 {
return "", 0, 0, false
}
end = from + int64(len(available))
if len(available) > max {
skip := runeStartAfter(available, len(available)-max)
available = available[skip:]
from += int64(skip)
}
o.emitted = end
return validChatShellText(available), from, end, true
}
// runeStartAfter moves index forward (at most three bytes) to the first byte
// that starts a character, so a cut never splits one.
func runeStartAfter(data []byte, index int) int {
for step := 0; step < utf8.UTFMax-1 && index < len(data) && !utf8.RuneStart(data[index]); step++ {
index++
}
return index
}
// completeUTF8Prefix is the length of data without a trailing partial
// character that a later read may complete.
func completeUTF8Prefix(data []byte) int {
for back := 1; back <= utf8.UTFMax-1 && back <= len(data); back++ {
if utf8.RuneStart(data[len(data)-back]) {
if !utf8.FullRune(data[len(data)-back:]) {
return len(data) - back
}
break
}
}
return len(data)
}
// validChatShellText keeps binary output representable in a JSON frame.
func validChatShellText(data []byte) string {
return strings.ToValidUTF8(string(data), "�")
}
+190
View File
@@ -0,0 +1,190 @@
package server
import (
"context"
"os"
"path/filepath"
"strings"
"testing"
"github.com/coder/websocket"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// shellChat is one server with a recorded operator session whose directory is
// a fresh temporary folder, and two connections watching that session.
func shellChat(t *testing.T) (context.Context, []*websocket.Conn, string) {
t.Helper()
store := newOperatorStore(t)
broker := scriptedChat()
broker.block = true
ctx, _, conns := dialChatConns(t, Options{Chat: broker, OperatorRegistry: store}, 2)
dir, err := filepath.EvalSymlinks(t.TempDir())
if err != nil {
t.Fatal(err)
}
if err := store.RecordOperatorSession(ctx, "ses_1", dir, "Shell", protocol.ChatSessionTagOperator); err != nil {
t.Fatal(err)
}
for i, conn := range conns {
writeChat(t, ctx, conn, protocol.Message{Type: protocol.ChatSubscribe, ID: "sub", ChatSubscribe: &protocol.ChatQuery{SessionID: "ses_1"}})
if got := readShellFrame(t, ctx, conn, func(m protocol.Message) bool { return m.ID == "sub" }); got.Type != protocol.ChatSubscribe {
t.Fatalf("subscribe %d = %+v", i, got)
}
}
return ctx, conns, dir
}
func readShellFrame(t *testing.T, ctx context.Context, conn *websocket.Conn, match func(protocol.Message) bool) protocol.Message {
t.Helper()
for {
var message protocol.Message
if err := readTestFrame(ctx, conn, &message); err != nil {
t.Fatal(err)
}
if match(message) {
return message
}
}
}
func shellRequest(kind, id, runID, command string) protocol.Message {
return protocol.Message{Type: kind, ID: id, ChatShellRunRequest: &protocol.ChatShellRunRequest{SessionID: "ses_1", Command: command, RunID: runID}}
}
// runShell starts command and returns its running record.
func runShell(t *testing.T, ctx context.Context, conn *websocket.Conn, id, command string) protocol.ChatShellRunRecord {
t.Helper()
writeChat(t, ctx, conn, shellRequest(protocol.ChatShellRun, id, "", command))
reply := readShellFrame(t, ctx, conn, func(m protocol.Message) bool { return m.ID == id })
if reply.Type != protocol.ChatShellRun || reply.ChatShellRun == nil || reply.ChatShellRun.Status != protocol.ChatShellRunRunning {
t.Fatalf("chat_shell_run reply = %+v", reply)
}
return *reply.ChatShellRun
}
// finishedShell reads conn's frames until runID's final lifecycle frame and
// returns it with the live output joined from its output frames.
func finishedShell(t *testing.T, ctx context.Context, conn *websocket.Conn, runID string) (protocol.ChatShellRunRecord, string) {
t.Helper()
var output strings.Builder
var end int64
for {
frame := readShellFrame(t, ctx, conn, func(m protocol.Message) bool {
return m.Type == protocol.ChatShellRunEvent && m.ChatShellRunEvent != nil && m.ChatShellRunEvent.RunID == runID
}).ChatShellRunEvent
if frame.Run == nil {
if frame.Offset != end {
t.Fatalf("output frame at %d after %d", frame.Offset, end)
}
output.WriteString(frame.Output)
end = frame.End
continue
}
if frame.Run.Status != protocol.ChatShellRunRunning {
return *frame.Run, output.String()
}
}
}
func TestChatShellRunStreamsToEveryWatcherAndPersists(t *testing.T) {
ctx, conns, dir := shellChat(t)
run := runShell(t, ctx, conns[0], "r1", `pwd; echo out; echo err >&2; exit 3`)
if run.Directory != dir || run.Command == "" || run.ID == "" {
t.Fatalf("running record = %+v", run)
}
for _, conn := range conns {
final, output := finishedShell(t, ctx, conn, run.ID)
if final.Status != protocol.ChatShellRunExited || final.ExitCode == nil || *final.ExitCode != 3 || final.EndedAt < final.StartedAt {
t.Fatalf("final record = %+v", final)
}
if output != dir+"\nout\nerr\n" {
t.Fatalf("streamed output = %q", output)
}
}
writeChat(t, ctx, conns[1], protocol.Message{Type: protocol.ChatShellRuns, ID: "list", ChatQuery: &protocol.ChatQuery{SessionID: "ses_1"}})
list := readShellFrame(t, ctx, conns[1], func(m protocol.Message) bool { return m.ID == "list" })
if len(list.ChatShellRuns) != 1 || list.ChatShellRuns[0].Output != dir+"\nout\nerr\n" || *list.ChatShellRuns[0].ExitCode != 3 {
t.Fatalf("persisted runs = %+v", list)
}
}
func TestChatShellStopInterruptsTheGroup(t *testing.T) {
ctx, conns, _ := shellChat(t)
// The child sleep is in the shell's group, so the stop reaches it too.
run := runShell(t, ctx, conns[0], "r1", `echo started; sleep 30; echo never`)
writeChat(t, ctx, conns[0], shellRequest(protocol.ChatShellStop, "stop", run.ID, ""))
if reply := readShellFrame(t, ctx, conns[0], func(m protocol.Message) bool { return m.ID == "stop" }); reply.Type != protocol.ChatShellStop {
t.Fatalf("stop reply = %+v", reply)
}
final, output := finishedShell(t, ctx, conns[1], run.ID)
if final.Status != protocol.ChatShellRunStopped || strings.Contains(output, "never") || final.DurationMS > 10_000 {
t.Fatalf("stopped record = %+v output=%q", final, output)
}
writeChat(t, ctx, conns[0], shellRequest(protocol.ChatShellStop, "again", run.ID, ""))
if reply := readShellFrame(t, ctx, conns[0], func(m protocol.Message) bool { return m.ID == "again" }); reply.Type != protocol.Error {
t.Fatalf("stopping a finished run = %+v", reply)
}
}
func TestChatShellRunLimitsAndRefusals(t *testing.T) {
ctx, conns, dir := shellChat(t)
var runs []protocol.ChatShellRunRecord
for i := 0; i < protocol.ChatShellRunConcurrent; i++ {
runs = append(runs, runShell(t, ctx, conns[0], "r"+string(rune('a'+i)), "sleep 30"))
}
refusals := []protocol.Message{
shellRequest(protocol.ChatShellRun, "fifth", "", "sleep 30"),
shellRequest(protocol.ChatShellRun, "blank", "", " "),
shellRequest(protocol.ChatShellRun, "huge", "", strings.Repeat("x", protocol.ChatShellRunCommandLimit+1)),
{Type: protocol.ChatShellRun, ID: "nobody", ChatShellRunRequest: &protocol.ChatShellRunRequest{SessionID: "ses_unknown", Command: "true"}},
{Type: protocol.ChatShellRun, ID: "badid", ChatShellRunRequest: &protocol.ChatShellRunRequest{SessionID: "../ses", Command: "true"}},
{Type: protocol.ChatShellRun, ID: "nobody-body"},
{Type: protocol.ChatShellStop, ID: "foreign", ChatShellRunRequest: &protocol.ChatShellRunRequest{SessionID: "ses_unknown", RunID: runs[0].ID}},
shellRequest(protocol.ChatShellShare, "share-running", runs[0].ID, ""),
}
for _, request := range refusals {
writeChat(t, ctx, conns[0], request)
if reply := readShellFrame(t, ctx, conns[0], func(m protocol.Message) bool { return m.ID == request.ID }); reply.Type != protocol.Error {
t.Fatalf("%s was not refused: %+v", request.ID, reply)
}
}
for _, run := range runs {
writeChat(t, ctx, conns[0], shellRequest(protocol.ChatShellStop, "stop-"+run.ID, run.ID, ""))
readShellFrame(t, ctx, conns[0], func(m protocol.Message) bool { return m.ID == "stop-"+run.ID })
}
for range runs {
readShellFrame(t, ctx, conns[1], func(m protocol.Message) bool {
return m.Type == protocol.ChatShellRunEvent && m.ChatShellRunEvent.Run != nil && m.ChatShellRunEvent.Run.Status == protocol.ChatShellRunStopped
})
}
// A deleted working directory is refused rather than run somewhere else.
if err := os.RemoveAll(dir); err != nil {
t.Fatal(err)
}
writeChat(t, ctx, conns[0], shellRequest(protocol.ChatShellRun, "gone", "", "true"))
if reply := readShellFrame(t, ctx, conns[0], func(m protocol.Message) bool { return m.ID == "gone" }); reply.Type != protocol.Error || !strings.Contains(reply.Error, "not available") {
t.Fatalf("missing directory = %+v", reply)
}
}
func TestChatShellShareQueuesAnOrdinaryPrompt(t *testing.T) {
ctx, conns, dir := shellChat(t)
run := runShell(t, ctx, conns[0], "r1", "echo shared-output")
finishedShell(t, ctx, conns[0], run.ID)
writeChat(t, ctx, conns[0], shellRequest(protocol.ChatShellShare, "share", run.ID, ""))
// The composed prompt is echoed to the sender too: it has no local copy.
for _, conn := range conns {
user := readShellFrame(t, ctx, conn, func(m protocol.Message) bool {
return m.Type == protocol.ChatEvent && m.ChatEvent != nil && m.ChatEvent.Kind == protocol.ChatEventUser
}).ChatEvent
text := user.Part.Text
if !strings.Contains(text, "$ echo shared-output") || !strings.Contains(text, "shared-output\n```") || !strings.Contains(text, dir) || !strings.Contains(text, "exited with status 0") {
t.Fatalf("shared prompt = %q", text)
}
}
if reply := readShellFrame(t, ctx, conns[0], func(m protocol.Message) bool { return m.ID == "share" }); reply.Type != protocol.ChatPrompt {
t.Fatalf("share reply = %+v", reply)
}
}
+256
View File
@@ -0,0 +1,256 @@
package server
import (
"context"
"crypto/rand"
"encoding/hex"
"errors"
"fmt"
"os"
"os/exec"
"path/filepath"
"strings"
"sync"
"syscall"
"time"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// chatShellRunStore persists operator shell runs; *pipeline.Store implements it.
type chatShellRunStore interface {
SaveChatShellRun(ctx context.Context, run protocol.ChatShellRunRecord, keep int) error
ChatShellRuns(ctx context.Context, sessionID string) ([]protocol.ChatShellRunRecord, error)
ChatShellRun(ctx context.Context, sessionID, id string) (protocol.ChatShellRunRecord, bool, error)
InterruptChatShellRuns(ctx context.Context, endedAt int64, reason string) (int64, error)
}
const (
chatShellInterruptedReason = "The server stopped while this command was running."
// chatShellDrain is how long output is still read after the command itself
// exited, for descendants that keep the pipe open; the group is then killed.
chatShellDrain = time.Second
)
// chatShellRunner owns the operator's own commands: each runs `$SHELL -lc` in
// its chat's directory, in its own process group, with stdout and stderr
// merged into one bounded tail that is streamed to the session's watchers and
// persisted as Pipelines' record of the run.
type chatShellRunner struct {
base context.Context
store chatShellRunStore
publish func(sessionID string, frame protocol.ChatShellRunEventFrame)
now func() time.Time
shell func() string
// grace separates Stop's SIGINT from its SIGKILL; flush batches live output
// frames; persist is the interval a running run's output is saved at.
grace time.Duration
flush time.Duration
persist time.Duration
mu sync.Mutex
active map[string]*chatShellProcess
wg sync.WaitGroup
}
type chatShellProcess struct {
mu sync.Mutex
record protocol.ChatShellRunRecord
out *chatShellOutput
cmd *exec.Cmd
stopped bool
done chan struct{}
}
func newChatShellRunner(base context.Context, store chatShellRunStore, publish func(string, protocol.ChatShellRunEventFrame)) *chatShellRunner {
return &chatShellRunner{
base: base, store: store, publish: publish, now: time.Now, shell: chatShellProgram,
grace: 3 * time.Second, flush: 100 * time.Millisecond, persist: 2 * time.Second,
active: map[string]*chatShellProcess{},
}
}
// chatShellProgram is the operator's login shell, or /bin/sh without one.
func chatShellProgram() string {
if shell := os.Getenv("SHELL"); filepath.IsAbs(shell) {
if info, err := os.Stat(shell); err == nil && !info.IsDir() {
return shell
}
}
return "/bin/sh"
}
// recover marks runs a previous server process left running as interrupted:
// their processes died with it (or are no longer owned by anyone).
func (r *chatShellRunner) recover(ctx context.Context) {
if r.store == nil {
return
}
_, _ = r.store.InterruptChatShellRuns(ctx, r.now().UnixMilli(), chatShellInterruptedReason)
}
// resolveChatShellDirectory requires the chat's recorded directory to still be
// an existing directory and returns its symlink-free path.
func resolveChatShellDirectory(directory string) (string, error) {
directory = strings.TrimSpace(directory)
if directory == "" || !filepath.IsAbs(directory) {
return "", errors.New("this chat has no absolute working directory to run commands in")
}
real, err := filepath.EvalSymlinks(directory)
if err != nil {
return "", fmt.Errorf("the chat's directory %s is not available: %v", directory, err)
}
info, err := os.Stat(real)
if err != nil || !info.IsDir() {
return "", fmt.Errorf("the chat's directory %s is not a directory", directory)
}
return real, nil
}
func newChatShellRunID() (string, error) {
var b [12]byte
if _, err := rand.Read(b[:]); err != nil {
return "", err
}
return "run_" + hex.EncodeToString(b[:]), nil
}
// Start launches command for sessionID in directory and returns its running
// record. Validation and start failures are returned without a record.
func (r *chatShellRunner) Start(ctx context.Context, sessionID, directory, command string) (protocol.ChatShellRunRecord, error) {
if r.store == nil {
return protocol.ChatShellRunRecord{}, errors.New("shell commands need the server's store, which is not configured")
}
if strings.TrimSpace(command) == "" {
return protocol.ChatShellRunRecord{}, errors.New("a nonempty command is required")
}
if len(command) > protocol.ChatShellRunCommandLimit {
return protocol.ChatShellRunRecord{}, fmt.Errorf("the command exceeds %d KiB", protocol.ChatShellRunCommandLimit>>10)
}
dir, err := resolveChatShellDirectory(directory)
if err != nil {
return protocol.ChatShellRunRecord{}, err
}
id, err := newChatShellRunID()
if err != nil {
return protocol.ChatShellRunRecord{}, err
}
r.mu.Lock()
defer r.mu.Unlock()
if r.base.Err() != nil {
return protocol.ChatShellRunRecord{}, errors.New("the server is stopping")
}
running := 0
for _, p := range r.active {
if p.record.SessionID == sessionID {
running++
}
}
if running >= protocol.ChatShellRunConcurrent {
return protocol.ChatShellRunRecord{}, fmt.Errorf("this chat already runs %d commands; stop one or wait for it to finish", running)
}
reader, writer, err := os.Pipe()
if err != nil {
return protocol.ChatShellRunRecord{}, err
}
cmd := exec.Command(r.shell(), "-lc", command)
cmd.Dir = dir
cmd.Env = os.Environ()
cmd.Stdout, cmd.Stderr = writer, writer
cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
if err := cmd.Start(); err != nil {
reader.Close()
writer.Close()
return protocol.ChatShellRunRecord{}, fmt.Errorf("could not start the command: %v", err)
}
writer.Close()
record := protocol.ChatShellRunRecord{ID: id, SessionID: sessionID, Command: command, Directory: dir, Status: protocol.ChatShellRunRunning, StartedAt: r.now().UnixMilli()}
p := &chatShellProcess{record: record, out: newChatShellOutput(protocol.ChatShellRunRetained), cmd: cmd, done: make(chan struct{})}
if err := r.store.SaveChatShellRun(ctx, record, protocol.ChatShellRunHistory); err != nil {
_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
reader.Close()
_ = cmd.Wait()
return protocol.ChatShellRunRecord{}, fmt.Errorf("could not record the command: %v", err)
}
r.active[id] = p
r.wg.Add(1)
go r.supervise(p, reader)
r.publishRun(record)
return record, nil
}
// Stop interrupts a running command's whole process group, then kills it
// after the grace period. It returns the run's current record.
func (r *chatShellRunner) Stop(sessionID, runID string) (protocol.ChatShellRunRecord, error) {
r.mu.Lock()
p := r.active[runID]
r.mu.Unlock()
if p == nil || p.record.SessionID != sessionID {
return protocol.ChatShellRunRecord{}, errors.New("this command is not running")
}
p.mu.Lock()
p.stopped = true
record := p.record
p.mu.Unlock()
pid := p.cmd.Process.Pid
_ = syscall.Kill(-pid, syscall.SIGINT)
go func() {
select {
case <-p.done:
case <-time.After(r.grace):
_ = syscall.Kill(-pid, syscall.SIGKILL)
}
}()
return record, nil
}
// Wait blocks until every supervised command has finished (tests, shutdown).
func (r *chatShellRunner) Wait() { r.wg.Wait() }
func (r *chatShellRunner) activeProcess(sessionID, runID string) *chatShellProcess {
r.mu.Lock()
defer r.mu.Unlock()
if p := r.active[runID]; p != nil && p.record.SessionID == sessionID {
return p
}
return nil
}
// snapshot is the process's current record carrying at most max output bytes.
func (p *chatShellProcess) snapshot(max int) protocol.ChatShellRunRecord {
p.mu.Lock()
defer p.mu.Unlock()
record := p.record
record.Output, record.OutputStart = p.out.tail(max)
record.OutputBytes = p.out.total
record.Truncated = record.OutputStart > 0
return record
}
func (r *chatShellRunner) publishRun(record protocol.ChatShellRunRecord) {
if r.publish == nil {
return
}
record.Output = ""
r.publish(record.SessionID, protocol.ChatShellRunEventFrame{SessionID: record.SessionID, RunID: record.ID, Run: &record})
}
func (h *chatHub) shellRunner() *chatShellRunner {
if h == nil {
return nil
}
return h.shellRuns
}
// startShellRunner gives the hub its operator command runner over store,
// streaming to the session's room, after interrupting runs a previous server
// process left recorded as running. A nil store leaves commands refused.
func (h *chatHub) startShellRunner(ctx context.Context, store chatShellRunStore) {
if store == nil {
return
}
h.shellRuns = newChatShellRunner(ctx, store, func(sessionID string, frame protocol.ChatShellRunEventFrame) {
h.fanout(sessionID, protocol.Message{Type: protocol.ChatShellRunEvent, ChatShellRunEvent: &frame}, "")
})
h.shellRuns.recover(ctx)
}
+143
View File
@@ -0,0 +1,143 @@
package server
import (
"context"
"strings"
"sync"
"testing"
"time"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// shellFrames records every frame a test runner publishes.
type shellFrames struct {
mu sync.Mutex
frames []protocol.ChatShellRunEventFrame
}
func (f *shellFrames) add(_ string, frame protocol.ChatShellRunEventFrame) {
f.mu.Lock()
f.frames = append(f.frames, frame)
f.mu.Unlock()
}
func (f *shellFrames) final(runID string) *protocol.ChatShellRunRecord {
f.mu.Lock()
defer f.mu.Unlock()
for _, frame := range f.frames {
if frame.RunID == runID && frame.Run != nil && frame.Run.Status != protocol.ChatShellRunRunning {
return frame.Run
}
}
return nil
}
func testShellRunner(t *testing.T, ctx context.Context) (*chatShellRunner, *shellFrames) {
t.Helper()
frames := &shellFrames{}
runner := newChatShellRunner(ctx, newOperatorStore(t), frames.add)
runner.grace = 200 * time.Millisecond
runner.flush = 10 * time.Millisecond
return runner, frames
}
func TestChatShellStopKillsAfterGrace(t *testing.T) {
runner, frames := testShellRunner(t, context.Background())
run, err := runner.Start(context.Background(), "ses_1", t.TempDir(), `trap "" INT; echo ready; while :; do sleep 0.05; done`)
if err != nil {
t.Fatal(err)
}
time.Sleep(150 * time.Millisecond)
if _, err := runner.Stop("ses_2", run.ID); err == nil {
t.Fatal("another session stopped this run")
}
if _, err := runner.Stop("ses_1", run.ID); err != nil {
t.Fatal(err)
}
runner.Wait()
final := frames.final(run.ID)
if final == nil || final.Status != protocol.ChatShellRunStopped || final.Signal != "killed" || final.DurationMS < 200 {
t.Fatalf("final = %+v", final)
}
}
func TestChatShellRetainsBoundedTail(t *testing.T) {
runner, frames := testShellRunner(t, context.Background())
total := protocol.ChatShellRunRetained + 200_000
run, err := runner.Start(context.Background(), "ses_1", t.TempDir(), `head -c 1248576 /dev/zero | tr '\0' a; printf END`)
if err != nil {
t.Fatal(err)
}
runner.Wait()
stored, err := runner.Read(context.Background(), "ses_1", run.ID)
if err != nil {
t.Fatal(err)
}
if stored.OutputBytes != int64(total+3) || len(stored.Output) != protocol.ChatShellRunRetained || !stored.Truncated || stored.OutputStart != stored.OutputBytes-int64(protocol.ChatShellRunRetained) || !strings.HasSuffix(stored.Output, "aEND") {
t.Fatalf("stored = bytes %d len %d start %d truncated %v", stored.OutputBytes, len(stored.Output), stored.OutputStart, stored.Truncated)
}
list, err := runner.List(context.Background(), "ses_1")
if err != nil || len(list) != 1 || len(list[0].Output) != protocol.ChatShellRunListOutput || list[0].OutputStart != stored.OutputBytes-protocol.ChatShellRunListOutput {
t.Fatalf("list = %d runs, err %v", len(list), err)
}
frames.mu.Lock()
defer frames.mu.Unlock()
for _, frame := range frames.frames {
if len(frame.Output) > protocol.ChatShellRunChunkLimit {
t.Fatalf("an output frame carried %d bytes", len(frame.Output))
}
}
}
func TestChatShellShutdownAndRestartInterrupt(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
runner, frames := testShellRunner(t, ctx)
run, err := runner.Start(context.Background(), "ses_1", t.TempDir(), "sleep 30")
if err != nil {
t.Fatal(err)
}
cancel()
runner.Wait()
if final := frames.final(run.ID); final == nil || final.Status != protocol.ChatShellRunInterrupted {
t.Fatalf("shutdown final = %+v", final)
}
if _, err := runner.Start(context.Background(), "ses_1", t.TempDir(), "true"); err == nil {
t.Fatal("a stopping server started a command")
}
// A record a crashed process left running is interrupted on start.
store := runner.store
if err := store.SaveChatShellRun(context.Background(), protocol.ChatShellRunRecord{ID: "run_left", SessionID: "ses_1", Command: "sleep 1", Directory: "/", Status: protocol.ChatShellRunRunning, StartedAt: 1}, 0); err != nil {
t.Fatal(err)
}
next := newChatShellRunner(context.Background(), store, nil)
next.recover(context.Background())
left, err := next.Read(context.Background(), "ses_1", "run_left")
if err != nil || left.Status != protocol.ChatShellRunInterrupted || left.Error != chatShellInterruptedReason {
t.Fatalf("recovered = %+v, %v", left, err)
}
}
func TestChatShellOutputKeepsCharactersWhole(t *testing.T) {
out := newChatShellOutput(4)
out.write([]byte("ab\xc3"))
if text, offset, end, ok := out.pending(64, false); !ok || text != "ab" || offset != 0 || end != 2 {
t.Fatalf("partial character emitted: %q %d %d", text, offset, end)
}
out.write([]byte("\xa9cdefghij"))
text, offset, end, ok := out.pending(3, false)
if !ok || text != "hij" || offset != 9 || end != 12 {
t.Fatalf("bounded chunk = %q %d %d", text, offset, end)
}
if tail, start := out.tail(6); tail != "ghij" || start != 8 {
t.Fatalf("tail = %q at %d", tail, start)
}
}
func TestChatShellSharePromptFencesOutput(t *testing.T) {
code := 1
prompt := chatShellSharePrompt(protocol.ChatShellRunRecord{Command: "cat notes.md", Directory: "/w", Status: protocol.ChatShellRunExited, ExitCode: &code, DurationMS: 1500, Output: "```go\nx\n```\n", OutputBytes: 13})
if !strings.Contains(prompt, "````text\n```go\nx\n```\n````") || !strings.Contains(prompt, "exited with status 1 after 1.5s") {
t.Fatalf("prompt = %q", prompt)
}
}
+78
View File
@@ -0,0 +1,78 @@
package server
import (
"fmt"
"strings"
"time"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// chatShellSharePrompt is the ordinary prompt chat_shell_share queues: the
// command, where it ran, how it ended and a bounded tail of its output. It is
// the only path by which an operator command reaches the agent.
func chatShellSharePrompt(record protocol.ChatShellRunRecord) string {
output := chatShellRecordTail(record, protocol.ChatShellRunShareOutput)
var b strings.Builder
fmt.Fprintf(&b, "I ran this shell command in %s:\n\n", record.Directory)
fence := chatShellFence(record.Command)
fmt.Fprintf(&b, "%ssh\n$ %s\n%s\n\n", fence, record.Command, fence)
fmt.Fprintf(&b, "%s.\n\n", chatShellOutcome(record))
if output.Output == "" {
b.WriteString("It printed no output.")
return b.String()
}
if output.OutputStart > 0 {
fmt.Fprintf(&b, "Output (the last %s of %s):\n\n", chatShellBytes(int64(len(output.Output))), chatShellBytes(output.OutputBytes))
} else {
b.WriteString("Output:\n\n")
}
fence = chatShellFence(output.Output)
text := strings.TrimRight(output.Output, "\n")
fmt.Fprintf(&b, "%stext\n%s\n%s", fence, text, fence)
return b.String()
}
// chatShellOutcome describes how a run ended, in the card's own words.
func chatShellOutcome(record protocol.ChatShellRunRecord) string {
took := (time.Duration(record.DurationMS) * time.Millisecond).Round(time.Millisecond)
switch record.Status {
case protocol.ChatShellRunStopped:
return fmt.Sprintf("I stopped it after %s", took)
case protocol.ChatShellRunInterrupted:
return "It was interrupted when the server stopped"
case protocol.ChatShellRunFailed:
return "It failed: " + record.Error
}
if record.Signal != "" {
return fmt.Sprintf("It was killed by %s after %s", record.Signal, took)
}
if record.ExitCode != nil {
return fmt.Sprintf("It exited with status %d after %s", *record.ExitCode, took)
}
return "It ended"
}
// chatShellFence is a Markdown code fence longer than any backtick run in text.
func chatShellFence(text string) string {
longest, run := 0, 0
for _, r := range text {
if r == '`' {
run++
longest = max(longest, run)
} else {
run = 0
}
}
return strings.Repeat("`", max(3, longest+1))
}
func chatShellBytes(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)
}
+132
View File
@@ -0,0 +1,132 @@
package server
import (
"context"
"errors"
"os"
"os/exec"
"syscall"
"time"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// supervise reads one command's merged output, streams it in batches, saves
// it periodically and records how the command ended. It owns the reader.
func (r *chatShellRunner) supervise(p *chatShellProcess, reader *os.File) {
defer r.wg.Done()
defer close(p.done)
readDone := make(chan struct{})
go func() {
defer close(readDone)
buffer := make([]byte, 32<<10)
for {
n, err := reader.Read(buffer)
if n > 0 {
p.mu.Lock()
p.out.write(buffer[:n])
p.mu.Unlock()
}
if err != nil {
return
}
}
}()
waitDone := make(chan error, 1)
go func() { waitDone <- p.cmd.Wait() }()
pid := p.cmd.Process.Pid
flush := time.NewTicker(r.flush)
defer flush.Stop()
lastSaved := r.now()
var waitErr error
exited, drained, shutdown := false, false, false
base := r.base.Done()
for !exited || !drained {
select {
case <-flush.C:
r.emitOutput(p, false)
if r.now().Sub(lastSaved) >= r.persist {
lastSaved = r.now()
r.save(p.snapshot(protocol.ChatShellRunRetained))
}
case waitErr = <-waitDone:
exited = true
// Descendants may hold the pipe open; read what they write
// briefly, then stop reading.
_ = reader.SetReadDeadline(time.Now().Add(chatShellDrain))
case <-readDone:
drained = true
readDone = nil
case <-base:
base = nil
shutdown = true
_ = syscall.Kill(-pid, syscall.SIGKILL)
}
}
// Nothing in the command's group outlives it.
_ = syscall.Kill(-pid, syscall.SIGKILL)
reader.Close()
r.emitOutput(p, true)
p.mu.Lock()
finishChatShellRecord(&p.record, waitErr, p.stopped, shutdown || r.base.Err() != nil, r.now())
p.mu.Unlock()
record := p.snapshot(protocol.ChatShellRunRetained)
r.save(record)
r.mu.Lock()
delete(r.active, p.record.ID)
r.mu.Unlock()
r.publishRun(record)
}
// finishChatShellRecord records how a command ended. A requested stop wins
// over the exit status it caused; a server shutdown marks it interrupted.
func finishChatShellRecord(record *protocol.ChatShellRunRecord, waitErr error, stopped, shutdown bool, now time.Time) {
record.EndedAt = now.UnixMilli()
record.DurationMS = max(record.EndedAt-record.StartedAt, 0)
var exitErr *exec.ExitError
switch {
case waitErr == nil:
code := 0
record.ExitCode = &code
case errors.As(waitErr, &exitErr):
if status, ok := exitErr.Sys().(syscall.WaitStatus); ok && status.Signaled() {
record.Signal = status.Signal().String()
} else {
code := exitErr.ExitCode()
record.ExitCode = &code
}
default:
record.Error = waitErr.Error()
}
switch {
case shutdown:
record.Status = protocol.ChatShellRunInterrupted
record.Error = chatShellInterruptedReason
case stopped:
record.Status = protocol.ChatShellRunStopped
case record.Error != "":
record.Status = protocol.ChatShellRunFailed
default:
record.Status = protocol.ChatShellRunExited
}
}
// emitOutput pushes the output written since the last frame.
func (r *chatShellRunner) emitOutput(p *chatShellProcess, final bool) {
p.mu.Lock()
text, offset, end, ok := p.out.pending(protocol.ChatShellRunChunkLimit, final)
sessionID, runID := p.record.SessionID, p.record.ID
p.mu.Unlock()
if !ok || r.publish == nil {
return
}
r.publish(sessionID, protocol.ChatShellRunEventFrame{SessionID: sessionID, RunID: runID, Output: text, Offset: offset, End: end})
}
// save persists a record; a shutdown's base context is already canceled, so
// it uses its own bounded context.
func (r *chatShellRunner) save(record protocol.ChatShellRunRecord) {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
_ = r.store.SaveChatShellRun(ctx, record, protocol.ChatShellRunHistory)
}
+12 -1
View File
@@ -22,6 +22,13 @@ const chatPermissionPollInterval = 2 * time.Second
// every other client, attributed to the sending device's label, and the turn's
// output is fanned out to all of them.
func handleChatPrompt(ctx context.Context, request protocol.Message, broker chatBroker, hub *chatHub, registry operatorRegistry, clientID string, write func(protocol.Message) error) {
admitChatPrompt(ctx, request, broker, hub, registry, clientID, write, false)
}
// admitChatPrompt is handleChatPrompt; echoSender also publishes the user turn
// to the sending client, for a prompt the server composed (chat_shell_share)
// that the sender has no local copy of.
func admitChatPrompt(ctx context.Context, request protocol.Message, broker chatBroker, hub *chatHub, registry operatorRegistry, clientID string, write func(protocol.Message) error, echoSender bool) {
if broker == nil {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat is not configured on this server"})
return
@@ -128,7 +135,11 @@ func handleChatPrompt(ctx context.Context, request protocol.Message, broker chat
accepted = true
queued := admission == chatAdmitQueued
// Publish the user turn to every other client; the sender already has it.
hub.broadcastUser(userFrame, clientID)
exceptClientID := clientID
if echoSender {
exceptClientID = ""
}
hub.broadcastUser(userFrame, exceptClientID)
if admission == chatAdmitSteered {
hub.markOpSteered(sessionID, operationID)
// The harness took the message into its running turn: it is not queued,
+7
View File
@@ -136,6 +136,13 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin
hub.liveStore = stores[0]
hub.turnDiffStore = stores[0]
}
// Operator shell commands persist beside the operator sessions they belong
// to: the execution store, else an injected store-backed registry.
if len(stores) > 0 {
hub.startShellRunner(ctx, stores[0])
} else if store, ok := registry.(chatShellRunStore); ok {
hub.startShellRunner(ctx, store)
}
acks := newAttentionAckHub()
var ackStore attentionAckStore
var notes *appNotifier