feat(agent-pane): paste clipboard images into the chat with Alt+V (#211) (#354)

* feat(agent-pane): paste clipboard images into the chat with Alt+V (#211)

Support pasting an image from the Windows clipboard into the WTA agent-pane
chat input via Alt+V, mirroring the Copilot CLI. The image is sent to the
agent as an ACP `ContentBlock::Image` in the existing `session/prompt`.

- clipboard_image.rs (new): Win32 clipboard read (CF_DIBV5/CF_DIB screenshots
  re-encoded to PNG; CF_HDROP image files read raw with mime-from-ext).
- app.rs: Alt+V key handler gated on input nav-focus + the agent advertising
  `promptCapabilities.image`; per-tab pending image attachments; three clear
  system-message outcomes (attached / unsupported / empty clipboard).
- client.rs: thread `images` through PromptSubmission -> dispatch_prompt ->
  build_prompt_content, appended as ContentBlock::Image after the text block.
  Capability read from initialize's prompt_capabilities.image. No master change
  (cached_init_resp replay + verbatim PromptRequest forward already propagate).
- locales: 4 new keys translated across all 88 locale files.
- cgmanifest.json / NOTICE.md regenerated for the new `image` crate + deps.

Tests:
- clipboard round-trip (live OS clipboard DIB -> read_clipboard_image -> PNG).
- mock-agent end-to-end: clipboard image -> dispatch_prompt -> real ACP ->
  agent receives the exact ContentBlock::Image (mime + base64).
- ItE2E Feature.AgentImagePaste: injects Alt+V via win32-input-mode and asserts
  it reaches the helper's crossterm reader with the ALT modifier (the path the
  unit tests stub). Verified live against a deployed build.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(agent-pane): address Copilot review on image paste (#211)

- clipboard_image: cap clipboard payload at 256 MiB (MAX_CLIPBOARD_BYTES) so a
  corrupted/hostile GlobalSize can't drive an OOM allocation on Alt+V; oversized
  payloads are treated as non-pastable.
- clipboard_image: free the HGLOBAL via GlobalFree on the GlobalLock-fail and
  SetClipboardData-null paths in the test helper set_clipboard_dib (ownership is
  only transferred to the clipboard on success).
- app.rs: clear pending_images in clear_chat_history so /clear, /new, and session
  resets drop a queued-but-unsent attachment; doc comment updated to match.
- en-US.yml: lock the "Enter" key name in system.image_pasted per the WTA
  localization instructions (all 88 locales already keep it verbatim).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: vanzue

NOTICE.md

@@ -38,8 +38,10 @@ $publicFns = @(
     # Agent / Autofix / Sessions
     'Open-AgentPane', 'Set-AgentPaneFocus', 'Wait-AgentReady', 'Send-AgentPrompt', 'Wait-AgentState',
     'Test-AgentPaneOpen', 'Stop-AgentPane', 'Restore-AgentPane', 'Get-AgentPaneSession', 'Get-AgentPaneText',
-    'Send-AgentKey', 'Clear-AgentInput', 'Open-AgentCommandMenu', 'Get-AgentMenuSelection', 'Invoke-AgentMenuItem',
+    'Send-AgentKey', 'Clear-AgentInput', 'Send-AgentWin32Key', 'Send-AgentAltV',
+    'Open-AgentCommandMenu', 'Get-AgentMenuSelection', 'Invoke-AgentMenuItem',
     'Test-AgentPopupShown', 'Wait-AgentPermission', 'Resolve-AgentPermission', 'Assert-AgentPaneText',
+    'Set-ClipboardImage',
     'Wait-Autofix', 'Wait-WtCommandFailure', 'Send-AutofixState', 'Invoke-FailingCommand', 'Get-WtSessions',
     'Open-SessionList', 'Close-SessionList', 'Test-SessionListShown', 'Get-SessionRows',
     'Get-SessionListSelection', 'Select-SessionRow', 'Resume-Session', 'Get-SessionListJson',

test/e2e/ItE2E/ItE2E.psm1

@@ -61,6 +61,55 @@ function Clear-AgentInput {
     }
 }
 
+function Send-AgentWin32Key {
+    <#
+    .SYNOPSIS
+        Inject a single MODIFIED key (e.g. Alt+V, Shift+Enter) into the agent pane via
+        win32-input-mode raw key-event sequences — the only way to express a modifier, since
+        wtcli's tmux tokens and bare ANSI escapes carry no modifier state.
+    .DESCRIPTION
+        Emits a keydown then keyup as `ESC[Vk;Sc;Uc;Kd;Cs;Rc_`, where:
+          Vk = virtual-key code, Sc = scan code, Uc = UTF-16 unit (0 if none),
+          Kd = 1 down / 0 up, Cs = control-key-state bitmask, Rc = repeat count.
+        ConPTY decodes these back into INPUT_RECORD key events for the helper's console, so
+        crossterm sees a real KeyEvent with the modifier — exactly like a physical keypress.
+    .PARAMETER Modifiers
+        Control-key-state bitmask: 0x02 = LEFT_ALT_PRESSED, 0x10 = SHIFT_PRESSED,
+        0x08 = LEFT_CTRL_PRESSED (combine with -bor).
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory, ValueFromPipeline)]$App,
+        [Parameter(Mandatory)][int]$Vk,
+        [int]$Sc = 0,
+        [int]$Uc = 0,
+        [int]$Modifiers = 0,
+        [string]$PaneSessionId
+    )
+    process {
+        if (-not $PaneSessionId) {
+            $PaneSessionId = (Wait-Until -TimeoutSec 20 -Because "agent pane session id" -Condition { Get-AgentPaneSession -App $App }).PaneSessionId
+        }
+        $e = $script:ItEsc
+        $down = "$e[$Vk;$Sc;$Uc;1;$Modifiers;1_"
+        $up = "$e[$Vk;$Sc;$Uc;0;$Modifiers;1_"
+        Invoke-WtCli -App $App -Arguments @('send-keys', '--raw', '-t', $PaneSessionId, '--', "$down$up") | Out-Null
+        Start-Sleep -Milliseconds 150
+        $App
+    }
+}
+
+function Send-AgentAltV {
+    <#
+    .SYNOPSIS
+        Simulate Alt+V (clipboard image paste) in the agent pane. VK_V=0x56, scan=0x2F, no
+        character (Alt+letter is a menu accelerator, so Uc=0 — matching real hardware),
+        LEFT_ALT_PRESSED=0x02. The agent pane session is resolved automatically.
+    #>
+    [CmdletBinding()] param([Parameter(Mandatory, ValueFromPipeline)]$App, [string]$PaneSessionId)
+    process { Send-AgentWin32Key -App $App -Vk 0x56 -Sc 0x2F -Uc 0 -Modifiers 0x02 -PaneSessionId $PaneSessionId }
+}
+
 function Open-AgentCommandMenu {
     <#
     .SYNOPSIS

test/e2e/ItE2E/Public/AgentInput.ps1

@@ -0,0 +1,51 @@
+# Clipboard.ps1 — OS clipboard primitives for tests.
+#
+# The agent pane's Alt+V image paste (issue #211) reads the *live* OS clipboard from the
+# wta-helper (a real Win32 process sharing the interactive session's clipboard). To exercise
+# it end-to-end a test must place a real image on the clipboard first.
+#
+# `Clipboard.SetImage` requires an STA thread, so we run it on a dedicated STA runspace
+# (pwsh 7 defaults to MTA and has no -STA switch). The bitmap lands as CF_BITMAP/CF_DIB,
+# which `read_clipboard_image` picks up via its CF_DIBV5/CF_DIB path (label "screenshot").
+
+function Set-ClipboardImage {
+    <#
+    .SYNOPSIS
+        Put a synthetic bitmap on the OS clipboard (CF_DIB) so the agent pane's Alt+V has a
+        real image to capture. Returns nothing; throws if the clipboard write fails.
+    .PARAMETER Width / -Height
+        Size of the generated bitmap (default 24x24).
+    #>
+    [CmdletBinding()]
+    param([int]$Width = 24, [int]$Height = 24)
+
+    $worker = {
+        param($w, $h)
+        Add-Type -AssemblyName System.Windows.Forms, System.Drawing
+        $bmp = [System.Drawing.Bitmap]::new($w, $h)
+        for ($x = 0; $x -lt $w; $x++) {
+            for ($y = 0; $y -lt $h; $y++) {
+                $color = [System.Drawing.Color]::FromArgb(255, ($x * 10 % 256), ($y * 10 % 256), 128)
+                $bmp.SetPixel($x, $y, $color)
+            }
+        }
+        [System.Windows.Forms.Clipboard]::SetImage($bmp)
+        $bmp.Dispose()
+    }
+
+    $rs = [runspacefactory]::CreateRunspace()
+    $rs.ApartmentState = 'STA'
+    $rs.ThreadOptions = 'ReuseThread'
+    $rs.Open()
+    try {
+        $ps = [powershell]::Create()
+        try {
+            $ps.Runspace = $rs
+            $null = $ps.AddScript($worker).AddArgument($Width).AddArgument($Height)
+            $ps.Invoke() | Out-Null
+            if ($ps.Streams.Error.Count) { throw "Set-ClipboardImage failed: $($ps.Streams.Error[0])" }
+        }
+        finally { $ps.Dispose() }
+    }
+    finally { $rs.Close(); $rs.Dispose() }
+}

test/e2e/ItE2E/Public/Clipboard.ps1

@@ -0,0 +1,77 @@
+#Requires -Modules @{ ModuleName='Pester'; ModuleVersion='5.0.0' }
+# Feature: agent pane image paste (Alt+V) — issue #211.
+#
+# Verifies the end-to-end Alt+V flow against a deployed package:
+#   screenshot on clipboard -> focus agent pane -> simulate Alt+V -> image captured & queued.
+#
+# The key thing this proves that the Rust-side tests cannot: that Alt+V, injected through
+# WT/ConPTY as a win32-input-mode key event, actually reaches the helper's crossterm reader
+# as a KeyEvent carrying the ALT modifier (the path the unit tests stub out with a synthetic
+# KeyEvent). If this assumption were wrong, Alt+V would type a literal 'v' or be dropped, and
+# none of the handler's three outcome messages would appear.
+#
+#   Invoke-Pester test/e2e/tests/Feature.AgentImagePaste.Tests.ps1 -Tag Feature
+
+BeforeDiscovery {
+    $script:Ready = [bool](
+        (Get-AppxPackage | Where-Object { $_.Name -like '*IntelligentTerminal*' }) -and
+        (Get-Command copilot -ErrorAction SilentlyContinue) -and
+        (Get-Command winapp -ErrorAction SilentlyContinue)
+    )
+}
+
+Describe 'Feature: agent pane image paste (Alt+V)' -Tag 'Feature' -Skip:(-not $script:Ready) {
+    BeforeAll {
+        Import-Module (Join-Path $PSScriptRoot '..\ItE2E\ItE2E.psd1') -Force
+        $script:app = Start-Terminal -Package (Get-ItTestPackage) -PassFre $true -Settings @{ acpAgent = 'copilot' }
+        Open-AgentPane -App $script:app | Out-Null
+        Wait-AgentReady -App $script:app -TimeoutSec 60 | Out-Null
+    }
+    AfterAll { if ($script:app) { Stop-Terminal -App $script:app } }
+
+    It 'Alt+V reaches the handler and captures the clipboard image (not typed as a literal key)' {
+        # 1) Put a real image (CF_DIB) on the shared OS clipboard.
+        Set-ClipboardImage
+
+        # 2) Focus the agent pane input and dismiss any popup / stale char.
+        Set-AgentPaneFocus -App $script:app | Out-Null
+        Clear-AgentInput -App $script:app | Out-Null
+
+        # 3) Simulate Alt+V via win32-input-mode raw key events.
+        Send-AgentAltV -App $script:app | Out-Null
+
+        # 4) The handler must have run. With an image on the clipboard it either ATTACHES it
+        #    (📎 title / "Image attached") or — if copilot doesn't advertise the image prompt
+        #    capability — reports it UNSUPPORTED. Either proves Alt+V arrived as a KeyEvent
+        #    with the ALT modifier. It must NOT report an empty clipboard (we set one).
+        Assert-AgentPaneText -App $script:app -Pattern '📎|Image attached|support image input' -TimeoutSec 15
+
+        $after = Get-AgentPaneText -App $script:app -MaxLines 80
+        $after | Should -Not -Match 'No image on the clipboard'
+    }
+
+    It 'Queued image is sent to the agent as an ACP image content block (when the agent supports images)' {
+        $paneText = Get-AgentPaneText -App $script:app -MaxLines 80
+        if ($paneText -match 'support image input') {
+            Set-ItResult -Skipped -Because 'the configured agent does not advertise the image prompt capability'
+            return
+        }
+        # The image is queued (the 📎 input-box title). Submit it, then confirm an image
+        # content block reached the agent on the ACP wire. The wire trace only lands when
+        # debug logging is on, so treat its absence as inconclusive rather than a failure.
+        $acpLog = Get-ItLogText -App $script:app -Name 'wta-acp-debug.log' -SinceStart
+        if ([string]::IsNullOrWhiteSpace($acpLog)) {
+            Set-ItResult -Skipped -Because 'wta-acp-debug.log is empty (ACP wire trace requires WTA_LOG=debug)'
+            return
+        }
+
+        Send-AgentKey -App $script:app -Key Enter | Out-Null
+        Wait-AgentState -App $script:app -State Working -TimeoutSec 30 | Out-Null
+
+        $sent = Test-Until -TimeoutSec 30 -IntervalSec 1 -Condition {
+            $log = Get-ItLogText -App $script:app -Name 'wta-acp-debug.log' -SinceStart
+            ($log -match '"type"\s*:\s*"image"') -or ($log -match 'image/png')
+        }
+        $sent | Should -BeTrue -Because 'the pasted image must reach the agent as an ACP ContentBlock::Image'
+    }
+}

test/e2e/tests/Feature.AgentImagePaste.Tests.ps1

@@ -28,10 +28,16 @@ windows-sys = { version = "0.61", features = [
     "Win32_Foundation",
     "Win32_Globalization",
     "Win32_Storage_Packaging_Appx",
+    "Win32_System_DataExchange",
     "Win32_System_Environment",
+    "Win32_System_Memory",
     "Win32_System_Registry",
     "Win32_System_Threading",
+    "Win32_UI_Shell",
 ] }
+# Image decode/encode for clipboard-paste (Alt+V). Minimal feature set: decode
+# the clipboard DIB (BMP) and re-encode to PNG for ACP `ContentBlock::Image`.
+image = { version = "0.25", default-features = false, features = ["bmp", "png"] }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] }
 tracing-appender = "0.2"