Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,8 @@
<PackageVersion Include="Grpc.AspNetCore" Version="2.83.0" />
<PackageVersion Include="Grpc.Net.ClientFactory" Version="2.83.0" />
<PackageVersion Include="Grpc.Tools" Version="2.83.0" />
<PackageVersion Include="Hex1b" Version="0.165.0" />
<!-- Keep paired with @hex1b/web-terminal in src/Aspire.Dashboard/package.json. -->
<PackageVersion Include="Hex1b" Version="0.167.0-alpha.1547.1.798b26c" />
<PackageVersion Include="Hex1b.McpServer" Version="0.165.0" />
<PackageVersion Include="Hex1b.Tool" Version="0.165.0" />
<PackageVersion Include="Humanizer.Core" Version="3.0.10" />
Expand Down
103 changes: 77 additions & 26 deletions docs/specs/with-terminal.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ builder.AddProject<Projects.MyAgent>("agent")
.WithTerminal();
```

The dashboard then renders an xterm.js terminal per replica, and the CLI
The dashboard then renders a Hex1b web terminal per replica, and the CLI
exposes the same session as `aspire terminal agent --replica 0`.

## Process topology
Expand Down Expand Up @@ -63,10 +63,11 @@ version 1), which already handles:
- Authenticated stream factory hooks (we only use Unix-socket transport
today)

The `Hmp1WorkloadAdapter` is what the AppHost-side terminal host uses to
multiplex DCP's PTY traffic to the consumer-facing listener; the
`Hmp1PresentationAdapter` is what consumers (Dashboard WebSocket proxy and
the CLI) use to attach.
The terminal host uses `DcpUpstreamAdapter` for DCP's minimal single-peer
protocol and `Hmp1PresentationAdapter` for its consumer-facing listener.
The dashboard and CLI attach using `Hmp1WorkloadAdapter`. The dashboard
adds a per-browser `Hex1bTerminal` mirror with `Hwt1PresentationAdapter`;
the browser receives authoritative terminal state rather than parsing ANSI.

## Property contract (gRPC `ResourceService` snapshots)

Expand All @@ -93,34 +94,76 @@ endpoint at `/api/terminal?resource=<displayName>&replica=<index>`.

`TerminalWebSocketProxy` resolves the connection entirely server-side:

1. `ITerminalConnectionResolver.ConnectAsync(resourceName, replicaIndex, ct)`
1. The same-origin WebSocket gate rejects missing or cross-origin `Origin`
headers before resolving a resource, in addition to frontend authorization.
2. `ITerminalConnectionResolver.ConnectAsync(resourceName, replicaIndex, ct)`
walks `IDashboardClient.GetResources()`, matches by `DisplayName` +
`TryGetTerminalReplicaInfo`, and connects via
`Hmp1Transports.ConnectUnixSocket(consumerUdsPath, ct)`.
2. The proxy wraps the resulting stream in `Hmp1WorkloadAdapter` and runs
two pumps:
- **Inbound (browser → producer):** binary frames are forwarded as HMP v1
`Input` (keystrokes); text frames are parsed as JSON resize control
messages (`{"type":"resize","cols":N,"rows":N}`).
- **Outbound (producer → browser):** VT bytes from the producer become
binary WebSocket frames; resize hints from the producer become JSON
text frames.
3. Frame type — not content — distinguishes keystroke from control. This
keeps the proxy's parser cheap and avoids ambiguity around binary input
that happens to look like JSON.
4. Multi-fragment WS reads are reassembled in `ReassembledFrame` using
`ArrayPool<byte>`.
3. The handler connects a public `Hmp1WorkloadAdapter`, attaches a per-view
terminal and `Hwt1PresentationAdapter`, and runs the two transport pumps.
Incoming UTF-8 JSON messages are reassembled up to 64 KiB and passed to
`HandleMessageAsync`. Each `ReadFrameAsync` result is sent as one complete
binary WebSocket message, without dropping or reordering frames.
4. Hex1b owns input encoding, primary-role negotiation, selection, history,
graphics projection, acknowledgements and state resynchronization. The
dashboard bounds handshake and send times and cancels both pumps when
either transport ends. Disposing a view disconnects only that peer, not
the AppHost-owned producer.

The browser never sees `consumerUdsPath` and cannot induce the dashboard
to connect to an arbitrary local socket — it can only ask for
`(resource, replica)` pairs that are present in the resource snapshot
stream.

### Browser requirements and package pairing

The dashboard uses `@hex1b/web-terminal` and the `Hex1b` NuGet package at
exactly `0.167.0-alpha.1547.1.798b26c`. HWT1 is experimental state transfer
between these paired packages, not a stable wire contract implemented by
Aspire. Upgrade both together. The full npm `dist` tree is vendored, including
module workers, relative imports, fonts and licenses.

The dashboard uses the package's automatic renderer selection: WebGPU is
preferred, with WebGL2 used when WebGPU capabilities or device acquisition are
unavailable. WebGPU requires a secure context (HTTPS or localhost); WebGL2 can
render on ordinary HTTP. Clipboard API restrictions still apply, and renderer
selection does not relax transport security, authorization or origin checks.
Both backends require OffscreenCanvas and module workers. Initialization and
runtime rendering failures remain visible errors; there is no xterm.js fallback.
Sixel and Kitty Graphics Protocol are rendered
from server-authoritative state. Historical rendering is text-only. The
dashboard's independent console-log view remains available.

Text selections use a translucent Aspire accent highlight. A Fluent copy button
appears below and to the right of the last visible selected line, clamping to the
canvas edges and moving above the line when there is not enough room below.
The dashboard uses Hex1b's public selection overlay and copy action; Hex1b retains
ownership of authoritative selection text, history and clipboard handling.
After a successful copy, the selection and copy overlay are cleared and focus
returns to the terminal, ready for Cmd+V or Ctrl+V. A failed copy leaves the
selection available for retry.

HMP checkpoints retain uploaded Kitty image data even when an animation
temporarily removes its placements. They also preserve partially received ANSI
sequences, so late and reconnected viewers can resume placement-only updates
without losing pixels or displaying fragments of graphics commands. See the
[graphics and partial-sequence replay fix](https://github.com/mitchdenny/hex1b/pull/496).

The package handles Ctrl/Cmd+click on authoritative OSC 8 hyperlinks in live
output and history. HMP state replay preserves link destinations across late
attachment and reconnect. It only opens absolute HTTP, HTTPS and mailto destinations
with `noopener,noreferrer`; plain clicks and drags retain selection/application
behavior. Aspire adds no custom opener or plain-text URL detection. See the
[hyperlink PR](https://github.com/mitchdenny/hex1b/pull/489),
[renderer PR](https://github.com/mitchdenny/hex1b/pull/491), and
[hyperlink replay fix](https://github.com/mitchdenny/hex1b/pull/493).

### Console / Terminal view toggle

For a terminal-enabled resource the dashboard `ConsoleLogs` page mounts
**both** `LogViewer` (the resource's standard log stream) and
`TerminalView` (the interactive xterm.js terminal) at the same time and
`TerminalView` (the interactive Hex1b web terminal) at the same time and
flips between them via a pair of **Console logs** / **Terminal** items
rendered inside the toolbar's options (⋯) `AspireMenuButton`:

Expand All @@ -133,10 +176,10 @@ rendered inside the toolbar's options (⋯) `AspireMenuButton`:
or a different resource is selected (which resets to Console).
- Both views stay mounted across flips (visibility is toggled with
`display:none` on a wrapper `<div>`); the log subscription and the
xterm/HMP1 consumer session are kept alive so neither view loses
Hex1b/HMP1 consumer session are kept alive so neither view loses
scrollback or has to re-handshake on toggle. After a `display:none →
visible` transition the page calls `refreshLayout` on the JS terminal
to guarantee xterm rebinds to the new available space.
to fit the terminal to the new available space.

The console log stream is now subscribed to for terminal-enabled
resources too (previously it was suppressed), which is what makes the
Expand All @@ -145,7 +188,7 @@ Console view non-empty for a `WithTerminal()` resource.
## CLI

`aspire terminal <resource> [--replica N]` (`Aspire.Cli/Commands/TerminalCommand.cs`)
opens its own `Hmp1PresentationAdapter` against the consumer UDS path
opens its own `Hmp1WorkloadAdapter` against the consumer UDS path
returned by `IBackchannel.GetTerminalInfoAsync(resource, replica)` and
renders frames into the host terminal via Hex1b's `Hex1bTerminal`. When the
resource has more than one replica and the CLI is interactive, it prompts
Expand All @@ -171,8 +214,16 @@ when the executable (or container) spec carries a populated `terminal` block:
process owns the listener). The dimensions are the initial PTY size; both
sides exchange resize frames over HMP afterwards.

Desktop PTY support is implemented across all three platforms (Unix98 `/dev/ptmx` on Linux and macOS; ConPTY on Windows). Container PTYs are tracked
as a Phase 3 follow-up on the parent issue.
Desktop PTY support is implemented across all three platforms (Unix98 `/dev/ptmx` on Linux and macOS; ConPTY on Windows).
Container PTYs use the container runtime's attach command. DCP currently starts the
container before attaching, so one-time startup output, including terminal capability
queries, can be lost. See the [DCP startup ordering](https://github.com/microsoft/dcp/blob/v0.25.13/controllers/container_controller.go#L1843-L1855).

The `notcurses` resource in `playground/Terminals` installs Ubuntu's `notcurses-bin`
package and starts an interactive Bash shell. Open its dashboard Terminal view, then
run `notcurses-demo` to exercise graphics, color and Unicode rendering. Starting the
demo from the attached shell avoids losing its initial capability queries. Press
`q` to return to the shell; run the command again to repeat the stress workload.

## Files of interest

Expand All @@ -187,6 +238,6 @@ as a Phase 3 follow-up on the parent issue.
| CLI command | `src/Aspire.Cli/Commands/TerminalCommand.cs` |
| Dashboard WebSocket proxy | `src/Aspire.Dashboard/Terminal/TerminalWebSocketProxy.cs` |
| Dashboard resolver | `src/Aspire.Dashboard/Terminal/DefaultTerminalConnectionResolver.cs`|
| `TerminalView` (xterm.js host) | `src/Aspire.Dashboard/Components/Controls/TerminalView.razor.*` |
| `TerminalView` (Hex1b web host) | `src/Aspire.Dashboard/Components/Controls/TerminalView.razor.*` |
| Property keys | `src/Shared/Model/KnownProperties.cs` (`Terminal.*`) |
| Playground sample | `playground/Terminals/Terminals.AppHost/AppHost.cs` |
9 changes: 9 additions & 0 deletions eng/github-ci/test-trigger-map.yml
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,15 @@ ignore:
# Path rules: a glob set -> a target set. One mechanism; the comment headers below are organization
# only. targets may be test: / job: / a GROUP name / ALL.
path_rules:
- paths:
- src/Aspire.Dashboard/Components/Controls/TerminalView.razor.js
- src/Aspire.Dashboard/wwwroot/js/app.js
- src/Aspire.Dashboard/package.json
- src/Aspire.Dashboard/package-lock.json
- src/Aspire.Dashboard/wwwroot/js/hex1b-web-terminal/**
- tests/Aspire.Dashboard.Components.Tests/JavaScript/**
targets: [test:Infrastructure.Tests]
Comment on lines +102 to +109
reason: DashboardTerminalScriptTests executes the terminal lifecycle JavaScript and reads the paired package assets outside its MSBuild graph.

# --- catch-all: build infrastructure & broadly shared code -> ALL --------------------------
- paths:
Expand Down
11 changes: 10 additions & 1 deletion playground/Terminals/Terminals.AppHost/AppHost.cs
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,16 @@
.WithTerminal(options => options.ShowTerminalHost = true);
}

builder.AddDockerfile("notcurses", "../Terminals.Notcurses")
.WithTerminal(options =>
{
// The demo recommends at least 80x45 for its graphics and Unicode workloads:
// https://manpages.ubuntu.com/manpages/noble/man1/notcurses-demo.1.html
options.Columns = 120;
options.Rows = 45;
options.ShowTerminalHost = true;
});

#if !SKIP_DASHBOARD_REFERENCE
// This project is only added in playground projects to support development/debugging
// of the dashboard. It is not required in end developer code. Comment out this code
Expand All @@ -70,4 +80,3 @@
#endif

builder.Build().Run();

18 changes: 18 additions & 0 deletions playground/Terminals/Terminals.Notcurses/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Licensed to the .NET Foundation under one or more agreements.
# The .NET Foundation licenses this file to you under the MIT license.

FROM ubuntu:24.04

RUN apt-get update \
&& apt-get install -y --no-install-recommends notcurses-bin \
&& rm -rf /var/lib/apt/lists

ENV LANG=C.UTF-8 \
TERM=xterm-256color \
COLORTERM=24bit

USER 1000:1000

# Launch notcurses-demo from the shell after the terminal has attached, so DCP
# does not lose the demo's one-time terminal capability queries during startup.
CMD ["bash", "-i", "-l"]
4 changes: 1 addition & 3 deletions src/Aspire.Dashboard/Aspire.Dashboard.csproj
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
<Project Sdk="Microsoft.NET.Sdk.Web">

<PropertyGroup>
<!-- This list of runtimes needs to match the set of runtimes specified in eng/workloads/workloads.csproj -->
<RuntimeIdentifiers>win-x86;win-x64;win-arm64;linux-x64;linux-arm64;linux-musl-x64;osx-x64;osx-arm64</RuntimeIdentifiers>
Expand Down Expand Up @@ -332,10 +331,9 @@
</ItemGroup>

<ItemGroup>
<Content Update="package.json;package-lock.json" CopyToPublishDirectory="Never" />
<Content Remove="wwwroot\js\README.md" />
<None Include="wwwroot\js\README.md" />
<Content Remove="wwwroot\fonts\cascadia-mono-nf\README.md" />
<None Include="wwwroot\fonts\cascadia-mono-nf\README.md" />
</ItemGroup>

<Import Project="BlazorAssets.targets" />
Expand Down
33 changes: 32 additions & 1 deletion src/Aspire.Dashboard/Components/Controls/TerminalView.razor
Original file line number Diff line number Diff line change
@@ -1,3 +1,34 @@
@namespace Aspire.Dashboard.Components.Controls

<div class="terminal-container" @ref="_terminalElement" style="width: 100%; height: 100%;"></div>
<div class="terminal-view">
<div hidden @ref="_selectionTemplateElement">
<div class="terminal-selection-actions">
<FluentButton Class="terminal-selection-copy"
Appearance="ButtonAppearance.Default"
IconOnly="true"
Title="@ControlsLoc[nameof(Resources.ControlsStrings.GridValueCopyToClipboard)]"
aria-label="@ControlsLoc[nameof(Resources.ControlsStrings.GridValueCopyToClipboard)]">
<FluentIcon Value="new Icons.Regular.Size16.Copy()" Color="Color.Default" />
</FluentButton>
</div>
</div>
<div class="terminal-frame">
<div class="terminal-titlebar">
<span class="terminal-title">@(ResourceName ?? Loc[nameof(Resources.ConsoleLogs.ConsoleLogsViewTerminalOption)].Value)</span>
@if (_terminalColumns > 0 && _terminalRows > 0)
{
<span class="terminal-dimensions" title="@Loc[nameof(Resources.ConsoleLogs.TerminalToolbarGridSize)]">@_terminalColumns &times; @_terminalRows</span>
}
</div>
<div class="terminal-body">
<div class="terminal-container" @ref="_terminalElement"></div>
@if (_terminalError is not null)
{
<div class="terminal-error">
<span role="alert">@GetErrorMessage()</span>
<FluentButton OnClick="RetryAsync">@Loc[nameof(Resources.ConsoleLogs.TerminalRetry)]</FluentButton>
</div>
}
</div>
</div>
</div>
Loading
Loading