feat: capture interactive agent TUI sessions

.github/workflows/js.yml

@@ -192,7 +192,9 @@ jobs:
       - name: Run tests (Deno)
         if: matrix.runtime == 'deno'
         working-directory: js
-        run: deno test --allow-read --allow-run --allow-env --allow-net test/**/*.test.mjs
+        # Release PRs intentionally verify freshly published dependencies.
+        # Deno 2.9 otherwise blocks packages younger than 24 hours.
+        run: deno test --minimum-dependency-age=0 --allow-read --allow-run --allow-env --allow-net test/**/*.test.mjs
 
   js-release:
     name: JS Release

js/.changeset/tidy-taxis-capture.md

@@ -0,0 +1,6 @@
+---
+'agent-commander': minor
+---
+
+Add cross-client real-TUI launch, input and resize control, semantic transcript
+normalization, and terminal artifact capture backed by command-stream.

js/README.md

@@ -84,6 +84,40 @@ console.log(result.metadata);
 
 `result.metadata` is a normalized summary for `claude`, `codex`, `opencode`, and `agent` runs. It includes success and error classification, session ID, usage-limit reset details, result summary, cost estimates, stream token usage, optional model usage, and sub-agent call summaries.
 
+### Real TUI capture
+
+Use `captureAgentTui()` when a test must exercise the same interactive terminal
+interface a person sees. It supports `claude`, `codex`, `opencode`, `agent`,
+`gemini`, and `qwen` without switching them to their JSON/headless modes:
+
+```javascript
+import { captureAgentTui } from 'agent-commander';
+
+const capture = await captureAgentTui({
+  tool: 'codex',
+  workingDirectory: '/tmp/project',
+  prompt: 'Inspect the failing test',
+  cols: 100,
+  rows: 30,
+  interactions: [
+    { after: 'Choose an option', key: 'DOWN' },
+    { after: 'Second option', key: 'ENTER' },
+    { after: 'Working', resize: { cols: 120, rows: 40 } },
+  ],
+  stopMarker: 'Finished',
+  artifactDirectory: 'artifacts/codex',
+});
+
+console.log(capture.transcript);
+console.log(capture.events); // normalized message and tool_call events
+```
+
+The result includes command-stream's unrolled transcript, settled frames, raw
+asciicast event stream, and normalized semantic events. The artifact directory
+contains `transcript.txt`, `frames.json`, `session.cast`, `snapshot.svg`, and
+the self-contained animated `recording.svg`. Partial artifacts are also written
+when the terminal command times out.
+
 For large generated prompts, pass `promptFile` or let the controller create a temporary prompt file automatically for `claude`, `codex`, `opencode`, `agent`, `qwen`, and `gemini`:
 
 ```javascript

js/package.json

@@ -46,9 +46,11 @@
   "author": "",
   "license": "Unlicense",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "command-stream": "^0.15.0"
   },
-  "dependencies": {},
   "devDependencies": {
     "@changesets/cli": "^2.29.7",
     "@eslint/js": "^9.35.0",

js/src/index.mjs

@@ -188,7 +188,7 @@
  * @param {Object} [options.toolOptions] - Additional tool-specific options
  * @returns {Object} Agent controller with start, stop, and utility methods
  */
 export function agent(options) {
   const {
     tool,
     workingDirectory,
@@ -287,7 +287,7 @@
    * @param {Function} [startOptions.onOutput] - Callback for raw output chunks
    * @returns {Promise<void>} Resolves when process is started (not when it exits)
    */
   const start = async (startOptions = {}) => {
     const {
       dryRun = false,
       detached = false,
@@ -448,7 +448,7 @@
    * @param {boolean} [stopOptions.dryRun] - If true, just show the command
    * @returns {Promise<Object>} Result with exitCode, output, session info, usage, and metadata
    */
   const stop = async (stopOptions = {}) => {
     const { dryRun = false } = stopOptions;
 
     // For isolation modes, send stop command
@@ -654,6 +654,11 @@
 export { JsonOutputStream, JsonInputStream } from './streaming/index.mjs';
 export { parseNdjsonLine, stringifyNdjsonLine } from './streaming/ndjson.mjs';
 export { buildNormalizedResultMetadata } from './result-metadata.mjs';
+export {
+  buildAgentTuiLaunch,
+  captureAgentTui,
+  normalizeTuiTranscript,
+} from './tui.mjs';
 export {
   ASK_SUPPORTED_TOOLS,
   ASK_DECISIONS,