Implement wtcli, an application to query details about an existing Terminal instance

OpenConsole.slnx

@@ -449,6 +449,7 @@
   <Folder Name="/Terminal/">
     <Project Path="src/cascadia/CascadiaPackage/CascadiaPackage.wapproj" Type="c7167f0d-bc9f-4e6e-afe1-012c56b48db5">
       <BuildDependency Project="src/cascadia/ShellExtension/WindowsTerminalShellExt.vcxproj" />
+      <BuildDependency Project="src/tools/wtcli/wtcli.vcxproj" />
       <BuildType Solution="AuditMode|Any CPU" Project="Debug" />
       <BuildType Solution="AuditMode|ARM64" Project="Release" />
       <BuildType Solution="AuditMode|x64" Project="Release" />
@@ -1046,4 +1047,15 @@
       <Build Solution="Fuzzing|x86" Project="false" />
     </Project>
   </Folder>
+  <Project Path="src/tools/wtcli/wtcli.vcxproj" Id="8a3b5e2f-1c4d-4f6a-9b8c-0d1e2f3a4b5c" />
+  <Project Path="src/cascadia/TerminalProtocol/TerminalProtocol.vcxproj" Id="f1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5d" />
+  <Project Path="src/cascadia/TerminalProtocol/ft_fuzzer/ProtocolFuzzer.vcxproj" Id="26711d2f-ca10-45be-9e89-43771030bdb0">
+    <Platform Solution="*|Any CPU" Project="Win32" />
+    <Build Solution="*|Any CPU" Project="false" />
+    <Build Solution="*|ARM64" Project="false" />
+    <Build Solution="*|x86" Project="false" />
+    <Build Solution="AuditMode|x64" Project="false" />
+    <Build Solution="Debug|x64" Project="false" />
+    <Build Solution="Release|x64" Project="false" />
+  </Project>
 </Solution>

doc/wtcli-commands.md

@@ -0,0 +1,40 @@
+# wtcli Command Reference
+
+`wtcli` is the CLI client for the Windows Terminal Protocol. It calls
+`CoCreateInstance` using the per-brand `CLSID` and exposes a tmux-style command surface over its IDL methods.
+
+- Source: `src/tools/wtcli/main.cpp`
+- IDL: `src/host/proxy/ITerminalProtocol.idl`
+- Primary in-tree caller: `tools/wta/src/shell/wt_channel/cli_channel.rs`.
+
+## Global flags
+
+| Flag | Effect |
+|------|--------|
+| `--json` | Emit machine-readable JSON. Required for any caller that parses output. |
+
+## Commands
+
+The "Used in repo" column reflects whether some other component in this
+repository actually shells out to that subcommand today (not whether the
+subcommand is reachable). External callers (third-party agents, ad-hoc
+scripts) are not counted.
+
+| Command | Alias | What it does | Example | Used in repo |
+|---------|-------|--------------|---------|--------------|
+| `list-windows` | `lsw` | List all Terminal windows. | `wtcli --json list-windows` | ✅ `cli_channel.rs` (`list_windows`) |
+| `list-tabs` | `lst` | List tabs in a window. `-w` defaults to the first window. | `wtcli --json list-tabs -w 1` | ✅ `cli_channel.rs` (`list_tabs`) |
+| `list-panes` | `lsp` | List panes in a tab. `-t`/`-w` default to the first tab of the first window. | `wtcli --json list-panes -t 2` | ✅ `cli_channel.rs` (`list_panes`) |
+| `active-pane` | — | Return metadata for the currently focused pane. Used by other subcommands as the default `-t` target. | `wtcli --json active-pane` | ✅ `cli_channel.rs` (`get_active_pane`) |
+| `capture-pane` | `capturep` | Read pane scrollback as text. `-l` caps line count. `--last-prompt` returns only the most recent completed shell prompt (requires OSC 133 shell integration). | `wtcli --json capture-pane -t 3 --last-prompt` | ✅ `cli_channel.rs` (`read_pane_output`) |
+| `pane-status` | — | Report pane process state: `pid`, `state` (`running`/`exited`), and `exit_code` when applicable. | `wtcli --json pane-status -t 3` | ✅ `cli_channel.rs` (`get_process_status`) |
+| `new-tab` | `neww` | Create a new tab. `-c` command, `-n` title, `-d` cwd. | `wtcli --json new-tab -c "pwsh" -n "build" -d C:\src` | ✅ `cli_channel.rs` (`create_tab`) |
+| `split-pane` | `splitw` | Split a pane. `-d right\|left\|up\|down\|auto` (default `automatic`). `-H`/`-v` are legacy aliases for `down`/`right`. `-s` is size fraction; `-c` is the command to run. | `wtcli --json split-pane -t 3 -d right -s 0.4 -c "tail -f log"` | ✅ `cli_channel.rs` (`split_pane`) |
+| `kill-pane` | `killp` | Close a pane. | `wtcli kill-pane -t 4` | ✅ `cli_channel.rs` (`close_pane`) |
+| `focus-pane` | `focusp` | Move focus to the given pane. | `wtcli focus-pane -t 3` | ✅ `cli_channel.rs` (`focus_pane`) |
+
+## Summary
+
+- **Wired into `wta` runtime (10):** `list-windows`, `list-tabs`,
+  `list-panes`, `active-pane`, `capture-pane`, `pane-status`,
+  `new-tab`, `split-pane`, `kill-pane`, `focus-pane`.

src/cascadia/CascadiaPackage/CascadiaPackage.wapproj

@@ -92,6 +92,9 @@
     <ProjectReference Include="$(OpenConsoleDir)src\host\proxy\Host.Proxy.vcxproj">
       <Project>{71CC9D78-BA29-4D93-946F-BEF5D9A3A6EF}</Project>
     </ProjectReference>
+    <ProjectReference Include="$(OpenConsoleDir)src\tools\wtcli\wtcli.vcxproj">
+      <Project>{8A3B5E2F-1C4D-4F6A-9B8C-0D1E2F3A4B5C}</Project>
+    </ProjectReference>
   </ItemGroup>
 
   <Target Name="OpenConsoleStompSourceProjectForWapProject" BeforeTargets="_ConvertItems">

src/cascadia/CascadiaPackage/Package-Can.appxmanifest

@@ -113,6 +113,7 @@
                 <com:Interface Id="E686C757-9A35-4A1C-B3CE-0BCC8B5C69F4" ProxyStubClsid="1D1852F4-ADAD-42B6-9A43-9437AAAD7717"/>
                 <com:Interface Id="6F23DA90-15C5-4203-9DB0-64E73F1B1B00" ProxyStubClsid="1D1852F4-ADAD-42B6-9A43-9437AAAD7717"/> <!-- ITerminalHandoff3 -->
                 <com:Interface Id="746E6BC0-AB05-4E38-AB14-71E86763141F" ProxyStubClsid="1D1852F4-ADAD-42B6-9A43-9437AAAD7717"/>
+                <com:Interface Id="D999831E-7EBD-4B14-9D2F-8B09417582D4" ProxyStubClsid="1D1852F4-ADAD-42B6-9A43-9437AAAD7717"/> <!-- ITerminalProtocol -->
             </com:ComInterface>
         </com:Extension>
         <com:Extension Category="windows.comServer">
@@ -122,6 +123,7 @@
                 </com:ExeServer>
                 <com:ExeServer DisplayName="WindowsTerminal" Executable="WindowsTerminal.exe">
                     <com:Class Id="1706609C-A4CE-4C0D-B7D2-C19BF66398A5"/>
+                    <com:Class Id="264DE65B-F597-4183-8A76-6A039A604725"/> <!-- TerminalProtocolComServer (Canary) -->
                 </com:ExeServer>
                 <com:SurrogateServer DisplayName="WindowsTerminalShellExt">
                     <com:Class Id="6119575F-6918-4392-AF16-C2C627AF9416" Path="WindowsTerminalShellExt.dll" ThreadingModel="STA"/>

src/cascadia/CascadiaPackage/Package-Dev.appxmanifest

@@ -113,6 +113,7 @@
                 <com:Interface Id="E686C757-9A35-4A1C-B3CE-0BCC8B5C69F4" ProxyStubClsid="DEC4804D-56D1-4F73-9FBE-6828E7C85C56"/>
                 <com:Interface Id="6F23DA90-15C5-4203-9DB0-64E73F1B1B00" ProxyStubClsid="DEC4804D-56D1-4F73-9FBE-6828E7C85C56"/> <!-- ITerminalHandoff3 -->
                 <com:Interface Id="746E6BC0-AB05-4E38-AB14-71E86763141F" ProxyStubClsid="DEC4804D-56D1-4F73-9FBE-6828E7C85C56"/>
+                <com:Interface Id="D999831E-7EBD-4B14-9D2F-8B09417582D4" ProxyStubClsid="DEC4804D-56D1-4F73-9FBE-6828E7C85C56"/> <!-- ITerminalProtocol -->
             </com:ComInterface>
         </com:Extension>
         <com:Extension Category="windows.comServer">
@@ -122,6 +123,7 @@
                 </com:ExeServer>
                 <com:ExeServer DisplayName="WindowsTerminal" Executable="WindowsTerminal.exe">
                     <com:Class Id="051F34EE-C1FD-4B19-AF75-9BA54648434C"/>
+                    <com:Class Id="AD9425AA-1722-4E7B-A451-AA1D09106E83"/> <!-- TerminalProtocolComServer (Dev) -->
                 </com:ExeServer>
                 <com:SurrogateServer DisplayName="WindowsTerminalShellExt">
                     <com:Class Id="52065414-e077-47ec-a3ac-1cc5455e1b54" Path="WindowsTerminalShellExt.dll" ThreadingModel="STA"/>

src/cascadia/CascadiaPackage/Package-Pre.appxmanifest

@@ -202,6 +202,7 @@
                 <com:Interface Id="E686C757-9A35-4A1C-B3CE-0BCC8B5C69F4" ProxyStubClsid="1833E661-CC81-4DD0-87C6-C2F74BD39EFA"/>
                 <com:Interface Id="6F23DA90-15C5-4203-9DB0-64E73F1B1B00" ProxyStubClsid="1833E661-CC81-4DD0-87C6-C2F74BD39EFA"/> <!-- ITerminalHandoff3 -->
                 <com:Interface Id="746E6BC0-AB05-4E38-AB14-71E86763141F" ProxyStubClsid="1833E661-CC81-4DD0-87C6-C2F74BD39EFA"/>
+                <com:Interface Id="D999831E-7EBD-4B14-9D2F-8B09417582D4" ProxyStubClsid="1833E661-CC81-4DD0-87C6-C2F74BD39EFA"/> <!-- ITerminalProtocol -->
             </com:ComInterface>
         </com:Extension>
         <com:Extension Category="windows.comServer">
@@ -211,6 +212,7 @@
                 </com:ExeServer>
                 <com:ExeServer DisplayName="WindowsTerminal" Executable="WindowsTerminal.exe">
                     <com:Class Id="86633F1F-6454-40EC-89CE-DA4EBA977EE2"/>
+                    <com:Class Id="D77C8A1A-83C0-42FC-BADF-9BE82E2A1624"/> <!-- TerminalProtocolComServer (Preview) -->
                 </com:ExeServer>
                 <com:SurrogateServer DisplayName="WindowsTerminalShellExt">
                     <com:Class Id="02db545a-3e20-46de-83a5-1329b1e88b6b" Path="WindowsTerminalShellExt.dll" ThreadingModel="STA"/>

src/cascadia/CascadiaPackage/Package.appxmanifest

@@ -202,6 +202,7 @@
                 <com:Interface Id="E686C757-9A35-4A1C-B3CE-0BCC8B5C69F4" ProxyStubClsid="3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F"/>
                 <com:Interface Id="6F23DA90-15C5-4203-9DB0-64E73F1B1B00" ProxyStubClsid="3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F"/> <!-- ITerminalHandoff3 -->
                 <com:Interface Id="746E6BC0-AB05-4E38-AB14-71E86763141F" ProxyStubClsid="3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F"/>
+                <com:Interface Id="D999831E-7EBD-4B14-9D2F-8B09417582D4" ProxyStubClsid="3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F"/> <!-- ITerminalProtocol -->
             </com:ComInterface>
         </com:Extension>
         <com:Extension Category="windows.comServer">
@@ -211,6 +212,7 @@
                 </com:ExeServer>
                 <com:ExeServer DisplayName="WindowsTerminal" Executable="WindowsTerminal.exe">
                     <com:Class Id="E12CFF52-A866-4C77-9A90-F570A7AA2C6B"/>
+                    <com:Class Id="832FDEC7-AA6F-4BAB-85FA-A491405638FC"/> <!-- TerminalProtocolComServer (Release) -->
                 </com:ExeServer>
                 <com:SurrogateServer DisplayName="WindowsTerminalShellExt">
                     <com:Class Id="9f156763-7844-4dc4-b2b1-901f640f5155" Path="WindowsTerminalShellExt.dll" ThreadingModel="STA"/>

src/cascadia/TerminalApp/TerminalAppLib.vcxproj

@@ -213,6 +213,10 @@
       <DependentUpon>TerminalPage.xaml</DependentUpon>
       <SubType>Code</SubType>
     </ClCompile>
+    <ClCompile Include="TerminalPage.Protocol.cpp">
+      <DependentUpon>TerminalPage.xaml</DependentUpon>
+      <SubType>Code</SubType>
+    </ClCompile>
     <ClCompile Include="TabManagement.cpp">
       <DependentUpon>TerminalPage.xaml</DependentUpon>
       <SubType>Code</SubType>
@@ -385,6 +389,10 @@
       you also update all the consumers
     -->
     <ProjectReference Include="$(OpenConsoleDir)src\types\lib\types.vcxproj" />
+    <ProjectReference Include="$(OpenConsoleDir)src\cascadia\TerminalProtocol\TerminalProtocol.vcxproj">
+      <Project>{F1A2B3C4-D5E6-4F7A-8B9C-0D1E2F3A4B5D}</Project>
+      <ReferenceOutputAssembly>false</ReferenceOutputAssembly>
+    </ProjectReference>
     <ProjectReference Include="$(OpenConsoleDir)src\cascadia\WinRTUtils\WinRTUtils.vcxproj">
       <Project>{CA5CAD1A-039A-4929-BA2A-8BEB2E4106FE}</Project>
       <ReferenceOutputAssembly>false</ReferenceOutputAssembly>
@@ -467,6 +475,12 @@
       <Private>false</Private>
       <CopyLocalSatelliteAssemblies>false</CopyLocalSatelliteAssemblies>
     </Reference>
+    <Reference Include="Microsoft.Terminal.Protocol">
+      <HintPath>$(OpenConsoleCommonOutDir)TerminalProtocol\Microsoft.Terminal.Protocol.winmd</HintPath>
+      <IsWinMDFile>true</IsWinMDFile>
+      <Private>false</Private>
+      <CopyLocalSatelliteAssemblies>false</CopyLocalSatelliteAssemblies>
+    </Reference>
     <Reference Include="Microsoft.Terminal.UI.Markdown">
       <HintPath>$(OpenConsoleCommonOutDir)Microsoft.Terminal.UI.Markdown\Microsoft.Terminal.UI.Markdown.winmd</HintPath>
       <IsWinMDFile>true</IsWinMDFile>