feat(tui-harness): tui_action tool, bug fixes, SVG rendering (aws#575)

* feat(tui-harness): add tui_action tool, fix sendKeys bug, add annotations

- Add tui_action composite tool combining send keys + wait for pattern +
  read screen in a single MCP round-trip
- Fix sendKeys silent discard bug where both keys and specialKey were
  sent sequentially with the first result overwritten
- Surface settling monitor return value via new SendResult type so
  agents know if the screen fully settled or hit the hard ceiling
- Add title and annotations (openWorldHint, readOnlyHint) to all tools

Constraint: sendKeys/sendSpecialKey return type changed from ScreenState to SendResult
Rejected: Add settled to ScreenState | mixes screen data with process metadata
Confidence: high
Scope-risk: moderate
Directive: tui_action intentionally reads screen twice (once from sendKeys, once for formatting options) — the buffer read is cheap
Not-tested: empty string keys parameter passes validation but writes nothing to PTY

* fix(tui-harness): fix SVG screenshot character positioning

SVG screenshots had misaligned characters ("janky letters all over the
place") due to two issues:

1. No xml:space="preserve" on <text> elements — SVG defaults to
   collapsing whitespace, so spaces in terminal text were eaten
2. No textLength on <tspan> elements — character positioning depended
   entirely on the viewer's font metrics matching our charWidth=0.6em
   assumption, which varies across renderers

Add xml:space="preserve" to prevent whitespace collapse and textLength
with lengthAdjust="spacing" to force each span to occupy the exact
calculated grid width regardless of font rendering differences.

Constraint: Must work across browser, GitHub markdown, and macOS Preview SVG renderers
Rejected: Render each character individually | extremely verbose SVG output
Rejected: Use ch CSS units | not supported in SVG
Confidence: high
Scope-risk: narrow

Author: aidandaly24

src/tui-harness/__tests__/svg-renderer.test.ts

@@ -108,4 +108,21 @@ describe('SVG renderer', () => {
 
     expect(svg).toContain('My Terminal');
   });
+
+  it('preserves whitespace and uses textLength for precise character positioning', async () => {
+    terminal = new Terminal({ cols: 80, rows: 24, allowProposedApi: true });
+    terminal.write('test');
+    await new Promise(resolve => setTimeout(resolve, 50));
+
+    const svg = renderTerminalToSvg(terminal);
+
+    // Both CSS white-space:pre and xml:space="preserve" prevent whitespace collapse
+    expect(svg).toContain('white-space: pre');
+    expect(svg).toContain('xml:space="preserve"');
+    // Must use textLength + lengthAdjust for font-independent character grid alignment
+    expect(svg).toContain('textLength=');
+    expect(svg).toContain('lengthAdjust="spacing"');
+    // Tspans must be inline within <text> — no newlines that white-space:pre would render
+    expect(svg).not.toMatch(/<text[^>]*>\n/);
+  });
 });

src/tui-harness/index.ts

@@ -13,7 +13,7 @@
 export { TuiSession } from './lib/tui-session.js';
 
 // --- Types and error classes ---
-export type { LaunchOptions, ScreenState, ReadOptions, CloseResult, SessionInfo } from './lib/types.js';
+export type { LaunchOptions, ScreenState, ReadOptions, CloseResult, SendResult, SessionInfo } from './lib/types.js';
 export type { SpecialKey } from './lib/types.js';
 export { SPECIAL_KEY_VALUES, WaitForTimeoutError, LaunchError } from './lib/types.js';
 

src/tui-harness/lib/svg-renderer.ts

@@ -423,11 +423,12 @@ export function renderTerminalToSvg(terminal: Terminal, options?: SvgRenderOptio
     if (!hasVisibleText) continue;
 
     const textY = y + textBaseline;
-    svgParts.push(`<text y="${textY}" class="fg">`);
+    const tspanParts: string[] = [];
 
     for (const span of spans) {
       const x = span.startCol * charWidth;
-      const attrs: string[] = [`x="${x}"`];
+      const spanWidth = span.colWidth * charWidth;
+      const attrs: string[] = [`x="${x}"`, `textLength="${spanWidth}"`, 'lengthAdjust="spacing"'];
 
       if (span.style.fg !== null) {
         attrs.push(`fill="${span.style.fg}"`);
@@ -443,10 +444,12 @@ export function renderTerminalToSvg(terminal: Terminal, options?: SvgRenderOptio
         attrs.push(`class="${classes.join(' ')}"`);
       }
 
-      svgParts.push(`<tspan ${attrs.join(' ')}>${escapeXml(span.text)}</tspan>`);
+      tspanParts.push(`<tspan ${attrs.join(' ')}>${escapeXml(span.text)}</tspan>`);
     }
 
-    svgParts.push('</text>');
+    // Concatenate tspans inline — newlines between tspans would render as
+    // visible line breaks under white-space:pre / xml:space="preserve".
+    svgParts.push(`<text y="${textY}" xml:space="preserve" class="fg">${tspanParts.join('')}</text>`);
   }
 
   svgParts.push('</g>');

src/tui-harness/lib/tui-session.ts

@@ -17,7 +17,15 @@ import { register, unregister } from './session-manager.js';
 import { SettlingMonitor } from './settling.js';
 import { renderTerminalToSvg } from './svg-renderer.js';
 import type { SvgRenderOptions } from './svg-renderer.js';
-import type { CloseResult, LaunchOptions, ReadOptions, ScreenState, SessionInfo, SpecialKey } from './types.js';
+import type {
+  CloseResult,
+  LaunchOptions,
+  ReadOptions,
+  ScreenState,
+  SendResult,
+  SessionInfo,
+  SpecialKey,
+} from './types.js';
 import { LaunchError, WaitForTimeoutError } from './types.js';
 import xtermHeadless from '@xterm/headless';
 import { randomUUID } from 'crypto';
@@ -314,28 +322,28 @@ export class TuiSession {
    * @param keys - The raw characters or escape sequences to write.
    * @param waitMs - Optional settling time in milliseconds. Defaults to the
    *   settling monitor's default (300ms).
-   * @returns The screen state after output settles.
+   * @returns The screen state and settling status after output settles.
    */
-  async sendKeys(keys: string, waitMs?: number): Promise<ScreenState> {
+  async sendKeys(keys: string, waitMs?: number): Promise<SendResult> {
     this.assertAlive();
     this.ptyProcess.write(keys);
-    await this.settlingMonitor.waitForSettle(waitMs);
-    return this.readScreen();
+    const settled = await this.settlingMonitor.waitForSettle(waitMs);
+    return { screen: this.readScreen(), settled };
   }
 
   /**
    * Send a named special key to the PTY process.
    *
    * @param key - The special key name (e.g., 'enter', 'ctrl+c', 'f5').
    * @param waitMs - Optional settling time in milliseconds.
-   * @returns The screen state after output settles.
+   * @returns The screen state and settling status after output settles.
    */
-  async sendSpecialKey(key: SpecialKey, waitMs?: number): Promise<ScreenState> {
+  async sendSpecialKey(key: SpecialKey, waitMs?: number): Promise<SendResult> {
     this.assertAlive();
     const sequence = resolveKey(key);
     this.ptyProcess.write(sequence);
-    await this.settlingMonitor.waitForSettle(waitMs);
-    return this.readScreen();
+    const settled = await this.settlingMonitor.waitForSettle(waitMs);
+    return { screen: this.readScreen(), settled };
   }
 
   // ---------------------------------------------------------------------------

src/tui-harness/lib/types.ts

@@ -59,6 +59,19 @@ export interface ReadOptions {
   numbered?: boolean;
 }
 
+/**
+ * Result from sending keys to a TUI session.
+ *
+ * @property screen - The screen state after output settles.
+ * @property settled - Whether the terminal output fully settled within the
+ *   wait period. When `false`, the hard ceiling timeout was reached and the
+ *   screen content may still be updating.
+ */
+export interface SendResult {
+  screen: ScreenState;
+  settled: boolean;
+}
+
 /**
  * Result returned when a TUI session is closed.
  *