From 41708c0f544a716b45f15fbfc8c8f6d56c072465 Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Wed, 15 Apr 2026 16:22:36 +0200
Subject: [PATCH 01/17] feat: add ai-transport demo command skeleton and
 dependencies

Add @ably/ai-transport SDK, Ink TUI framework, and command topic
structure for interactive AI Transport demos. The streaming demo
command is a placeholder with --role, --channel, --endpoint, and
--auth-endpoint flags. Bump ably to ^2.21.0 for SDK compatibility,
move get-port to runtime dependencies.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  89 +++++-
 package.json                                  |   7 +-
 pnpm-lock.yaml                                | 297 +++++++++++++++++-
 src/commands/ai-transport/demo/index.ts       |  14 +
 src/commands/ai-transport/demo/streaming.ts   |  60 ++++
 src/commands/ai-transport/index.ts            |  13 +
 .../ai-transport/demo/streaming.test.ts       | 103 ++++++
 7 files changed, 558 insertions(+), 25 deletions(-)
 create mode 100644 src/commands/ai-transport/demo/index.ts
 create mode 100644 src/commands/ai-transport/demo/streaming.ts
 create mode 100644 src/commands/ai-transport/index.ts
 create mode 100644 test/unit/commands/ai-transport/demo/streaming.test.ts

diff --git a/README.md b/README.md
index 9c27fc824..f5b5fe17a 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ $ npm install -g @ably/cli
 $ ably COMMAND
 running command...
 $ ably (--version)
-@ably/cli/0.17.0 darwin-arm64 node-v24.4.1
+@ably/cli/0.17.0 darwin-arm64 node-v22.14.0
 $ ably --help [COMMAND]
 USAGE
   $ ably COMMAND
@@ -76,6 +76,9 @@ $ ably-interactive
 * [`ably accounts login [TOKEN]`](#ably-accounts-login-token)
 * [`ably accounts logout [ALIAS]`](#ably-accounts-logout-alias)
 * [`ably accounts switch [ALIAS]`](#ably-accounts-switch-alias)
+* [`ably ai-transport`](#ably-ai-transport)
+* [`ably ai-transport demo`](#ably-ai-transport-demo)
+* [`ably ai-transport demo streaming`](#ably-ai-transport-demo-streaming)
 * [`ably apps`](#ably-apps)
 * [`ably apps create`](#ably-apps-create)
 * [`ably apps current`](#ably-apps-current)
@@ -382,6 +385,81 @@ EXAMPLES
 
 _See code: [src/commands/accounts/switch.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/accounts/switch.ts)_
 
+## `ably ai-transport`
+
+Interact with Ably AI Transport
+
+```
+USAGE
+  $ ably ai-transport
+
+DESCRIPTION
+  Interact with Ably AI Transport
+
+EXAMPLES
+  $ ably ai-transport demo streaming
+
+  $ ably ai-transport demo barge-in
+
+COMMANDS
+  ably ai-transport demo  Interactive demos of AI Transport features
+```
+
+_See code: [src/commands/ai-transport/index.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/ai-transport/index.ts)_
+
+## `ably ai-transport demo`
+
+Interactive demos of AI Transport features
+
+```
+USAGE
+  $ ably ai-transport demo
+
+DESCRIPTION
+  Interactive demos of AI Transport features
+
+EXAMPLES
+  $ ably ai-transport demo streaming
+
+  $ ably ai-transport demo barge-in
+
+  $ ably ai-transport demo cancel
+```
+
+_See code: [src/commands/ai-transport/demo/index.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/ai-transport/demo/index.ts)_
+
+## `ably ai-transport demo streaming`
+
+Demo AI Transport token streaming in a split-pane TUI
+
+```
+USAGE
+  $ ably ai-transport demo streaming [-v] [--json | --pretty-json] [--role both|client|server] [--channel <value>] [--endpoint
+    <value>] [--auth-endpoint <value>]
+
+FLAGS
+  -v, --verbose                Output verbose logs
+      --auth-endpoint=<value>  Auth endpoint returning JWT tokens (client-only, for external servers)
+      --channel=<value>        Channel name to use (auto-generated if not provided)
+      --endpoint=<value>       Server HTTP endpoint for sending messages (client-only, skips presence discovery)
+      --json                   Output in JSON format
+      --pretty-json            Output in colorized JSON format
+      --role=<option>          [default: both] Run as both client and server, or just one side
+                               <options: both|client|server>
+
+DESCRIPTION
+  Demo AI Transport token streaming in a split-pane TUI
+
+EXAMPLES
+  $ ably ai-transport demo streaming
+
+  $ ably ai-transport demo streaming --role client --channel my-session
+
+  $ ably ai-transport demo streaming --role server
+```
+
+_See code: [src/commands/ai-transport/demo/streaming.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/ai-transport/demo/streaming.ts)_
+
 ## `ably apps`
 
 Manage Ably apps
@@ -1421,8 +1499,8 @@ Delete an annotation from a channel message
 
 ```
 USAGE
-  $ ably channels annotations delete CHANNEL SERIAL TYPE [-v] [--json | --pretty-json] [--client-id <value>] [--count <value>]
-    [-n <value>]
+  $ ably channels annotations delete CHANNEL SERIAL TYPE [-v] [--json | --pretty-json] [--client-id <value>] [-n
+  <value>]
 
 ARGUMENTS
   CHANNEL  The channel name
@@ -1434,7 +1512,6 @@ FLAGS
   -v, --verbose            Output verbose logs
       --client-id=<value>  Overrides any default client ID when using API authentication. Use "none" to explicitly set
                            no client ID. Not applicable when using token authentication.
-      --count=<value>      The annotation count (for multiple.v1 types)
       --json               Output in JSON format
       --pretty-json        Output in colorized JSON format
 
@@ -1444,7 +1521,7 @@ DESCRIPTION
 EXAMPLES
   $ ably channels annotations delete my-channel "01234567890:0" "reactions:flag.v1" --name thumbsup
 
-  $ ably channels annotations delete my-channel "01234567890:0" "reactions:multiple.v1" --name thumbsup --count 2
+  $ ably channels annotations delete my-channel "01234567890:0" "reactions:multiple.v1" --name thumbsup
 
   $ ably channels annotations delete my-channel "01234567890:0" "reactions:flag.v1" --json
 
@@ -1468,7 +1545,7 @@ ARGUMENTS
 FLAGS
   -v, --verbose        Output verbose logs
       --json           Output in JSON format
-      --limit=<value>  [default: 50] Maximum number of results to return (default: 50)
+      --limit=<value>  [default: 100] Maximum number of results to return (default: 100)
       --pretty-json    Output in colorized JSON format
 
 DESCRIPTION
diff --git a/package.json b/package.json
index 0b9cff878..279a88e5e 100644
--- a/package.json
+++ b/package.json
@@ -110,6 +110,7 @@
     }
   },
   "dependencies": {
+    "@ably/ai-transport": "0.0.1",
     "@ably/chat": "^1.0.0",
     "@ably/spaces": "^0.4.0",
     "@inquirer/prompts": "^5.1.3",
@@ -119,11 +120,14 @@
     "@xterm/addon-fit": "^0.10.0",
     "@xterm/addon-web-links": "^0.11.0",
     "@xterm/xterm": "^5.5.0",
-    "ably": "^2.19.0",
+    "ably": "^2.21.0",
     "chalk": "5",
     "cli-table3": "^0.6.5",
     "color-json": "^3.0.5",
     "fast-levenshtein": "^3.0.0",
+    "get-port": "^7.2.0",
+    "ink": "^5.2.1",
+    "ink-text-input": "^6.0.0",
     "inquirer": "^9.2.16",
     "jsonwebtoken": "^9.0.2",
     "node-fetch": "^3.3.2",
@@ -162,7 +166,6 @@
     "eslint-plugin-unicorn": "^58.0.0",
     "execa": "^9.5.2",
     "fs-extra": "^11.3.0",
-    "get-port": "^7.1.0",
     "globals": "^15.15.0",
     "http-server": "^14.1.1",
     "nock": "^14.0.3",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 369d40189..1d8620c94 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -13,12 +13,15 @@ importers:
 
   .:
     dependencies:
+      '@ably/ai-transport':
+        specifier: 0.0.1
+        version: 0.0.1(ably@2.21.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(react@18.3.1)
       '@ably/chat':
         specifier: ^1.0.0
-        version: 1.0.0(ably@2.19.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 1.0.0(ably@2.21.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@ably/spaces':
         specifier: ^0.4.0
-        version: 0.4.0(ably@2.19.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        version: 0.4.0(ably@2.21.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@inquirer/prompts':
         specifier: ^5.1.3
         version: 5.5.0
@@ -41,8 +44,8 @@ importers:
         specifier: ^5.5.0
         version: 5.5.0
       ably:
-        specifier: ^2.19.0
-        version: 2.19.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+        specifier: ^2.21.0
+        version: 2.21.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       chalk:
         specifier: '5'
         version: 5.4.1
@@ -55,6 +58,15 @@ importers:
       fast-levenshtein:
         specifier: ^3.0.0
         version: 3.0.0
+      get-port:
+        specifier: ^7.2.0
+        version: 7.2.0
+      ink:
+        specifier: ^5.2.1
+        version: 5.2.1(@types/react@18.3.20)(react@18.3.1)
+      ink-text-input:
+        specifier: ^6.0.0
+        version: 6.0.0(ink@5.2.1(@types/react@18.3.20)(react@18.3.1))(react@18.3.1)
       inquirer:
         specifier: ^9.2.16
         version: 9.3.7
@@ -164,9 +176,6 @@ importers:
       fs-extra:
         specifier: ^11.3.0
         version: 11.3.0
-      get-port:
-        specifier: ^7.1.0
-        version: 7.1.0
       globals:
         specifier: ^15.15.0
         version: 15.15.0
@@ -352,6 +361,19 @@ importers:
 
 packages:
 
+  '@ably/ai-transport@0.0.1':
+    resolution: {integrity: sha512-oElB3ttr3KLvBD4k1gMQ1K68+7x3IcTampSs+f9yi66CIAKrUG4ioPtjdxjGU421jebLEXsqjazyqxLdOwIfRw==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      ably: ^2.21.0
+      ai: ^6
+      react: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      ai:
+        optional: true
+      react:
+        optional: true
+
   '@ably/chat@1.0.0':
     resolution: {integrity: sha512-001+DfhCFWTAD6CAZSltdIR9TMaznWsHOMyDN23vhPoFVGmM1nlXl9uTh3OE695pHfOrTuD/AqGC5J4qWYrrmA==}
     engines: {node: '>=20.0.0'}
@@ -383,6 +405,10 @@ packages:
   '@adobe/css-tools@4.4.2':
     resolution: {integrity: sha512-baYZExFpsdkBNuvGKTKWCwKH57HRZLVtycZS05WTQNVOiXVSeAki3nU35zlRbToeMW8aHlJfyS+1C4BOv27q0A==}
 
+  '@alcalzone/ansi-tokenize@0.1.3':
+    resolution: {integrity: sha512-3yWxPTq3UQ/FY9p1ErPxIyfT64elWaMvM9lIHnaqpyft63tkxodF5aUElYHrdisWve5cETkh1+KBw1yJuW0aRw==}
+    engines: {node: '>=14.13.1'}
+
   '@alloc/quick-lru@5.2.0':
     resolution: {integrity: sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw==}
     engines: {node: '>=10'}
@@ -2654,8 +2680,8 @@ packages:
     resolution: {integrity: sha512-AO2ac6pjRB3SJmGJo+v5/aK6Omggp6fsLrs6wN9bd35ulu4cCwaAU9+7ZhXjeqHVkaHThLuzH0nZr0YpCDhygg==}
     engines: {node: ^18.17.0 || >=20.5.0}
 
-  ably@2.19.0:
-    resolution: {integrity: sha512-uEgWf8p6UySLDFTO25S0fsd2ccwjB0hsuOV0EztVoxRhdsqSgnzCOmYSxUprVW5THlCLFA25tP9tIcj5G/XTVA==}
+  ably@2.21.0:
+    resolution: {integrity: sha512-Zgs3O/hqhnTEoXeV1WxoQeLaww58JbnDVFbVeEDj2kCHeuLPeavTbyf2NQBkxAM3jooN5mILaP0PDm79NOcpKw==}
     engines: {node: '>=16'}
     peerDependencies:
       react: '>=16.8.0'
@@ -2714,6 +2740,10 @@ packages:
     resolution: {integrity: sha512-gKXj5ALrKWQLsYG9jlTRmR/xKluxHV+Z9QEwNIgCfM1/uwPMCuzVVnh5mwTd+OuBZcwSIMbqssNWRm1lE51QaQ==}
     engines: {node: '>=8'}
 
+  ansi-escapes@7.3.0:
+    resolution: {integrity: sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg==}
+    engines: {node: '>=18'}
+
   ansi-regex@5.0.1:
     resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
     engines: {node: '>=8'}
@@ -2834,6 +2864,10 @@ packages:
   asynckit@0.4.0:
     resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==}
 
+  auto-bind@5.0.1:
+    resolution: {integrity: sha512-ooviqdwwgfIfNmDwo94wlshcdzfO64XV0Cg6oDsDYBJfITDz1EngD2z7DkbvCWn+XIMsIqW27sEVF6qcpJrRcg==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   autoprefixer@10.4.21:
     resolution: {integrity: sha512-O+A6LWV5LDHSJD3LjHYoNi4VLsj/Whi7k6zG12xTYaU4cQ8oxQGckXNX8cRHK5yOZ/ppVHe0ZBXGzSV9jXdVbQ==}
     engines: {node: ^10 || ^12 || >=14}
@@ -3035,6 +3069,10 @@ packages:
     resolution: {integrity: sha512-I/zHAwsKf9FqGoXM4WWRACob9+SNukZTd94DWF57E4toouRulbCxcUh6RKUEOQlYTHJnzkPMySvPNaaSLNfLZw==}
     engines: {node: '>=8'}
 
+  cli-cursor@4.0.0:
+    resolution: {integrity: sha512-VGtlMu3x/4DOtIUwEkRezxUZ2lBacNJCHash0N0WeZDBS+7Ux1dm3XWAgWYxLJFMMdOeXMHXorshEFhbMSGelg==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   cli-cursor@5.0.0:
     resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
     engines: {node: '>=18'}
@@ -3047,6 +3085,10 @@ packages:
     resolution: {integrity: sha512-+W/5efTR7y5HRD7gACw9yQjqMVvEMLBHmboM/kPWam+H+Hmyrgjh6YncVKK122YZkXrLudzTuAukUw9FnMf7IQ==}
     engines: {node: 10.* || >= 12.*}
 
+  cli-truncate@4.0.0:
+    resolution: {integrity: sha512-nPdaFdQ0h/GEigbPClz11D0v/ZJEwxmeVZGeMo3Z5StPtUTkA9o1lD6QwoirYiSDzbcwn2XcjwmCp68W1IS4TA==}
+    engines: {node: '>=18'}
+
   cli-width@4.1.0:
     resolution: {integrity: sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==}
     engines: {node: '>= 12'}
@@ -3069,6 +3111,10 @@ packages:
   code-block-writer@10.1.1:
     resolution: {integrity: sha512-67ueh2IRGst/51p0n6FvPrnRjAGHY5F8xdjkgrYE7DDzpJe6qA07RYQ9VcoUeo5ATOjSOiWpSL3SWBRRbempMw==}
 
+  code-excerpt@4.0.0:
+    resolution: {integrity: sha512-xxodCmBen3iy2i0WtAK8FlFNrRzjUqjRsMfho58xT/wvZU1YTM3fCnRjcy1gJPMepaRlgm/0e6w8SpWHpn3/cA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   color-convert@2.0.1:
     resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
     engines: {node: '>=7.0.0'}
@@ -3131,6 +3177,10 @@ packages:
   convert-source-map@2.0.0:
     resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
 
+  convert-to-spaces@2.0.1:
+    resolution: {integrity: sha512-rcQ1bsQO9799wq24uE5AM2tAILy4gXGIK/njFWcVQkGNZ96edlpY+A7bjwvzjYvLDyzmG1MmMLZhpcsb+klNMQ==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   core-js-compat@3.41.0:
     resolution: {integrity: sha512-RFsU9LySVue9RTwdDVX/T0e2Y6jRYWXERKElIjpuEOEnxaXffI0X7RUwVzfYLfzuLXSNJDYoRYUAmRUcyln20A==}
 
@@ -3351,6 +3401,10 @@ packages:
     resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==}
     engines: {node: '>=0.12'}
 
+  environment@1.1.0:
+    resolution: {integrity: sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==}
+    engines: {node: '>=18'}
+
   error-ex@1.3.2:
     resolution: {integrity: sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g==}
 
@@ -3395,6 +3449,9 @@ packages:
     resolution: {integrity: sha512-w+5mJ3GuFL+NjVtJlvydShqE1eN3h3PbI7/5LAsYJP/2qtuMXjfL2LpHSRqo4b4eSF5K/DH1JXKUAHSB2UW50g==}
     engines: {node: '>= 0.4'}
 
+  es-toolkit@1.45.1:
+    resolution: {integrity: sha512-/jhoOj/Fx+A+IIyDNOvO3TItGmlMKhtX8ISAHKE90c4b/k1tqaqEZ+uUqfpU8DMnW5cgNJv606zS55jGvza0Xw==}
+
   esbuild-android-64@0.14.47:
     resolution: {integrity: sha512-R13Bd9+tqLVFndncMHssZrPWe6/0Kpv2/dt4aA69soX4PRxlzsVpCvoJeFE8sOEoeVEiBkI0myjlkDodXlHa0g==}
     engines: {node: '>=12'}
@@ -3543,6 +3600,10 @@ packages:
     resolution: {integrity: sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==}
     engines: {node: '>=0.8.0'}
 
+  escape-string-regexp@2.0.0:
+    resolution: {integrity: sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==}
+    engines: {node: '>=8'}
+
   escape-string-regexp@4.0.0:
     resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
     engines: {node: '>=10'}
@@ -3989,6 +4050,10 @@ packages:
     resolution: {integrity: sha512-vpeMIQKxczTD/0s2CdEWHcb0eeJe6TFjxb+J5xgX7hScxqrGuyjmv4c1D4A/gelKfyox0gJJwIHF+fLjeaM8kQ==}
     engines: {node: '>=18'}
 
+  get-east-asian-width@1.5.0:
+    resolution: {integrity: sha512-CQ+bEO+Tva/qlmw24dCejulK5pMzVnUOFOijVogd3KQs07HnRIgp8TGipvCCRT06xeYEbpbgwaCxglFyiuIcmA==}
+    engines: {node: '>=18'}
+
   get-intrinsic@1.3.0:
     resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==}
     engines: {node: '>= 0.4'}
@@ -3997,8 +4062,8 @@ packages:
     resolution: {integrity: sha512-pjzuKtY64GYfWizNAJ0fr9VqttZkNiK2iS430LtIHzjBEr6bX8Am2zm4sW4Ro5wjWW5cAlRL1qAMTcXbjNAO2Q==}
     engines: {node: '>=8.0.0'}
 
-  get-port@7.1.0:
-    resolution: {integrity: sha512-QB9NKEeDg3xxVwCCwJQ9+xycaz6pBB6iQ76wiWMl1927n0Kir6alPiP+yuiICLLU4jpMe08dXfpebuQppFA2zw==}
+  get-port@7.2.0:
+    resolution: {integrity: sha512-afP4W205ONCuMoPBqcR6PSXnzX35KTcJygfJfcp+QY+uwm3p20p1YczWXhlICIzGMCxYBQcySEcOgsJcrkyobg==}
     engines: {node: '>=16'}
 
   get-proto@1.0.1:
@@ -4246,6 +4311,26 @@ packages:
   ini@1.3.8:
     resolution: {integrity: sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==}
 
+  ink-text-input@6.0.0:
+    resolution: {integrity: sha512-Fw64n7Yha5deb1rHY137zHTAbSTNelUKuB5Kkk2HACXEtwIHBCf9OH2tP/LQ9fRYTl1F0dZgbW0zPnZk6FA9Lw==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      ink: '>=5'
+      react: '>=18'
+
+  ink@5.2.1:
+    resolution: {integrity: sha512-BqcUyWrG9zq5HIwW6JcfFHsIYebJkWWb4fczNah1goUO0vv5vneIlfwuS85twyJ5hYR/y18FlAYUxrO9ChIWVg==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@types/react': '>=18.0.0'
+      react: '>=18.0.0'
+      react-devtools-core: ^4.19.1
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      react-devtools-core:
+        optional: true
+
   inquirer@9.3.7:
     resolution: {integrity: sha512-LJKFHCSeIRq9hanN14IlOtPSTe3lNES7TYDTE2xxdAy1LS5rYphajK1qtwvj3YmQXvvk0U2Vbmcni8P9EIQW9w==}
     engines: {node: '>=18'}
@@ -4326,6 +4411,14 @@ packages:
     resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==}
     engines: {node: '>=8'}
 
+  is-fullwidth-code-point@4.0.0:
+    resolution: {integrity: sha512-O4L094N2/dZ7xqVdrXhh9r1KODPJpFms8B5sGdJLPy664AgvXsreZUyCQQNItZRDlYug4xStLjNp/sz3HvBowQ==}
+    engines: {node: '>=12'}
+
+  is-fullwidth-code-point@5.1.0:
+    resolution: {integrity: sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ==}
+    engines: {node: '>=18'}
+
   is-generator-function@1.1.0:
     resolution: {integrity: sha512-nPUB5km40q9e8UfN/Zc24eLlzdSf9OfKByBw9CIdw4H1giPMeA0OIJvbchsCu4npfI2QcMVBsGEBHKZ7wLTWmQ==}
     engines: {node: '>= 0.4'}
@@ -4334,6 +4427,11 @@ packages:
     resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
     engines: {node: '>=0.10.0'}
 
+  is-in-ci@1.0.0:
+    resolution: {integrity: sha512-eUuAjybVTHMYWm/U+vBO1sY/JOCgoPCXRxzdju0K+K0BiGW0SChEL1MLC0PoCIR1OlPo5YAp8HuQoUlsWEICwg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   is-inside-container@1.0.0:
     resolution: {integrity: sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==}
     engines: {node: '>=14.16'}
@@ -5133,6 +5231,10 @@ packages:
   pascal-case@3.1.2:
     resolution: {integrity: sha512-uWlGT3YSnK9x3BQJaOdcZwrnV6hPpd8jFH1/ucpiLRPh/2zCVJKS19E4GvYHvaCcACn3foXZ0cLB9Wrx1KGe5g==}
 
+  patch-console@2.0.0:
+    resolution: {integrity: sha512-0YNdUceMdaQwoKce1gatDScmMo5pu/tfABfnzEqeG0gtTmd7mh/WcwgUjtAeOU7N8nFFlbQBnFK2gXW5fGvmMA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   path-browserify@1.0.1:
     resolution: {integrity: sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==}
 
@@ -5329,6 +5431,12 @@ packages:
   react-is@17.0.2:
     resolution: {integrity: sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==}
 
+  react-reconciler@0.29.2:
+    resolution: {integrity: sha512-zZQqIiYgDCTP/f1N/mAR10nJGrPD2ZR+jDSEsKWJHYC7Cm2wodlwbR3upZRdC3cjIjSlTLNVyO7Iu0Yy7t2AYg==}
+    engines: {node: '>=0.10.0'}
+    peerDependencies:
+      react: ^18.3.1
+
   react-refresh@0.17.0:
     resolution: {integrity: sha512-z6F7K9bV85EfseRCp2bzrpyQ0Gkw1uLoCel9XBVWPg/TjRj94SkJzUTGfOa4bs7iJvBWtQG0Wq7wnI0syw3EBQ==}
     engines: {node: '>=0.10.0'}
@@ -5445,6 +5553,10 @@ packages:
     resolution: {integrity: sha512-l+sSefzHpj5qimhFSE5a8nufZYAM3sBSVMAPtYkmC+4EH2anSGaEMXSD0izRQbu9nfyQ9y5JrVmp7E8oZrUjvA==}
     engines: {node: '>=8'}
 
+  restore-cursor@4.0.0:
+    resolution: {integrity: sha512-I9fPXU9geO9bHOt9pHHOhOkYerIMsmVaWB0rA2AI9ERh/+x/i7MV5HKBNrg+ljO5eoPVgCcnFuRjJ9uH6I/3eg==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   restore-cursor@5.1.0:
     resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
     engines: {node: '>=18'}
@@ -5623,6 +5735,14 @@ packages:
   slashes@3.0.12:
     resolution: {integrity: sha512-Q9VME8WyGkc7pJf6QEkj3wE+2CnvZMI+XJhwdTPR8Z/kWQRXi7boAWLDibRPyHRTUTPx5FaU7MsyrjI3yLB4HA==}
 
+  slice-ansi@5.0.0:
+    resolution: {integrity: sha512-FC+lgizVPfie0kkhqUScwRu1O/lF6NOgJmlCgK+/LYxDCTk8sGelYaHDhFcDN+Sn3Cv+3VSa4Byeo+IMCzpMgQ==}
+    engines: {node: '>=12'}
+
+  slice-ansi@7.1.2:
+    resolution: {integrity: sha512-iOBWFgUX7caIZiuutICxVgX1SdxwAVFFKwt1EvMYYec/NWO5meOJ6K5uQxhrYBdQJne4KxiqZc+KptFOWFSI9w==}
+    engines: {node: '>=18'}
+
   smol-toml@1.5.2:
     resolution: {integrity: sha512-QlaZEqcAH3/RtNyet1IPIYPsEWAaYyXXv1Krsi+1L/QHppjX4Ifm8MQsBISz9vE8cHicIq3clogsheili5vhaQ==}
     engines: {node: '>= 18'}
@@ -5664,6 +5784,10 @@ packages:
   stable-hash@0.0.5:
     resolution: {integrity: sha512-+L3ccpzibovGXFK+Ap/f8LOS0ahMrHTf3xu7mMLSpEGU0EO9ucaysSylKo9eRDFNhWve/y275iPmIZ4z39a9iA==}
 
+  stack-utils@2.0.6:
+    resolution: {integrity: sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ==}
+    engines: {node: '>=10'}
+
   stackback@0.0.2:
     resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
 
@@ -5795,6 +5919,7 @@ packages:
   tar@7.5.2:
     resolution: {integrity: sha512-7NyxrTE4Anh8km8iEy7o0QYPs+0JKBTj5ZaqHg6B39erLg0qYXN3BijtShwbsNSvQ+LN75+KV+C4QR/f6Gwnpg==}
     engines: {node: '>=18'}
+    deprecated: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
 
   thenify-all@1.6.0:
     resolution: {integrity: sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==}
@@ -6279,6 +6404,10 @@ packages:
     resolution: {integrity: sha512-o0cyEG0e8GPzT4iGHphIOh0cJOV8fivsXxddQasHPHfoZf1ZexrfeA21w2NaEN1RHE+fXlfISmOE8R9N3u3Qig==}
     engines: {node: '>=12'}
 
+  widest-line@5.0.0:
+    resolution: {integrity: sha512-c9bZp7b5YtRj2wOe6dlj32MK+Bx/M/d+9VB2SHM1OtsUHR0aV0tdP6DWh/iMt0kWi1t5g1Iudu6hQRNd1A4PVA==}
+    engines: {node: '>=18'}
+
   word-wrap@1.2.5:
     resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
     engines: {node: '>=0.10.0'}
@@ -6298,6 +6427,10 @@ packages:
     resolution: {integrity: sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==}
     engines: {node: '>=12'}
 
+  wrap-ansi@9.0.2:
+    resolution: {integrity: sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==}
+    engines: {node: '>=18'}
+
   wrappy@1.0.2:
     resolution: {integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==}
 
@@ -6343,14 +6476,23 @@ packages:
     resolution: {integrity: sha512-GQHQqAopRhwU8Kt1DDM8NjibDXHC8eoh1erhGAJPEyveY9qqVeXvVikNKrDz69sHowPMorbPUrH/mx8c50eiBQ==}
     engines: {node: '>=18'}
 
+  yoga-layout@3.2.1:
+    resolution: {integrity: sha512-0LPOt3AxKqMdFBZA3HBAt/t/8vIKq7VaQYbuA8WxCgung+p9TVyKRYdpvCb80HcdTN2NkbIKbhNwKUfm3tQywQ==}
+
   zod@3.24.3:
     resolution: {integrity: sha512-HhY1oqzWCQWuUqvBFnsyrtZRhyPeR7SUGv+C4+MsisMuVfSPx8HpwWqH8tRahSlt6M3PiFAcoeFhZAqIXTxoSg==}
 
 snapshots:
 
-  '@ably/chat@1.0.0(ably@2.19.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@ably/ai-transport@0.0.1(ably@2.21.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      ably: 2.21.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+    optionalDependencies:
+      react: 18.3.1
+
+  '@ably/chat@1.0.0(ably@2.21.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
-      ably: 2.19.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      ably: 2.21.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       async-mutex: 0.5.0
       dequal: 2.0.3
       lodash.clonedeep: 4.5.0
@@ -6364,9 +6506,9 @@ snapshots:
     dependencies:
       bops: 1.0.1
 
-  '@ably/spaces@0.4.0(ably@2.19.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+  '@ably/spaces@0.4.0(ably@2.21.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
-      ably: 2.19.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      ably: 2.21.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       nanoid: 3.3.11
     optionalDependencies:
       react: 18.3.1
@@ -6374,6 +6516,11 @@ snapshots:
 
   '@adobe/css-tools@4.4.2': {}
 
+  '@alcalzone/ansi-tokenize@0.1.3':
+    dependencies:
+      ansi-styles: 6.2.1
+      is-fullwidth-code-point: 4.0.0
+
   '@alloc/quick-lru@5.2.0': {}
 
   '@ampproject/remapping@2.3.0':
@@ -9080,7 +9227,7 @@ snapshots:
 
   abbrev@3.0.1: {}
 
-  ably@2.19.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+  ably@2.21.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
     dependencies:
       '@ably/msgpack-js': 0.4.0
       dequal: 2.0.3
@@ -9151,6 +9298,10 @@ snapshots:
     dependencies:
       type-fest: 0.21.3
 
+  ansi-escapes@7.3.0:
+    dependencies:
+      environment: 1.1.0
+
   ansi-regex@5.0.1: {}
 
   ansi-regex@6.1.0: {}
@@ -9278,6 +9429,8 @@ snapshots:
 
   asynckit@0.4.0: {}
 
+  auto-bind@5.0.1: {}
+
   autoprefixer@10.4.21(postcss@8.5.3):
     dependencies:
       browserslist: 4.24.4
@@ -9499,6 +9652,10 @@ snapshots:
     dependencies:
       restore-cursor: 3.1.0
 
+  cli-cursor@4.0.0:
+    dependencies:
+      restore-cursor: 4.0.0
+
   cli-cursor@5.0.0:
     dependencies:
       restore-cursor: 5.1.0
@@ -9511,6 +9668,11 @@ snapshots:
     optionalDependencies:
       '@colors/colors': 1.5.0
 
+  cli-truncate@4.0.0:
+    dependencies:
+      slice-ansi: 5.0.0
+      string-width: 7.2.0
+
   cli-width@4.1.0: {}
 
   clipboardy@3.0.0:
@@ -9529,6 +9691,10 @@ snapshots:
 
   code-block-writer@10.1.1: {}
 
+  code-excerpt@4.0.0:
+    dependencies:
+      convert-to-spaces: 2.0.1
+
   color-convert@2.0.1:
     dependencies:
       color-name: 1.1.4
@@ -9586,6 +9752,8 @@ snapshots:
 
   convert-source-map@2.0.0: {}
 
+  convert-to-spaces@2.0.1: {}
+
   core-js-compat@3.41.0:
     dependencies:
       browserslist: 4.24.4
@@ -9779,6 +9947,8 @@ snapshots:
 
   entities@4.5.0: {}
 
+  environment@1.1.0: {}
+
   error-ex@1.3.2:
     dependencies:
       is-arrayish: 0.2.1
@@ -9887,6 +10057,8 @@ snapshots:
       is-date-object: 1.1.0
       is-symbol: 1.1.1
 
+  es-toolkit@1.45.1: {}
+
   esbuild-android-64@0.14.47:
     optional: true
 
@@ -10060,6 +10232,8 @@ snapshots:
 
   escape-string-regexp@1.0.5: {}
 
+  escape-string-regexp@2.0.0: {}
+
   escape-string-regexp@4.0.0: {}
 
   eslint-compat-utils@0.5.1(eslint@9.34.0(jiti@2.4.2)):
@@ -10654,6 +10828,8 @@ snapshots:
 
   get-east-asian-width@1.3.0: {}
 
+  get-east-asian-width@1.5.0: {}
+
   get-intrinsic@1.3.0:
     dependencies:
       call-bind-apply-helpers: 1.0.2
@@ -10669,7 +10845,7 @@ snapshots:
 
   get-package-type@0.1.0: {}
 
-  get-port@7.1.0: {}
+  get-port@7.2.0: {}
 
   get-proto@1.0.1:
     dependencies:
@@ -10943,6 +11119,46 @@ snapshots:
 
   ini@1.3.8: {}
 
+  ink-text-input@6.0.0(ink@5.2.1(@types/react@18.3.20)(react@18.3.1))(react@18.3.1):
+    dependencies:
+      chalk: 5.4.1
+      ink: 5.2.1(@types/react@18.3.20)(react@18.3.1)
+      react: 18.3.1
+      type-fest: 4.40.0
+
+  ink@5.2.1(@types/react@18.3.20)(react@18.3.1):
+    dependencies:
+      '@alcalzone/ansi-tokenize': 0.1.3
+      ansi-escapes: 7.3.0
+      ansi-styles: 6.2.1
+      auto-bind: 5.0.1
+      chalk: 5.4.1
+      cli-boxes: 3.0.0
+      cli-cursor: 4.0.0
+      cli-truncate: 4.0.0
+      code-excerpt: 4.0.0
+      es-toolkit: 1.45.1
+      indent-string: 5.0.0
+      is-in-ci: 1.0.0
+      patch-console: 2.0.0
+      react: 18.3.1
+      react-reconciler: 0.29.2(react@18.3.1)
+      scheduler: 0.23.2
+      signal-exit: 3.0.7
+      slice-ansi: 7.1.2
+      stack-utils: 2.0.6
+      string-width: 7.2.0
+      type-fest: 4.40.0
+      widest-line: 5.0.0
+      wrap-ansi: 9.0.2
+      ws: 8.18.1
+      yoga-layout: 3.2.1
+    optionalDependencies:
+      '@types/react': 18.3.20
+    transitivePeerDependencies:
+      - bufferutil
+      - utf-8-validate
+
   inquirer@9.3.7:
     dependencies:
       '@inquirer/figures': 1.0.11
@@ -11032,6 +11248,12 @@ snapshots:
 
   is-fullwidth-code-point@3.0.0: {}
 
+  is-fullwidth-code-point@4.0.0: {}
+
+  is-fullwidth-code-point@5.1.0:
+    dependencies:
+      get-east-asian-width: 1.5.0
+
   is-generator-function@1.1.0:
     dependencies:
       call-bound: 1.0.4
@@ -11043,6 +11265,8 @@ snapshots:
     dependencies:
       is-extglob: 2.1.1
 
+  is-in-ci@1.0.0: {}
+
   is-inside-container@1.0.0:
     dependencies:
       is-docker: 3.0.0
@@ -11812,6 +12036,8 @@ snapshots:
       no-case: 3.0.4
       tslib: 2.8.1
 
+  patch-console@2.0.0: {}
+
   path-browserify@1.0.1: {}
 
   path-case@3.0.4:
@@ -11966,6 +12192,12 @@ snapshots:
 
   react-is@17.0.2: {}
 
+  react-reconciler@0.29.2(react@18.3.1):
+    dependencies:
+      loose-envify: 1.4.0
+      react: 18.3.1
+      scheduler: 0.23.2
+
   react-refresh@0.17.0: {}
 
   react@18.3.1:
@@ -12098,6 +12330,11 @@ snapshots:
       onetime: 5.1.2
       signal-exit: 3.0.7
 
+  restore-cursor@4.0.0:
+    dependencies:
+      onetime: 5.1.2
+      signal-exit: 3.0.7
+
   restore-cursor@5.1.0:
     dependencies:
       onetime: 7.0.0
@@ -12340,6 +12577,16 @@ snapshots:
 
   slashes@3.0.12: {}
 
+  slice-ansi@5.0.0:
+    dependencies:
+      ansi-styles: 6.2.1
+      is-fullwidth-code-point: 4.0.0
+
+  slice-ansi@7.1.2:
+    dependencies:
+      ansi-styles: 6.2.1
+      is-fullwidth-code-point: 5.1.0
+
   smol-toml@1.5.2: {}
 
   snake-case@3.0.4:
@@ -12387,6 +12634,10 @@ snapshots:
 
   stable-hash@0.0.5: {}
 
+  stack-utils@2.0.6:
+    dependencies:
+      escape-string-regexp: 2.0.0
+
   stackback@0.0.2: {}
 
   std-env@3.10.0: {}
@@ -13116,6 +13367,10 @@ snapshots:
     dependencies:
       string-width: 5.1.2
 
+  widest-line@5.0.0:
+    dependencies:
+      string-width: 7.2.0
+
   word-wrap@1.2.5: {}
 
   wordwrap@1.0.0: {}
@@ -13138,6 +13393,12 @@ snapshots:
       string-width: 5.1.2
       strip-ansi: 7.1.0
 
+  wrap-ansi@9.0.2:
+    dependencies:
+      ansi-styles: 6.2.1
+      string-width: 7.2.0
+      strip-ansi: 7.1.0
+
   wrappy@1.0.2: {}
 
   ws@8.18.1: {}
@@ -13158,4 +13419,6 @@ snapshots:
 
   yoctocolors@2.1.1: {}
 
+  yoga-layout@3.2.1: {}
+
   zod@3.24.3: {}
diff --git a/src/commands/ai-transport/demo/index.ts b/src/commands/ai-transport/demo/index.ts
new file mode 100644
index 000000000..845f4f0ae
--- /dev/null
+++ b/src/commands/ai-transport/demo/index.ts
@@ -0,0 +1,14 @@
+import { BaseTopicCommand } from "../../../base-topic-command.js";
+
+export default class AiTransportDemoIndex extends BaseTopicCommand {
+  protected topicName = "ai-transport:demo";
+  protected commandGroup = "AI Transport demo";
+
+  static override description = "Interactive demos of AI Transport features";
+
+  static override examples = [
+    "<%= config.bin %> <%= command.id %> streaming",
+    "<%= config.bin %> <%= command.id %> barge-in",
+    "<%= config.bin %> <%= command.id %> cancel",
+  ];
+}
diff --git a/src/commands/ai-transport/demo/streaming.ts b/src/commands/ai-transport/demo/streaming.ts
new file mode 100644
index 000000000..37df83785
--- /dev/null
+++ b/src/commands/ai-transport/demo/streaming.ts
@@ -0,0 +1,60 @@
+import { Flags } from "@oclif/core";
+
+import { ControlBaseCommand } from "../../../control-base-command.js";
+import { productApiFlags } from "../../../flags.js";
+
+export default class StreamingDemo extends ControlBaseCommand {
+  static override description =
+    "Demo AI Transport token streaming in a split-pane TUI";
+
+  static override examples = [
+    "<%= config.bin %> <%= command.id %>",
+    "<%= config.bin %> <%= command.id %> --role client --channel my-session",
+    "<%= config.bin %> <%= command.id %> --role server",
+  ];
+
+  static override flags = {
+    ...productApiFlags,
+    role: Flags.string({
+      description: "Run as both client and server, or just one side",
+      options: ["both", "client", "server"],
+      default: "both",
+    }),
+    channel: Flags.string({
+      description: "Channel name to use (auto-generated if not provided)",
+    }),
+    endpoint: Flags.string({
+      description:
+        "Server HTTP endpoint for sending messages (client-only, skips presence discovery)",
+    }),
+    "auth-endpoint": Flags.string({
+      description:
+        "Auth endpoint returning JWT tokens (client-only, for external servers)",
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(StreamingDemo);
+
+    if (flags.endpoint && flags.role !== "client") {
+      this.fail(
+        "--endpoint can only be used with --role client",
+        flags,
+        "aiTransportDemo",
+      );
+    }
+
+    if (flags["auth-endpoint"] && flags.role !== "client") {
+      this.fail(
+        "--auth-endpoint can only be used with --role client",
+        flags,
+        "aiTransportDemo",
+      );
+    }
+
+    this.log(
+      "AI Transport Streaming Demo (coming soon). " +
+        `Role: ${flags.role}, Channel: ${flags.channel ?? "(auto)"}`,
+    );
+  }
+}
diff --git a/src/commands/ai-transport/index.ts b/src/commands/ai-transport/index.ts
new file mode 100644
index 000000000..ce0d09bfd
--- /dev/null
+++ b/src/commands/ai-transport/index.ts
@@ -0,0 +1,13 @@
+import { BaseTopicCommand } from "../../base-topic-command.js";
+
+export default class AiTransportIndex extends BaseTopicCommand {
+  protected topicName = "ai-transport";
+  protected commandGroup = "AI Transport";
+
+  static override description = "Interact with Ably AI Transport";
+
+  static override examples = [
+    "<%= config.bin %> <%= command.id %> demo streaming",
+    "<%= config.bin %> <%= command.id %> demo barge-in",
+  ];
+}
diff --git a/test/unit/commands/ai-transport/demo/streaming.test.ts b/test/unit/commands/ai-transport/demo/streaming.test.ts
new file mode 100644
index 000000000..f5c48d754
--- /dev/null
+++ b/test/unit/commands/ai-transport/demo/streaming.test.ts
@@ -0,0 +1,103 @@
+import { describe, it, expect } from "vitest";
+import { runCommand } from "@oclif/test";
+import {
+  standardHelpTests,
+  standardArgValidationTests,
+  standardFlagTests,
+} from "../../../../helpers/standard-tests.js";
+
+describe("ai-transport:demo:streaming command", () => {
+  standardHelpTests("ai-transport:demo:streaming", import.meta.url);
+  standardArgValidationTests("ai-transport:demo:streaming", import.meta.url);
+  standardFlagTests("ai-transport:demo:streaming", import.meta.url, [
+    "--role",
+    "--channel",
+    "--endpoint",
+    "--auth-endpoint",
+    "--json",
+  ]);
+
+  describe("functionality", () => {
+    it("should display demo message with default role", async () => {
+      const { stdout } = await runCommand(
+        ["ai-transport:demo:streaming"],
+        import.meta.url,
+      );
+
+      expect(stdout).toContain("Streaming Demo");
+      expect(stdout).toContain("Role: both");
+    });
+
+    it("should accept role flag", async () => {
+      const { stdout } = await runCommand(
+        ["ai-transport:demo:streaming", "--role", "client"],
+        import.meta.url,
+      );
+
+      expect(stdout).toContain("Role: client");
+    });
+
+    it("should accept channel flag", async () => {
+      const { stdout } = await runCommand(
+        ["ai-transport:demo:streaming", "--channel", "test-channel"],
+        import.meta.url,
+      );
+
+      expect(stdout).toContain("Channel: test-channel");
+    });
+  });
+
+  describe("flags", () => {
+    it("should reject --endpoint without --role client", async () => {
+      const { error } = await runCommand(
+        ["ai-transport:demo:streaming", "--endpoint", "http://localhost:3000"],
+        import.meta.url,
+      );
+
+      expect(error?.message).toContain(
+        "--endpoint can only be used with --role client",
+      );
+    });
+
+    it("should reject --auth-endpoint without --role client", async () => {
+      const { error } = await runCommand(
+        [
+          "ai-transport:demo:streaming",
+          "--auth-endpoint",
+          "http://localhost:3000/auth",
+        ],
+        import.meta.url,
+      );
+
+      expect(error?.message).toContain(
+        "--auth-endpoint can only be used with --role client",
+      );
+    });
+
+    it("should accept --endpoint with --role client", async () => {
+      const { stdout } = await runCommand(
+        [
+          "ai-transport:demo:streaming",
+          "--role",
+          "client",
+          "--endpoint",
+          "http://localhost:3000",
+        ],
+        import.meta.url,
+      );
+
+      expect(stdout).toContain("Role: client");
+    });
+  });
+
+  describe("error handling", () => {
+    it("should reject invalid role values", async () => {
+      const { error } = await runCommand(
+        ["ai-transport:demo:streaming", "--role", "invalid"],
+        import.meta.url,
+      );
+
+      expect(error).toBeDefined();
+    });
+  });
+});

From 7869d87f7b756c60f6c7b9cdb8847759c5daf20f Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Wed, 15 Apr 2026 17:52:35 +0200
Subject: [PATCH 02/17] feat: add fake LLM, demo codec, and mutable messages
 detection

Core library modules for AI Transport demos:
- Fake LLM stream generator with bursty pacing and abort support
- Demo codec implementing full @ably/ai-transport Codec interface
  using createEncoderCore/createDecoderCore helpers
- Mutable messages detection via Control API and data plane fallback
  (error 93002)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/commands/ai-transport/demo/lib/codec.ts   | 252 ++++++++++++++++++
 .../ai-transport/demo/lib/fake-llm.ts         | 161 +++++++++++
 .../ai-transport/demo/lib/mutable-messages.ts | 153 +++++++++++
 .../demo/lib/responses/streaming.ts           |  33 +++
 .../ai-transport/demo/lib/codec.test.ts       | 122 +++++++++
 .../ai-transport/demo/lib/fake-llm.test.ts    | 139 ++++++++++
 .../demo/lib/mutable-messages.test.ts         | 172 ++++++++++++
 7 files changed, 1032 insertions(+)
 create mode 100644 src/commands/ai-transport/demo/lib/codec.ts
 create mode 100644 src/commands/ai-transport/demo/lib/fake-llm.ts
 create mode 100644 src/commands/ai-transport/demo/lib/mutable-messages.ts
 create mode 100644 src/commands/ai-transport/demo/lib/responses/streaming.ts
 create mode 100644 test/unit/commands/ai-transport/demo/lib/codec.test.ts
 create mode 100644 test/unit/commands/ai-transport/demo/lib/fake-llm.test.ts
 create mode 100644 test/unit/commands/ai-transport/demo/lib/mutable-messages.test.ts

diff --git a/src/commands/ai-transport/demo/lib/codec.ts b/src/commands/ai-transport/demo/lib/codec.ts
new file mode 100644
index 000000000..da75233b3
--- /dev/null
+++ b/src/commands/ai-transport/demo/lib/codec.ts
@@ -0,0 +1,252 @@
+/**
+ * Demo codec for the AI Transport demo commands.
+ *
+ * Maps between the demo's domain types (FakeLLMEvent, DemoMessage)
+ * and the Ably wire format using the @ably/ai-transport codec helpers.
+ */
+
+import {
+  createEncoderCore,
+  createDecoderCore,
+} from "@ably/ai-transport";
+import type {
+  Codec,
+  StreamEncoder,
+  StreamDecoder,
+  MessageAccumulator,
+  DecoderOutput,
+  EncoderOptions,
+  WriteOptions,
+  ChannelWriter,
+  DecoderCoreHooks,
+  StreamTrackerState,
+} from "@ably/ai-transport";
+import type * as Ably from "ably";
+
+import type { FakeLLMEvent } from "./fake-llm.js";
+
+/** A message in the demo conversation. */
+export interface DemoMessage {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+}
+
+/** The message name used for assistant text streams on the wire. */
+const STREAM_NAME = "assistant-text";
+
+/** The message name used for discrete user messages on the wire. */
+const USER_MESSAGE_NAME = "user-message";
+
+// ── Encoder ──────────────────────────────────────────────────────
+
+function createDemoEncoder(
+  channel: ChannelWriter,
+  options?: EncoderOptions,
+): StreamEncoder<FakeLLMEvent, DemoMessage> {
+  const core = createEncoderCore(channel, {
+    clientId: options?.clientId,
+  });
+  let activeStreamId: string | null = null;
+
+  return {
+    async writeMessages(
+      messages: DemoMessage[],
+      opts?: WriteOptions,
+    ): Promise<Ably.PublishResult> {
+      return core.publishDiscreteBatch(
+        messages.map((m) => ({
+          name: USER_MESSAGE_NAME,
+          data: JSON.stringify({ id: m.id, role: m.role, content: m.content }),
+        })),
+        opts,
+      );
+    },
+
+    async writeEvent(
+      event: FakeLLMEvent,
+      opts?: WriteOptions,
+    ): Promise<Ably.PublishResult> {
+      return core.publishDiscrete(
+        {
+          name: STREAM_NAME,
+          data: JSON.stringify(event),
+        },
+        opts,
+      );
+    },
+
+    async appendEvent(event: FakeLLMEvent, opts?: WriteOptions): Promise<void> {
+      if (event.type === "text-delta") {
+        if (!activeStreamId) {
+          // Start a new stream for the first delta
+          activeStreamId = `stream-${Date.now()}`;
+          await core.startStream(activeStreamId, {
+            name: STREAM_NAME,
+            data: event.text,
+          }, opts);
+        } else {
+          core.appendStream(activeStreamId, event.text);
+        }
+      } else if (event.type === "finish") {
+        if (activeStreamId) {
+          await core.closeStream(activeStreamId, {
+            name: STREAM_NAME,
+            data: "",
+          });
+          activeStreamId = null;
+        }
+      }
+    },
+
+    async abort(reason?: string): Promise<void> {
+      if (activeStreamId) {
+        await core.abortStream(activeStreamId);
+        activeStreamId = null;
+      } else {
+        await core.abortAllStreams();
+      }
+    },
+
+    async close(): Promise<void> {
+      await core.close();
+      activeStreamId = null;
+    },
+  };
+}
+
+// ── Decoder ──────────────────────────────────────────────────────
+
+function createDemoDecoder(): StreamDecoder<FakeLLMEvent, DemoMessage> {
+  const hooks: DecoderCoreHooks<FakeLLMEvent, DemoMessage> = {
+    buildStartEvents(
+      tracker: StreamTrackerState,
+    ): DecoderOutput<FakeLLMEvent, DemoMessage>[] {
+      // Emit a text-delta for the initial data from startStream
+      if (tracker.accumulated) {
+        return [
+          {
+            kind: "event",
+            event: { type: "text-delta", text: tracker.accumulated },
+            messageId: tracker.streamId,
+          },
+        ];
+      }
+
+      return [];
+    },
+
+    buildDeltaEvents(
+      tracker: StreamTrackerState,
+      delta: string,
+    ): DecoderOutput<FakeLLMEvent, DemoMessage>[] {
+      return [
+        {
+          kind: "event",
+          event: { type: "text-delta", text: delta },
+          messageId: tracker.streamId,
+        },
+      ];
+    },
+
+    buildEndEvents(
+      tracker: StreamTrackerState,
+    ): DecoderOutput<FakeLLMEvent, DemoMessage>[] {
+      return [
+        {
+          kind: "event",
+          event: { type: "finish" },
+          messageId: tracker.streamId,
+        },
+        {
+          kind: "message",
+          message: {
+            id: tracker.streamId,
+            role: "assistant",
+            content: tracker.accumulated,
+          },
+        },
+      ];
+    },
+
+    decodeDiscrete(payload): DecoderOutput<FakeLLMEvent, DemoMessage>[] {
+      if (payload.name === USER_MESSAGE_NAME) {
+        const data = JSON.parse(payload.data as string) as DemoMessage;
+        return [{ kind: "message", message: data }];
+      }
+
+      return [];
+    },
+  };
+
+  const core = createDecoderCore<FakeLLMEvent, DemoMessage>(hooks);
+  return { decode: (msg) => core.decode(msg) };
+}
+
+// ── Accumulator ──────────────────────────────────────────────────
+
+function createDemoAccumulator(): MessageAccumulator<FakeLLMEvent, DemoMessage> {
+  const messagesMap = new Map<string, DemoMessage>();
+  const activeStreams = new Set<string>();
+  const completedIds = new Set<string>();
+
+  return {
+    processOutputs(
+      outputs: DecoderOutput<FakeLLMEvent, DemoMessage>[],
+    ): void {
+      for (const output of outputs) {
+        if (output.kind === "message") {
+          const msg = output.message;
+          messagesMap.set(msg.id, msg);
+          activeStreams.delete(msg.id);
+          completedIds.add(msg.id);
+        } else if (output.kind === "event" && output.messageId) {
+          const event = output.event;
+          if (event.type === "text-delta") {
+            const existing = messagesMap.get(output.messageId);
+            if (existing) {
+              existing.content += event.text;
+            } else {
+              messagesMap.set(output.messageId, {
+                id: output.messageId,
+                role: "assistant",
+                content: event.text,
+              });
+              activeStreams.add(output.messageId);
+            }
+          } else if (event.type === "finish") {
+            activeStreams.delete(output.messageId);
+            completedIds.add(output.messageId);
+          }
+        }
+      }
+    },
+
+    updateMessage(message: DemoMessage): void {
+      messagesMap.set(message.id, message);
+    },
+
+    get messages(): DemoMessage[] {
+      return [...messagesMap.values()];
+    },
+
+    get completedMessages(): DemoMessage[] {
+      return [...messagesMap.values()].filter((m) => completedIds.has(m.id));
+    },
+
+    get hasActiveStream(): boolean {
+      return activeStreams.size > 0;
+    },
+  };
+}
+
+// ── Codec ────────────────────────────────────────────────────────
+
+/** The demo codec for AI Transport demos. */
+export const DemoCodec: Codec<FakeLLMEvent, DemoMessage> = {
+  createEncoder: createDemoEncoder,
+  createDecoder: createDemoDecoder,
+  createAccumulator: createDemoAccumulator,
+  isTerminal: (event: FakeLLMEvent): boolean => event.type === "finish",
+  getMessageKey: (message: DemoMessage): string => message.id,
+};
diff --git a/src/commands/ai-transport/demo/lib/fake-llm.ts b/src/commands/ai-transport/demo/lib/fake-llm.ts
new file mode 100644
index 000000000..b7a4103b5
--- /dev/null
+++ b/src/commands/ai-transport/demo/lib/fake-llm.ts
@@ -0,0 +1,161 @@
+/**
+ * Fake LLM token generator for AI Transport demos.
+ *
+ * Produces a ReadableStream of text tokens with realistic pacing.
+ * Each demo feature has its own response bank with contextually
+ * relevant text. No real LLM is used.
+ */
+
+import {
+  streamingResponses,
+  shortStreamingResponses,
+  longStreamingResponses,
+} from "./responses/streaming.js";
+
+export interface FakeLLMOptions {
+  /** Which demo feature is running (selects response bank). */
+  feature: string;
+  /** The user's message (for keyword matching). */
+  userMessage: string;
+  /** Override the base delay between tokens in ms (default ~40ms). */
+  baseDelayMs?: number;
+  /** AbortSignal to cancel generation early. */
+  signal?: AbortSignal;
+}
+
+/** A single token event from the fake LLM. */
+export type FakeLLMEvent =
+  | { type: "text-delta"; text: string }
+  | { type: "finish" };
+
+/**
+ * Tokenize a string into word-level tokens, preserving spaces.
+ * Each token is a word followed by a space (except possibly the last).
+ */
+function tokenize(text: string): string[] {
+  const words = text.split(/(\s+)/);
+  const tokens: string[] = [];
+  for (const word of words) {
+    if (word.length > 0) {
+      tokens.push(word);
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Select a response based on the feature and user message.
+ */
+function selectResponse(feature: string, userMessage: string): string {
+  const lower = userMessage.toLowerCase();
+
+  // Check for length hints
+  if (lower.includes("short") || lower.includes("brief")) {
+    const bank = getShortResponseBank(feature);
+    return bank[Math.floor(Math.random() * bank.length)];
+  }
+
+  if (lower.includes("long") || lower.includes("detailed")) {
+    const bank = getLongResponseBank(feature);
+    return bank[Math.floor(Math.random() * bank.length)];
+  }
+
+  // Default: pick a random response from the feature bank
+  const bank = getResponseBank(feature);
+  return bank[Math.floor(Math.random() * bank.length)];
+}
+
+function getResponseBank(feature: string): string[] {
+  switch (feature) {
+    case "streaming":
+      return streamingResponses;
+    // Future features will have their own banks
+    default:
+      return streamingResponses;
+  }
+}
+
+function getShortResponseBank(feature: string): string[] {
+  switch (feature) {
+    case "streaming":
+      return shortStreamingResponses;
+    default:
+      return shortStreamingResponses;
+  }
+}
+
+function getLongResponseBank(feature: string): string[] {
+  switch (feature) {
+    case "streaming":
+      return longStreamingResponses;
+    default:
+      return longStreamingResponses;
+  }
+}
+
+/**
+ * Compute a delay with realistic burstiness.
+ * Real LLMs produce tokens in bursts rather than at a uniform rate.
+ */
+function computeDelay(baseMs: number): number {
+  // 70% chance of fast (burst), 30% chance of slower (pause)
+  if (Math.random() < 0.7) {
+    return baseMs * (0.3 + Math.random() * 0.7); // 30-100% of base
+  }
+
+  return baseMs * (1.5 + Math.random() * 2.0); // 150-350% of base (pause)
+}
+
+/**
+ * Create a ReadableStream of fake LLM events.
+ *
+ * The stream emits text-delta events (one per token) followed by
+ * a single finish event. Tokens are delivered with realistic pacing.
+ */
+export function createFakeLLMStream(
+  options: FakeLLMOptions,
+): ReadableStream<FakeLLMEvent> {
+  const { feature, userMessage, baseDelayMs = 40, signal } = options;
+  const responseText = selectResponse(feature, userMessage);
+  const tokens = tokenize(responseText);
+
+  return new ReadableStream<FakeLLMEvent>({
+    async start(controller) {
+      for (const token of tokens) {
+        if (signal?.aborted) {
+          controller.close();
+          return;
+        }
+
+        controller.enqueue({ type: "text-delta", text: token });
+
+        const delay = computeDelay(baseDelayMs);
+        await new Promise<void>((resolve, reject) => {
+          const timer = setTimeout(resolve, delay);
+          if (signal) {
+            const onAbort = () => {
+              clearTimeout(timer);
+              reject(new DOMException("Aborted", "AbortError"));
+            };
+
+            signal.addEventListener("abort", onAbort, { once: true });
+          }
+        }).catch((error: unknown) => {
+          if (
+            error instanceof DOMException &&
+            error.name === "AbortError"
+          ) {
+            controller.close();
+            return;
+          }
+
+          throw error;
+        });
+      }
+
+      controller.enqueue({ type: "finish" });
+      controller.close();
+    },
+  });
+}
diff --git a/src/commands/ai-transport/demo/lib/mutable-messages.ts b/src/commands/ai-transport/demo/lib/mutable-messages.ts
new file mode 100644
index 000000000..1ca6db409
--- /dev/null
+++ b/src/commands/ai-transport/demo/lib/mutable-messages.ts
@@ -0,0 +1,153 @@
+/**
+ * Mutable messages detection for AI Transport demos.
+ *
+ * AI Transport requires mutable messages to be enabled on the channel
+ * namespace. This module provides two detection paths:
+ *
+ * Path 1 (Control API): Check namespace config via the Control API.
+ *   Requires an access token (from `ably login`).
+ *
+ * Path 2 (Data plane): Publish a test message and attempt to annotate it.
+ *   If error 93002 is returned, mutable messages is not enabled.
+ *   Works with just an API key.
+ */
+
+import type { ControlApi, Namespace } from "../../../../services/control-api.js";
+import type * as Ably from "ably";
+
+/** Error code returned when mutable messages is not enabled. */
+const MUTABLE_MESSAGES_ERROR_CODE = 93002;
+
+export interface MutableMessagesCheckResult {
+  enabled: boolean;
+  method: "control-api" | "data-plane";
+}
+
+/**
+ * Extract the namespace prefix from a channel name.
+ * For "ai-demo:streaming-abc", returns "ai-demo".
+ * For "streaming-abc" (no colon), returns "" (default namespace).
+ */
+export function extractNamespace(channelName: string): string {
+  const colonIndex = channelName.indexOf(":");
+  if (colonIndex === -1) return "";
+  return channelName.slice(0, colonIndex);
+}
+
+/**
+ * Check if mutable messages is enabled via the Control API.
+ * Returns null if Control API is not available.
+ */
+export async function checkViaControlApi(
+  controlApi: ControlApi,
+  appId: string,
+  namespace: string,
+): Promise<MutableMessagesCheckResult | null> {
+  try {
+    const namespaces: Namespace[] =
+      await controlApi.listNamespaces(appId);
+    const match = namespaces.find((ns) => ns.id === namespace);
+
+    if (!match) {
+      // Namespace doesn't exist at all — mutable messages is not enabled
+      return { enabled: false, method: "control-api" };
+    }
+
+    return {
+      enabled: match.mutableMessages === true,
+      method: "control-api",
+    };
+  } catch {
+    // Control API not available (no token, network error, etc.)
+    return null;
+  }
+}
+
+/**
+ * Check if mutable messages is enabled via a data plane smoke test.
+ * Publishes a test message then tries to append to it (which requires
+ * mutable messages). Error 93002 means mutable messages is not enabled.
+ */
+export async function checkViaDataPlane(
+  channel: Ably.RealtimeChannel,
+): Promise<MutableMessagesCheckResult> {
+  try {
+    // Publish a test message
+    const testMessageName = "__ait-demo-mutable-check__";
+    await channel.publish(testMessageName, "test");
+
+    // Try to append to it — this requires mutable messages
+    try {
+      await channel.appendMessage(
+        { name: testMessageName, data: "append-test" },
+      );
+    } catch (error: unknown) {
+      if (isAblyError(error, MUTABLE_MESSAGES_ERROR_CODE)) {
+        return { enabled: false, method: "data-plane" };
+      }
+
+      // Some other error — could be permissions, missing message, etc.
+      // Default to assuming it might work (let the real operation fail
+      // with a better error)
+      return { enabled: true, method: "data-plane" };
+    }
+
+    return { enabled: true, method: "data-plane" };
+  } catch (error: unknown) {
+    if (isAblyError(error, MUTABLE_MESSAGES_ERROR_CODE)) {
+      return { enabled: false, method: "data-plane" };
+    }
+
+    // Can't determine — assume it works and let the real operation fail
+    return { enabled: true, method: "data-plane" };
+  }
+}
+
+/**
+ * Enable mutable messages on a namespace via the Control API.
+ */
+export async function enableMutableMessages(
+  controlApi: ControlApi,
+  appId: string,
+  namespace: string,
+): Promise<void> {
+  const namespaces = await controlApi.listNamespaces(appId);
+  const existing = namespaces.find((ns) => ns.id === namespace);
+
+  if (existing) {
+    // Update existing namespace
+    await controlApi.updateNamespace(appId, namespace, {
+      mutableMessages: true,
+      persisted: true, // Required when mutableMessages is enabled
+    });
+  } else {
+    // Create new namespace
+    await controlApi.createNamespace(appId, {
+      id: namespace,
+      mutableMessages: true,
+      persisted: true,
+    });
+  }
+}
+
+function isAblyError(error: unknown, code: number): boolean {
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code: number }).code === code
+  ) {
+    return true;
+  }
+
+  // Check nested statusCode / code patterns
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "cause" in error
+  ) {
+    return isAblyError((error as { cause: unknown }).cause, code);
+  }
+
+  return false;
+}
diff --git a/src/commands/ai-transport/demo/lib/responses/streaming.ts b/src/commands/ai-transport/demo/lib/responses/streaming.ts
new file mode 100644
index 000000000..ee27f62c3
--- /dev/null
+++ b/src/commands/ai-transport/demo/lib/responses/streaming.ts
@@ -0,0 +1,33 @@
+/**
+ * Response bank for the streaming demo.
+ * Each response is a string that gets tokenized word-by-word for streaming.
+ * These responses are self-aware and reference the streaming infrastructure.
+ */
+
+export const streamingResponses: string[] = [
+  "Right now, each word you see is traveling as a separate token through Ably's global messaging infrastructure. The server published it to an Ably channel, and your client picked it up in real time via a persistent WebSocket connection. This is fundamentally different from a typical HTTP response body, because the stream lives on the channel, not on the connection. If your connection dropped right now and reconnected, you'd pick up exactly where you left off. That's what makes this a durable transport layer rather than just another streaming API. The tokens persist on the channel, so nothing is lost even if the network blips. Pretty neat for something that looks like a simple chat, right?",
+
+  "Let me tell you about what's happening behind the scenes while I stream this response. The server received your message via an HTTP POST, just like a normal API call. But instead of streaming the response back over that same HTTP connection, it's publishing tokens to an Ably channel. Your client is subscribed to that channel and renders each token as it arrives. This decoupling is the whole point of AI Transport. The response doesn't depend on the HTTP connection staying alive. Multiple clients could subscribe to the same channel and see this response simultaneously. The server doesn't even need to know how many clients are listening.",
+
+  "I'm a fake language model, but I'm streaming through the exact same infrastructure a real one would use. Each token goes through Ably's edge network, which spans over 600 points of presence globally. The median delivery latency is under 50 milliseconds, which is why this feels instantaneous even though every token is making a round trip through the cloud. In production, you'd replace me with Claude, GPT, or any other model, and the transport layer would work identically. The AI Transport SDK handles the protocol, the turn lifecycle, the streaming, and the recovery. Your application code just publishes events and subscribes to them.",
+
+  "Here's something interesting about the architecture you're seeing in action. This demo has a real HTTP server running locally on your machine, and a real Ably channel connecting the server transport to the client transport. The server entered presence on the channel to announce itself, and the client discovered it automatically. When you typed your message, the client POSTed it to the server's HTTP endpoint. The server then started a new turn, began streaming tokens through the AI Transport SDK, and here we are. Every piece of this is the real protocol, exercised end to end. The only fake part is me, the language model.",
+
+  "Welcome to the streaming demo. What you're witnessing is AI Transport's core capability: durable token streaming over Ably channels. Each word I produce is published as a message operation on the channel. The Ably SDK handles message ordering, delivery guarantees, and connection management. If I were a real AI model, I might be generating tokens for thirty seconds or more. During that time, network conditions could change, connections might drop and reconnect, or you might switch devices entirely. The transport layer handles all of that transparently. The stream just keeps flowing, picking up where it left off after any interruption.",
+];
+
+/**
+ * Short responses for when the user asks for something brief.
+ */
+export const shortStreamingResponses: string[] = [
+  "Short and sweet. Each of these tokens traveled through Ably's infrastructure to reach you. That's AI Transport in action.",
+  "Quick response! But every word still went through the full transport pipeline: server published to Ably channel, client subscribed and rendered. Real infrastructure, real protocol.",
+  "Brief as requested. Even this short message exercises the full AI Transport stack end to end.",
+];
+
+/**
+ * Responses for when the user asks for something long.
+ */
+export const longStreamingResponses: string[] = [
+  "You asked for a long response, so let me take this opportunity to really dig into what's happening at every layer of the stack while I stream this to you. Starting at the top: you typed a message and hit enter. The client component captured that input and made an HTTP POST request to the demo server running on localhost. The server received that request, parsed the message body, and created a new turn using the AI Transport SDK's server transport. A turn is the fundamental unit of a request-response cycle in the AI Transport protocol. It has a unique ID, a lifecycle with start and end events, and an abort signal that fires if the client cancels. The server published a turn-start event to the Ably channel, signaling to all subscribers that a response is incoming. Then the server began streaming tokens. Each token is published as a message append operation on the channel. This is where Ably's mutable messages feature comes in. The response message starts as an empty message on the channel, and each token appends to it. The channel maintains the full accumulated state, so if a new client subscribes mid-stream, it receives the complete response so far and then continues receiving live updates. This is what makes the stream resumable. On the client side, the AI Transport SDK's client transport is subscribed to the channel. It decodes each incoming message using the codec, which converts the wire format back into domain events. The React hook in the UI consumes these events and updates the conversation display. The debug console below the conversation shows you the raw transport events as they happen. When I finish this response, the server will publish a turn-end event, and the client will know the response is complete. The whole cycle, from your keypress to this final token, exercised real network infrastructure, real message routing, and real protocol handling. Not bad for a demo running on localhost.",
+];
diff --git a/test/unit/commands/ai-transport/demo/lib/codec.test.ts b/test/unit/commands/ai-transport/demo/lib/codec.test.ts
new file mode 100644
index 000000000..494bff592
--- /dev/null
+++ b/test/unit/commands/ai-transport/demo/lib/codec.test.ts
@@ -0,0 +1,122 @@
+import { describe, it, expect } from "vitest";
+import {
+  DemoCodec,
+  type DemoMessage,
+} from "../../../../../../src/commands/ai-transport/demo/lib/codec.js";
+import type { FakeLLMEvent } from "../../../../../../src/commands/ai-transport/demo/lib/fake-llm.js";
+
+describe("DemoCodec", () => {
+  describe("isTerminal", () => {
+    it("should return true for finish events", () => {
+      expect(DemoCodec.isTerminal({ type: "finish" })).toBe(true);
+    });
+
+    it("should return false for text-delta events", () => {
+      expect(
+        DemoCodec.isTerminal({ type: "text-delta", text: "hello" }),
+      ).toBe(false);
+    });
+  });
+
+  describe("getMessageKey", () => {
+    it("should return the message id", () => {
+      const msg: DemoMessage = {
+        id: "msg-123",
+        role: "user",
+        content: "hello",
+      };
+      expect(DemoCodec.getMessageKey(msg)).toBe("msg-123");
+    });
+  });
+
+  describe("createAccumulator", () => {
+    it("should start with empty state", () => {
+      const acc = DemoCodec.createAccumulator();
+      expect(acc.messages).toEqual([]);
+      expect(acc.completedMessages).toEqual([]);
+      expect(acc.hasActiveStream).toBe(false);
+    });
+
+    it("should accumulate text-delta events into a message", () => {
+      const acc = DemoCodec.createAccumulator();
+
+      acc.processOutputs([
+        {
+          kind: "event",
+          event: { type: "text-delta", text: "Hello " } as FakeLLMEvent,
+          messageId: "stream-1",
+        },
+        {
+          kind: "event",
+          event: { type: "text-delta", text: "world" } as FakeLLMEvent,
+          messageId: "stream-1",
+        },
+      ]);
+
+      expect(acc.messages).toHaveLength(1);
+      expect(acc.messages[0].content).toBe("Hello world");
+      expect(acc.messages[0].role).toBe("assistant");
+      expect(acc.hasActiveStream).toBe(true);
+    });
+
+    it("should mark message as completed on finish event", () => {
+      const acc = DemoCodec.createAccumulator();
+
+      acc.processOutputs([
+        {
+          kind: "event",
+          event: { type: "text-delta", text: "Hi" } as FakeLLMEvent,
+          messageId: "stream-1",
+        },
+      ]);
+
+      expect(acc.hasActiveStream).toBe(true);
+      expect(acc.completedMessages).toHaveLength(0);
+
+      acc.processOutputs([
+        {
+          kind: "event",
+          event: { type: "finish" } as FakeLLMEvent,
+          messageId: "stream-1",
+        },
+      ]);
+
+      expect(acc.hasActiveStream).toBe(false);
+      expect(acc.completedMessages).toHaveLength(1);
+    });
+
+    it("should handle complete message outputs", () => {
+      const acc = DemoCodec.createAccumulator();
+
+      acc.processOutputs([
+        {
+          kind: "message",
+          message: { id: "msg-1", role: "user", content: "Hello" },
+        },
+      ]);
+
+      expect(acc.messages).toHaveLength(1);
+      expect(acc.messages[0]).toEqual({
+        id: "msg-1",
+        role: "user",
+        content: "Hello",
+      });
+      expect(acc.completedMessages).toHaveLength(1);
+    });
+
+    it("should update existing messages via updateMessage", () => {
+      const acc = DemoCodec.createAccumulator();
+
+      acc.processOutputs([
+        {
+          kind: "message",
+          message: { id: "msg-1", role: "user", content: "Hello" },
+        },
+      ]);
+
+      acc.updateMessage({ id: "msg-1", role: "user", content: "Updated" });
+
+      expect(acc.messages[0].content).toBe("Updated");
+    });
+  });
+});
diff --git a/test/unit/commands/ai-transport/demo/lib/fake-llm.test.ts b/test/unit/commands/ai-transport/demo/lib/fake-llm.test.ts
new file mode 100644
index 000000000..2af8591d5
--- /dev/null
+++ b/test/unit/commands/ai-transport/demo/lib/fake-llm.test.ts
@@ -0,0 +1,139 @@
+import { describe, it, expect } from "vitest";
+import {
+  createFakeLLMStream,
+  type FakeLLMEvent,
+} from "../../../../../../src/commands/ai-transport/demo/lib/fake-llm.js";
+
+async function collectEvents(
+  stream: ReadableStream<FakeLLMEvent>,
+): Promise<FakeLLMEvent[]> {
+  const events: FakeLLMEvent[] = [];
+  const reader = stream.getReader();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    events.push(value);
+  }
+
+  return events;
+}
+
+describe("fake-llm", () => {
+  describe("createFakeLLMStream", () => {
+    it("should produce text-delta events followed by a finish event", async () => {
+      const stream = createFakeLLMStream({
+        feature: "streaming",
+        userMessage: "Hello",
+        baseDelayMs: 1, // Fast for tests
+      });
+
+      const events = await collectEvents(stream);
+
+      expect(events.length).toBeGreaterThan(1);
+
+      // All events except the last should be text-delta
+      const deltas = events.filter((e) => e.type === "text-delta");
+      expect(deltas.length).toBeGreaterThan(0);
+
+      // Last event should be finish
+      const last = events[events.length - 1];
+      expect(last.type).toBe("finish");
+    });
+
+    it("should produce non-empty text in deltas", async () => {
+      const stream = createFakeLLMStream({
+        feature: "streaming",
+        userMessage: "Tell me something",
+        baseDelayMs: 1,
+      });
+
+      const events = await collectEvents(stream);
+      const deltas = events.filter(
+        (e): e is Extract<FakeLLMEvent, { type: "text-delta" }> =>
+          e.type === "text-delta",
+      );
+
+      for (const delta of deltas) {
+        expect(delta.text.length).toBeGreaterThan(0);
+      }
+    });
+
+    it("should reconstruct the original response from deltas", async () => {
+      const stream = createFakeLLMStream({
+        feature: "streaming",
+        userMessage: "Hello",
+        baseDelayMs: 1,
+      });
+
+      const events = await collectEvents(stream);
+      const text = events
+        .filter(
+          (e): e is Extract<FakeLLMEvent, { type: "text-delta" }> =>
+            e.type === "text-delta",
+        )
+        .map((e) => e.text)
+        .join("");
+
+      // Should contain meaningful text (not empty)
+      expect(text.length).toBeGreaterThan(50);
+    });
+
+    it("should select shorter response when user asks for short", async () => {
+      const shortStream = createFakeLLMStream({
+        feature: "streaming",
+        userMessage: "Give me a short response",
+        baseDelayMs: 1,
+      });
+
+      const normalStream = createFakeLLMStream({
+        feature: "streaming",
+        userMessage: "Tell me about the weather",
+        baseDelayMs: 1,
+      });
+
+      const shortEvents = await collectEvents(shortStream);
+      const normalEvents = await collectEvents(normalStream);
+
+      const shortDeltas = shortEvents.filter((e) => e.type === "text-delta");
+      const normalDeltas = normalEvents.filter(
+        (e) => e.type === "text-delta",
+      );
+
+      // Short response should have fewer tokens than normal
+      expect(shortDeltas.length).toBeLessThan(normalDeltas.length);
+    });
+
+    it("should stop when abort signal is fired", async () => {
+      const controller = new AbortController();
+      const stream = createFakeLLMStream({
+        feature: "streaming",
+        userMessage: "Tell me something long",
+        baseDelayMs: 5,
+        signal: controller.signal,
+      });
+
+      const events: FakeLLMEvent[] = [];
+      const reader = stream.getReader();
+
+      // Read a few events then abort
+      for (let i = 0; i < 5; i++) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        events.push(value);
+      }
+
+      controller.abort();
+
+      // Read remaining (should stop quickly)
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        events.push(value);
+      }
+
+      // Should have stopped before producing all tokens
+      // (normal responses have 50+ tokens)
+      expect(events.length).toBeLessThan(30);
+    });
+  });
+});
diff --git a/test/unit/commands/ai-transport/demo/lib/mutable-messages.test.ts b/test/unit/commands/ai-transport/demo/lib/mutable-messages.test.ts
new file mode 100644
index 000000000..3751b877c
--- /dev/null
+++ b/test/unit/commands/ai-transport/demo/lib/mutable-messages.test.ts
@@ -0,0 +1,172 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  extractNamespace,
+  checkViaControlApi,
+  checkViaDataPlane,
+  enableMutableMessages,
+} from "../../../../../../src/commands/ai-transport/demo/lib/mutable-messages.js";
+import type { ControlApi } from "../../../../../../src/services/control-api.js";
+
+function createMockControlApi(
+  namespaces: Array<{ id: string; mutableMessages?: boolean }>,
+): ControlApi {
+  return {
+    listNamespaces: vi.fn().mockResolvedValue(
+      namespaces.map((ns) => ({
+        appId: "test-app",
+        id: ns.id,
+        mutableMessages: ns.mutableMessages,
+        persisted: ns.mutableMessages ?? false,
+        pushEnabled: false,
+        created: Date.now(),
+        modified: Date.now(),
+      })),
+    ),
+    createNamespace: vi.fn().mockResolvedValue({}),
+    updateNamespace: vi.fn().mockResolvedValue({}),
+  } as unknown as ControlApi;
+}
+
+function createMockChannel(opts?: {
+  publishError?: { code: number };
+  appendError?: { code: number };
+}) {
+  return {
+    publish: opts?.publishError
+      ? vi.fn().mockRejectedValue(opts.publishError)
+      : vi.fn().mockResolvedValue(undefined),
+    appendMessage: opts?.appendError
+      ? vi.fn().mockRejectedValue(opts.appendError)
+      : vi.fn().mockResolvedValue(undefined),
+  } as any;
+}
+
+describe("mutable-messages", () => {
+  describe("extractNamespace", () => {
+    it("should extract namespace from channel name with colon", () => {
+      expect(extractNamespace("ai-demo:streaming-abc")).toBe("ai-demo");
+    });
+
+    it("should return empty string for channel name without colon", () => {
+      expect(extractNamespace("streaming-abc")).toBe("");
+    });
+
+    it("should handle multiple colons", () => {
+      expect(extractNamespace("ai-demo:sub:channel")).toBe("ai-demo");
+    });
+  });
+
+  describe("checkViaControlApi", () => {
+    it("should return enabled when namespace has mutableMessages", async () => {
+      const api = createMockControlApi([
+        { id: "ai-demo", mutableMessages: true },
+      ]);
+
+      const result = await checkViaControlApi(api, "test-app", "ai-demo");
+
+      expect(result).toEqual({ enabled: true, method: "control-api" });
+    });
+
+    it("should return not enabled when namespace lacks mutableMessages", async () => {
+      const api = createMockControlApi([
+        { id: "ai-demo", mutableMessages: false },
+      ]);
+
+      const result = await checkViaControlApi(api, "test-app", "ai-demo");
+
+      expect(result).toEqual({ enabled: false, method: "control-api" });
+    });
+
+    it("should return not enabled when namespace does not exist", async () => {
+      const api = createMockControlApi([]);
+
+      const result = await checkViaControlApi(
+        api,
+        "test-app",
+        "nonexistent",
+      );
+
+      expect(result).toEqual({ enabled: false, method: "control-api" });
+    });
+
+    it("should return null when Control API fails", async () => {
+      const api = {
+        listNamespaces: vi.fn().mockRejectedValue(new Error("unauthorized")),
+      } as unknown as ControlApi;
+
+      const result = await checkViaControlApi(api, "test-app", "ai-demo");
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("checkViaDataPlane", () => {
+    it("should return enabled when appendMessage succeeds", async () => {
+      const channel = createMockChannel();
+
+      const result = await checkViaDataPlane(channel);
+
+      expect(result).toEqual({ enabled: true, method: "data-plane" });
+      expect(channel.publish).toHaveBeenCalled();
+      expect(channel.appendMessage).toHaveBeenCalled();
+    });
+
+    it("should return not enabled when appendMessage returns error 93002", async () => {
+      const channel = createMockChannel({
+        appendError: { code: 93002 },
+      });
+
+      const result = await checkViaDataPlane(channel);
+
+      expect(result).toEqual({ enabled: false, method: "data-plane" });
+    });
+
+    it("should return enabled for non-93002 errors", async () => {
+      const channel = createMockChannel({
+        appendError: { code: 40160 },
+      });
+
+      const result = await checkViaDataPlane(channel);
+
+      expect(result).toEqual({ enabled: true, method: "data-plane" });
+    });
+
+    it("should detect error 93002 on publish itself", async () => {
+      const channel = createMockChannel({
+        publishError: { code: 93002 },
+      });
+
+      const result = await checkViaDataPlane(channel);
+
+      expect(result).toEqual({ enabled: false, method: "data-plane" });
+    });
+  });
+
+  describe("enableMutableMessages", () => {
+    it("should update existing namespace", async () => {
+      const api = createMockControlApi([
+        { id: "ai-demo", mutableMessages: false },
+      ]);
+
+      await enableMutableMessages(api, "test-app", "ai-demo");
+
+      expect(api.updateNamespace).toHaveBeenCalledWith(
+        "test-app",
+        "ai-demo",
+        { mutableMessages: true, persisted: true },
+      );
+    });
+
+    it("should create new namespace when it does not exist", async () => {
+      const api = createMockControlApi([]);
+
+      await enableMutableMessages(api, "test-app", "ai-demo");
+
+      expect(api.createNamespace).toHaveBeenCalledWith("test-app", {
+        id: "ai-demo",
+        mutableMessages: true,
+        persisted: true,
+      });
+    });
+  });
+});

From 9abc008845ac274d4045bfa4aa4d2d7e5bcf3a76 Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Wed, 15 Apr 2026 17:54:18 +0200
Subject: [PATCH 03/17] feat: add HTTP server and presence-based server
 discovery

Local HTTP server with auto-port finding and presence announcement.
Client discovery subscribes to presence, finds the server endpoint,
with timeout and graceful fallback for both existing members and
late-arriving servers.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../ai-transport/demo/lib/client-discovery.ts | 105 ++++++++++++
 src/commands/ai-transport/demo/lib/server.ts  | 153 +++++++++++++++++
 .../demo/lib/client-discovery.test.ts         | 141 ++++++++++++++++
 .../ai-transport/demo/lib/server.test.ts      | 158 ++++++++++++++++++
 4 files changed, 557 insertions(+)
 create mode 100644 src/commands/ai-transport/demo/lib/client-discovery.ts
 create mode 100644 src/commands/ai-transport/demo/lib/server.ts
 create mode 100644 test/unit/commands/ai-transport/demo/lib/client-discovery.test.ts
 create mode 100644 test/unit/commands/ai-transport/demo/lib/server.test.ts

diff --git a/src/commands/ai-transport/demo/lib/client-discovery.ts b/src/commands/ai-transport/demo/lib/client-discovery.ts
new file mode 100644
index 000000000..65f277d3c
--- /dev/null
+++ b/src/commands/ai-transport/demo/lib/client-discovery.ts
@@ -0,0 +1,105 @@
+/**
+ * Presence-based server discovery for AI Transport demos.
+ *
+ * The demo server enters presence on the Ably channel with its HTTP
+ * endpoint in the presence data. The client subscribes to presence
+ * and discovers the server automatically.
+ */
+
+import type * as Ably from "ably";
+
+export interface DiscoveredServer {
+  /** The server's HTTP endpoint URL. */
+  endpoint: string;
+  /** The client ID of the server presence member. */
+  clientId?: string;
+}
+
+/**
+ * Discover the demo server by subscribing to presence on the channel.
+ *
+ * Returns the server's endpoint URL, or null if no server is found
+ * within the timeout period.
+ *
+ * @param channel - The Ably channel to watch for server presence
+ * @param timeoutMs - How long to wait for a server (default 10s)
+ * @param onLog - Optional callback for discovery log messages
+ */
+export async function discoverServer(
+  channel: Ably.RealtimeChannel,
+  timeoutMs = 10_000,
+  onLog?: (message: string) => void,
+): Promise<DiscoveredServer | null> {
+  onLog?.("Searching for server via presence...");
+
+  // First, check if the server is already present
+  try {
+    const members = await channel.presence.get();
+    for (const member of members) {
+      const server = extractServerFromPresence(member);
+      if (server) {
+        onLog?.(`Found server at ${server.endpoint}`);
+        return server;
+      }
+    }
+  } catch {
+    // Channel might not be attached yet, fall through to subscribe
+  }
+
+  // Subscribe to presence and wait for a server to appear
+  return new Promise<DiscoveredServer | null>((resolve) => {
+    let resolved = false;
+
+    const cleanup = () => {
+      if (!resolved) {
+        resolved = true;
+        channel.presence.unsubscribe(onPresenceEvent);
+      }
+    };
+
+    const onPresenceEvent = (message: Ably.PresenceMessage) => {
+      if (message.action === "enter" || message.action === "present") {
+        const server = extractServerFromPresence(message);
+        if (server) {
+          onLog?.(`Found server at ${server.endpoint}`);
+          cleanup();
+          resolve(server);
+        }
+      }
+    };
+
+    channel.presence.subscribe(onPresenceEvent);
+
+    // Timeout
+    setTimeout(() => {
+      if (!resolved) {
+        onLog?.("No server found within timeout");
+        cleanup();
+        resolve(null);
+      }
+    }, timeoutMs);
+  });
+}
+
+/**
+ * Extract server info from a presence message.
+ * The server enters presence with { endpoint: "http://localhost:PORT" }.
+ */
+function extractServerFromPresence(
+  member: Ably.PresenceMessage,
+): DiscoveredServer | null {
+  const data = member.data;
+  if (
+    typeof data === "object" &&
+    data !== null &&
+    "endpoint" in data &&
+    typeof (data as { endpoint: unknown }).endpoint === "string"
+  ) {
+    return {
+      endpoint: (data as { endpoint: string }).endpoint,
+      clientId: member.clientId,
+    };
+  }
+
+  return null;
+}
diff --git a/src/commands/ai-transport/demo/lib/server.ts b/src/commands/ai-transport/demo/lib/server.ts
new file mode 100644
index 000000000..8a5b6c61b
--- /dev/null
+++ b/src/commands/ai-transport/demo/lib/server.ts
@@ -0,0 +1,153 @@
+/**
+ * Local HTTP server for AI Transport demos.
+ *
+ * Spins up a server on localhost with an auto-assigned port.
+ * Enters Ably presence on the demo channel to announce the endpoint.
+ * Handles POST requests with user messages.
+ */
+
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { EventEmitter } from "node:events";
+import getPort from "get-port";
+import type * as Ably from "ably";
+
+export interface DemoServerOptions {
+  /** The Ably channel to enter presence on. */
+  channel: Ably.RealtimeChannel;
+  /** Callback when a user message is received via HTTP POST. */
+  onMessage: (body: MessageRequestBody) => void;
+}
+
+export interface MessageRequestBody {
+  /** The user's message text. */
+  message: string;
+  /** Optional client ID. */
+  clientId?: string;
+}
+
+export interface DemoServer {
+  /** The port the server is listening on. */
+  port: number;
+  /** The full URL of the server endpoint. */
+  url: string;
+  /** Event emitter for server log events. */
+  events: DemoServerEvents;
+  /** Shut down the server and leave presence. */
+  close: () => Promise<void>;
+}
+
+export class DemoServerEvents extends EventEmitter {
+  emitLog(message: string): void {
+    this.emit("log", message);
+  }
+}
+
+/**
+ * Create and start the demo HTTP server.
+ * Enters presence on the Ably channel with the endpoint URL.
+ */
+export async function createDemoServer(
+  options: DemoServerOptions,
+): Promise<DemoServer> {
+  const { channel, onMessage } = options;
+  const events = new DemoServerEvents();
+
+  // Find an available port
+  const port = await getPort();
+  const url = `http://localhost:${port}`;
+
+  // Create HTTP server
+  const server = createServer(
+    (req: IncomingMessage, res: ServerResponse) => {
+      // CORS headers for flexibility
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+      if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      if (req.method === "POST" && (req.url === "/" || req.url === "/api/chat")) {
+        let body = "";
+        req.on("data", (chunk: Buffer) => {
+          body += chunk.toString();
+        });
+        req.on("end", () => {
+          try {
+            const parsed = JSON.parse(body) as MessageRequestBody;
+            events.emitLog(`Received message: "${truncate(parsed.message, 50)}"`);
+            onMessage(parsed);
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: true }));
+          } catch {
+            events.emitLog("Invalid request body");
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid JSON body" }));
+          }
+        });
+        return;
+      }
+
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Not found" }));
+    },
+  );
+
+  // Start listening
+  await new Promise<void>((resolve, reject) => {
+    server.on("error", reject);
+    server.listen(port, "127.0.0.1", () => {
+      events.emitLog(`Listening on ${url}`);
+      resolve();
+    });
+  });
+
+  // Enter presence on the Ably channel
+  try {
+    await channel.presence.enter({ endpoint: url });
+    events.emitLog("Entered presence on channel");
+  } catch (error: unknown) {
+    events.emitLog(`Failed to enter presence: ${String(error)}`);
+    // Continue anyway — presence is for discovery, not critical
+  }
+
+  return {
+    port,
+    url,
+    events,
+    close: () => closeServer(server, channel, events),
+  };
+}
+
+async function closeServer(
+  server: Server,
+  channel: Ably.RealtimeChannel,
+  events: DemoServerEvents,
+): Promise<void> {
+  // Leave presence
+  try {
+    await Promise.race([
+      channel.presence.leave(),
+      new Promise<void>((resolve) => setTimeout(resolve, 2000)),
+    ]);
+    events.emitLog("Left presence");
+  } catch {
+    // Ignore cleanup errors
+  }
+
+  // Close HTTP server
+  await new Promise<void>((resolve) => {
+    server.close(() => {
+      events.emitLog("Server stopped");
+      resolve();
+    });
+  });
+}
+
+function truncate(str: string, maxLen: number): string {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 3) + "...";
+}
diff --git a/test/unit/commands/ai-transport/demo/lib/client-discovery.test.ts b/test/unit/commands/ai-transport/demo/lib/client-discovery.test.ts
new file mode 100644
index 000000000..63db625db
--- /dev/null
+++ b/test/unit/commands/ai-transport/demo/lib/client-discovery.test.ts
@@ -0,0 +1,141 @@
+import { describe, it, expect, vi } from "vitest";
+import { discoverServer } from "../../../../../../src/commands/ai-transport/demo/lib/client-discovery.js";
+
+function createMockChannel(opts?: {
+  presenceMembers?: Array<{ data: unknown; clientId?: string; action?: string }>;
+}) {
+  let subscribeCallback: ((msg: any) => void) | null = null;
+
+  return {
+    presence: {
+      get: vi
+        .fn()
+        .mockResolvedValue(
+          (opts?.presenceMembers ?? []).map((m) => ({
+            ...m,
+            action: m.action ?? "present",
+          })),
+        ),
+      subscribe: vi.fn((callback: (msg: any) => void) => {
+        subscribeCallback = callback;
+      }),
+      unsubscribe: vi.fn(),
+    },
+    // Helper to simulate a presence event
+    _simulatePresenceEvent(member: {
+      data: unknown;
+      clientId?: string;
+      action: string;
+    }) {
+      subscribeCallback?.(member);
+    },
+  } as any;
+}
+
+describe("client-discovery", () => {
+  describe("discoverServer", () => {
+    it("should find server from existing presence members", async () => {
+      const channel = createMockChannel({
+        presenceMembers: [
+          {
+            data: { endpoint: "http://localhost:12345" },
+            clientId: "server-1",
+          },
+        ],
+      });
+
+      const result = await discoverServer(channel, 1000);
+
+      expect(result).toEqual({
+        endpoint: "http://localhost:12345",
+        clientId: "server-1",
+      });
+    });
+
+    it("should find server when it enters after subscription", async () => {
+      const channel = createMockChannel({ presenceMembers: [] });
+
+      // Start discovery, then simulate server entering
+      const discoveryPromise = discoverServer(channel, 5000);
+
+      // Small delay to let subscription start
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      channel._simulatePresenceEvent({
+        action: "enter",
+        data: { endpoint: "http://localhost:9999" },
+        clientId: "server-2",
+      });
+
+      const result = await discoveryPromise;
+
+      expect(result).toEqual({
+        endpoint: "http://localhost:9999",
+        clientId: "server-2",
+      });
+    });
+
+    it("should return null when no server found within timeout", async () => {
+      const channel = createMockChannel({ presenceMembers: [] });
+
+      const result = await discoverServer(channel, 100); // Short timeout
+
+      expect(result).toBeNull();
+    });
+
+    it("should ignore presence members without endpoint data", async () => {
+      const channel = createMockChannel({
+        presenceMembers: [
+          { data: { something: "else" }, clientId: "not-a-server" },
+        ],
+      });
+
+      const result = await discoverServer(channel, 100);
+
+      expect(result).toBeNull();
+    });
+
+    it("should ignore non-enter/present actions", async () => {
+      const channel = createMockChannel({ presenceMembers: [] });
+
+      const discoveryPromise = discoverServer(channel, 500);
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      // Leave event should be ignored
+      channel._simulatePresenceEvent({
+        action: "leave",
+        data: { endpoint: "http://localhost:9999" },
+        clientId: "server-3",
+      });
+
+      const result = await discoveryPromise;
+      expect(result).toBeNull();
+    });
+
+    it("should call onLog callback", async () => {
+      const channel = createMockChannel({
+        presenceMembers: [
+          { data: { endpoint: "http://localhost:12345" } },
+        ],
+      });
+      const logs: string[] = [];
+
+      await discoverServer(channel, 1000, (msg) => logs.push(msg));
+
+      expect(logs.some((l) => l.includes("Searching for server"))).toBe(
+        true,
+      );
+      expect(logs.some((l) => l.includes("Found server"))).toBe(true);
+    });
+
+    it("should handle presence.get failure gracefully", async () => {
+      const channel = createMockChannel({ presenceMembers: [] });
+      channel.presence.get.mockRejectedValue(new Error("not attached"));
+
+      // Should still fall through to subscribe and then timeout
+      const result = await discoverServer(channel, 100);
+      expect(result).toBeNull();
+    });
+  });
+});
diff --git a/test/unit/commands/ai-transport/demo/lib/server.test.ts b/test/unit/commands/ai-transport/demo/lib/server.test.ts
new file mode 100644
index 000000000..ce461807c
--- /dev/null
+++ b/test/unit/commands/ai-transport/demo/lib/server.test.ts
@@ -0,0 +1,158 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import {
+  createDemoServer,
+  type DemoServer,
+} from "../../../../../../src/commands/ai-transport/demo/lib/server.js";
+
+function createMockChannel() {
+  return {
+    presence: {
+      enter: vi.fn().mockResolvedValue(undefined),
+      leave: vi.fn().mockResolvedValue(undefined),
+    },
+  } as any;
+}
+
+describe("server", () => {
+  let server: DemoServer | null = null;
+
+  afterEach(async () => {
+    if (server) {
+      await server.close();
+      server = null;
+    }
+  });
+
+  describe("createDemoServer", () => {
+    it("should start a server on an available port", async () => {
+      const channel = createMockChannel();
+      const onMessage = vi.fn();
+
+      server = await createDemoServer({ channel, onMessage });
+
+      expect(server.port).toBeGreaterThan(0);
+      expect(server.url).toBe(`http://localhost:${server.port}`);
+    });
+
+    it("should enter presence with the endpoint URL", async () => {
+      const channel = createMockChannel();
+      const onMessage = vi.fn();
+
+      server = await createDemoServer({ channel, onMessage });
+
+      expect(channel.presence.enter).toHaveBeenCalledWith({
+        endpoint: server.url,
+      });
+    });
+
+    it("should handle POST requests with JSON body", async () => {
+      const channel = createMockChannel();
+      const onMessage = vi.fn();
+
+      server = await createDemoServer({ channel, onMessage });
+
+      const response = await fetch(server.url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ message: "Hello" }),
+      });
+
+      expect(response.status).toBe(200);
+      const data = await response.json();
+      expect(data).toEqual({ ok: true });
+      expect(onMessage).toHaveBeenCalledWith({ message: "Hello" });
+    });
+
+    it("should handle POST to /api/chat endpoint", async () => {
+      const channel = createMockChannel();
+      const onMessage = vi.fn();
+
+      server = await createDemoServer({ channel, onMessage });
+
+      const response = await fetch(`${server.url}/api/chat`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ message: "Hello from /api/chat" }),
+      });
+
+      expect(response.status).toBe(200);
+      expect(onMessage).toHaveBeenCalledWith({
+        message: "Hello from /api/chat",
+      });
+    });
+
+    it("should return 400 for invalid JSON", async () => {
+      const channel = createMockChannel();
+      const onMessage = vi.fn();
+
+      server = await createDemoServer({ channel, onMessage });
+
+      const response = await fetch(server.url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "not json",
+      });
+
+      expect(response.status).toBe(400);
+      expect(onMessage).not.toHaveBeenCalled();
+    });
+
+    it("should return 404 for unknown routes", async () => {
+      const channel = createMockChannel();
+      const onMessage = vi.fn();
+
+      server = await createDemoServer({ channel, onMessage });
+
+      const response = await fetch(`${server.url}/unknown`);
+
+      expect(response.status).toBe(404);
+    });
+
+    it("should emit log events", async () => {
+      const channel = createMockChannel();
+      const onMessage = vi.fn();
+      const logs: string[] = [];
+
+      server = await createDemoServer({ channel, onMessage });
+      server.events.on("log", (msg: string) => logs.push(msg));
+
+      await fetch(server.url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ message: "Test" }),
+      });
+
+      expect(logs.some((l) => l.includes("Received message"))).toBe(true);
+    });
+
+    it("should leave presence and stop on close", async () => {
+      const channel = createMockChannel();
+      const onMessage = vi.fn();
+
+      server = await createDemoServer({ channel, onMessage });
+      await server.close();
+
+      expect(channel.presence.leave).toHaveBeenCalled();
+
+      // Server should be stopped — fetch should fail
+      await expect(
+        fetch(server.url).catch(() => {
+          throw new Error("connection refused");
+        }),
+      ).rejects.toThrow();
+
+      server = null; // Prevent double-close in afterEach
+    });
+
+    it("should continue if presence enter fails", async () => {
+      const channel = createMockChannel();
+      channel.presence.enter.mockRejectedValue(new Error("presence error"));
+      const onMessage = vi.fn();
+
+      server = await createDemoServer({ channel, onMessage });
+
+      // Server should still be running despite presence failure
+      expect(server.port).toBeGreaterThan(0);
+    });
+  });
+});

From 970e30183e8ce4d34594c02d14a52f9af9b09a7d Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Wed, 15 Apr 2026 18:00:47 +0200
Subject: [PATCH 04/17] feat: add Ink TUI layout and move lib to services
 directory

Split-pane terminal UI with Ink (React for CLIs):
- ClientPanel: conversation display with streaming cursor
- ServerPanel: timestamped server activity log
- DebugPanel: collapsible transport-level event console
- InputBar: text input with context-sensitive hints
- App: root layout with role-based rendering

Move lib/ and ui/ from commands/ to services/ai-transport-demo/
to prevent oclif from treating them as commands. Add ESLint config
for TSX files with React plugin support.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 eslint.config.js                              |  32 ++++
 src/commands/ai-transport/demo/streaming.ts   |  30 +++-
 .../lib/client-discovery.ts                   |   0
 .../ai-transport-demo}/lib/codec.ts           |   0
 .../ai-transport-demo}/lib/fake-llm.ts        |   0
 .../lib/mutable-messages.ts                   |   2 +-
 .../lib/responses/streaming.ts                |   0
 .../ai-transport-demo}/lib/server.ts          |   0
 src/services/ai-transport-demo/ui/App.tsx     | 140 ++++++++++++++++++
 .../ai-transport-demo/ui/ClientPanel.tsx      | 105 +++++++++++++
 .../ai-transport-demo/ui/DebugPanel.tsx       |  51 +++++++
 .../ai-transport-demo/ui/InputBar.tsx         |  58 ++++++++
 .../ai-transport-demo/ui/ServerPanel.tsx      |  79 ++++++++++
 .../ui/hooks/use-scrollable-log.ts            |  44 ++++++
 src/services/ai-transport-demo/ui/theme.ts    |  50 +++++++
 .../demo/lib/client-discovery.test.ts         |   2 +-
 .../ai-transport/demo/lib/codec.test.ts       |   4 +-
 .../ai-transport/demo/lib/fake-llm.test.ts    |   2 +-
 .../demo/lib/mutable-messages.test.ts         |   2 +-
 .../ai-transport/demo/lib/server.test.ts      |   2 +-
 20 files changed, 593 insertions(+), 10 deletions(-)
 rename src/{commands/ai-transport/demo => services/ai-transport-demo}/lib/client-discovery.ts (100%)
 rename src/{commands/ai-transport/demo => services/ai-transport-demo}/lib/codec.ts (100%)
 rename src/{commands/ai-transport/demo => services/ai-transport-demo}/lib/fake-llm.ts (100%)
 rename src/{commands/ai-transport/demo => services/ai-transport-demo}/lib/mutable-messages.ts (98%)
 rename src/{commands/ai-transport/demo => services/ai-transport-demo}/lib/responses/streaming.ts (100%)
 rename src/{commands/ai-transport/demo => services/ai-transport-demo}/lib/server.ts (100%)
 create mode 100644 src/services/ai-transport-demo/ui/App.tsx
 create mode 100644 src/services/ai-transport-demo/ui/ClientPanel.tsx
 create mode 100644 src/services/ai-transport-demo/ui/DebugPanel.tsx
 create mode 100644 src/services/ai-transport-demo/ui/InputBar.tsx
 create mode 100644 src/services/ai-transport-demo/ui/ServerPanel.tsx
 create mode 100644 src/services/ai-transport-demo/ui/hooks/use-scrollable-log.ts
 create mode 100644 src/services/ai-transport-demo/ui/theme.ts

diff --git a/eslint.config.js b/eslint.config.js
index 58e41f19d..90aac2c3f 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -108,6 +108,38 @@ export default [
       "unicorn/numeric-separators-style": "off",
     },
   },
+  {
+    // Configuration for AI Transport demo TUI - TSX files
+    files: ["src/services/ai-transport-demo/ui/**/*.{ts,tsx}"],
+    plugins: {
+      react: eslintPluginReact,
+      "@typescript-eslint": tsPlugin,
+    },
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaFeatures: {
+          jsx: true,
+        },
+        project: "./tsconfig.json",
+      },
+    },
+    settings: {
+      react: {
+        version: "detect",
+      },
+    },
+    rules: {
+      ...eslintPluginReact.configs.recommended.rules,
+      ...eslintPluginReact.configs["jsx-runtime"].rules,
+      ...tsPlugin.configs.recommended.rules,
+      "unicorn/filename-case": "off",
+      "unicorn/prevent-abbreviations": "off",
+      "n/no-missing-import": "off",
+      "react/prop-types": "off",
+      "react/react-in-jsx-scope": "off",
+    },
+  },
   {
     // Configuration for React Web CLI package - TSX files
     files: ["packages/react-web-cli/**/*.{ts,tsx}"],
diff --git a/src/commands/ai-transport/demo/streaming.ts b/src/commands/ai-transport/demo/streaming.ts
index 37df83785..d4ce9e633 100644
--- a/src/commands/ai-transport/demo/streaming.ts
+++ b/src/commands/ai-transport/demo/streaming.ts
@@ -1,7 +1,11 @@
+import React from "react";
 import { Flags } from "@oclif/core";
+import { render } from "ink";
 
 import { ControlBaseCommand } from "../../../control-base-command.js";
 import { productApiFlags } from "../../../flags.js";
+import isTestMode from "../../../utils/test-mode.js";
+import { App } from "../../../services/ai-transport-demo/ui/App.js";
 
 export default class StreamingDemo extends ControlBaseCommand {
   static override description =
@@ -52,9 +56,29 @@ export default class StreamingDemo extends ControlBaseCommand {
       );
     }
 
-    this.log(
-      "AI Transport Streaming Demo (coming soon). " +
-        `Role: ${flags.role}, Channel: ${flags.channel ?? "(auto)"}`,
+    const role = (flags.role ?? "both") as "both" | "client" | "server";
+    const channelName =
+      flags.channel ??
+      `ai-demo:streaming-${Math.random().toString(36).slice(2, 6)}`;
+
+    // In test mode, just output a marker and return (Ink can't render in tests)
+    if (isTestMode()) {
+      this.log(
+        `AI Transport Streaming Demo (coming soon). ` +
+          `Role: ${role}, Channel: ${channelName}`,
+      );
+      return;
+    }
+
+    // Render the TUI
+    const { waitUntilExit } = render(
+      React.createElement(App, {
+        role,
+        feature: "streaming",
+        channelName,
+      }),
     );
+
+    await waitUntilExit();
   }
 }
diff --git a/src/commands/ai-transport/demo/lib/client-discovery.ts b/src/services/ai-transport-demo/lib/client-discovery.ts
similarity index 100%
rename from src/commands/ai-transport/demo/lib/client-discovery.ts
rename to src/services/ai-transport-demo/lib/client-discovery.ts
diff --git a/src/commands/ai-transport/demo/lib/codec.ts b/src/services/ai-transport-demo/lib/codec.ts
similarity index 100%
rename from src/commands/ai-transport/demo/lib/codec.ts
rename to src/services/ai-transport-demo/lib/codec.ts
diff --git a/src/commands/ai-transport/demo/lib/fake-llm.ts b/src/services/ai-transport-demo/lib/fake-llm.ts
similarity index 100%
rename from src/commands/ai-transport/demo/lib/fake-llm.ts
rename to src/services/ai-transport-demo/lib/fake-llm.ts
diff --git a/src/commands/ai-transport/demo/lib/mutable-messages.ts b/src/services/ai-transport-demo/lib/mutable-messages.ts
similarity index 98%
rename from src/commands/ai-transport/demo/lib/mutable-messages.ts
rename to src/services/ai-transport-demo/lib/mutable-messages.ts
index 1ca6db409..2402237c9 100644
--- a/src/commands/ai-transport/demo/lib/mutable-messages.ts
+++ b/src/services/ai-transport-demo/lib/mutable-messages.ts
@@ -12,7 +12,7 @@
  *   Works with just an API key.
  */
 
-import type { ControlApi, Namespace } from "../../../../services/control-api.js";
+import type { ControlApi, Namespace } from "../../control-api.js";
 import type * as Ably from "ably";
 
 /** Error code returned when mutable messages is not enabled. */
diff --git a/src/commands/ai-transport/demo/lib/responses/streaming.ts b/src/services/ai-transport-demo/lib/responses/streaming.ts
similarity index 100%
rename from src/commands/ai-transport/demo/lib/responses/streaming.ts
rename to src/services/ai-transport-demo/lib/responses/streaming.ts
diff --git a/src/commands/ai-transport/demo/lib/server.ts b/src/services/ai-transport-demo/lib/server.ts
similarity index 100%
rename from src/commands/ai-transport/demo/lib/server.ts
rename to src/services/ai-transport-demo/lib/server.ts
diff --git a/src/services/ai-transport-demo/ui/App.tsx b/src/services/ai-transport-demo/ui/App.tsx
new file mode 100644
index 000000000..17bde197c
--- /dev/null
+++ b/src/services/ai-transport-demo/ui/App.tsx
@@ -0,0 +1,140 @@
+/**
+ * Root Ink component for AI Transport demos.
+ *
+ * Renders the split-pane TUI with client (left) and server (right) panels,
+ * a debug console, and an input bar.
+ */
+
+import React, { useState } from "react";
+import { Box, Text, useApp, useInput, useStdout } from "ink";
+import { ClientPanel, type ConversationMessage } from "./ClientPanel.js";
+import { ServerPanel } from "./ServerPanel.js";
+import { DebugPanel } from "./DebugPanel.js";
+import { InputBar } from "./InputBar.js";
+import { useScrollableLog } from "./hooks/use-scrollable-log.js";
+import { colors } from "./theme.js";
+
+export interface AppProps {
+  /** Which role the demo is running as. */
+  role: "both" | "client" | "server";
+  /** The demo feature name. */
+  feature: string;
+  /** The Ably channel name. */
+  channelName: string;
+  /** Callback when user submits a message. */
+  onSendMessage?: (text: string) => void;
+  /** Callback when user requests cancel (Ctrl+C). */
+  onCancel?: () => void;
+}
+
+export function App({
+  role,
+  feature,
+  channelName,
+  onSendMessage,
+  onCancel,
+}: AppProps) {
+  const { exit } = useApp();
+  const { stdout } = useStdout();
+  const terminalHeight = stdout?.rows ?? 24;
+  const terminalWidth = stdout?.columns ?? 80;
+
+  const [debugExpanded, setDebugExpanded] = useState(false);
+  const [isStreaming] = useState(false);
+
+  // Placeholder conversation messages
+  const [messages] = useState<ConversationMessage[]>([]);
+
+  // Server log
+  const serverLog = useScrollableLog();
+
+  // Debug log
+  const debugLog = useScrollableLog();
+
+  // Keyboard handling
+  useInput((input, key) => {
+    if (input === "d" && key.ctrl) {
+      exit();
+      return;
+    }
+
+    if (input === "c" && key.ctrl && isStreaming) {
+      onCancel?.();
+      return;
+    }
+
+    if (key.tab) {
+      setDebugExpanded((prev) => !prev);
+    }
+  });
+
+  const handleSendMessage = (text: string) => {
+    onSendMessage?.(text);
+  };
+
+  const showClient = role === "both" || role === "client";
+  const showServer = role === "both" || role === "server";
+
+  // Calculate panel heights
+  const debugHeight = debugExpanded ? 8 : 1;
+  const inputHeight = 2;
+  const mainHeight = terminalHeight - debugHeight - inputHeight - 2;
+
+  return (
+    <Box flexDirection="column" height={terminalHeight}>
+      {/* Main panels */}
+      <Box flexDirection="row" height={mainHeight}>
+        {showClient && (
+          <Box
+            flexDirection="column"
+            flexGrow={showServer ? 2 : 1}
+            borderStyle="single"
+            borderColor={colors.activeBorder}
+            paddingX={1}
+            width={showServer ? Math.floor(terminalWidth * 0.6) : undefined}
+          >
+            <ClientPanel
+              feature={feature}
+              channelName={channelName}
+              messages={messages}
+              serverStatus="connected"
+              maxVisible={mainHeight - 4}
+            />
+          </Box>
+        )}
+
+        {showServer && (
+          <Box
+            flexDirection="column"
+            flexGrow={1}
+            borderStyle="single"
+            borderColor={colors.border}
+            paddingX={1}
+          >
+            <ServerPanel
+              entries={serverLog.entries}
+              isRunning={false}
+              maxVisible={mainHeight - 3}
+            />
+          </Box>
+        )}
+      </Box>
+
+      {/* Debug panel (client side only in both mode) */}
+      {showClient && (
+        <DebugPanel entries={debugLog.entries} expanded={debugExpanded} />
+      )}
+
+      {/* Input bar (only when client is shown) */}
+      {showClient ? (
+        <InputBar onSubmit={handleSendMessage} isStreaming={isStreaming} />
+      ) : (
+        <Box>
+          <Text color={colors.dim}>
+            Server mode — no input. Ctrl+D to quit.
+          </Text>
+        </Box>
+      )}
+    </Box>
+  );
+}
diff --git a/src/services/ai-transport-demo/ui/ClientPanel.tsx b/src/services/ai-transport-demo/ui/ClientPanel.tsx
new file mode 100644
index 000000000..4a4b76574
--- /dev/null
+++ b/src/services/ai-transport-demo/ui/ClientPanel.tsx
@@ -0,0 +1,105 @@
+/**
+ * Client panel — shows the conversation (user messages + assistant responses).
+ */
+
+import React from "react";
+import { Box, Text } from "ink";
+import { colors } from "./theme.js";
+
+export interface ConversationMessage {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+  /** Whether this message is still being streamed. */
+  streaming?: boolean;
+  /** Whether this message was interrupted (barge-in). */
+  interrupted?: boolean;
+}
+
+interface ClientPanelProps {
+  feature: string;
+  channelName: string;
+  messages: ConversationMessage[];
+  serverStatus: "connecting" | "connected" | "not-found";
+  maxVisible?: number;
+}
+
+export function ClientPanel({
+  feature,
+  channelName,
+  messages,
+  serverStatus,
+  maxVisible = 20,
+}: ClientPanelProps) {
+  const visible = messages.slice(-maxVisible);
+
+  return (
+    <Box flexDirection="column" flexGrow={1}>
+      {/* Header */}
+      <Box flexDirection="column">
+        <Text bold>
+          💬 AI Transport Demo:{" "}
+          <Text color={colors.primary}>{formatFeatureName(feature)}</Text>
+        </Text>
+        <Text color={colors.dim}>Channel: {channelName}</Text>
+      </Box>
+
+      {/* Server status */}
+      {serverStatus === "not-found" && (
+        <Box marginTop={1}>
+          <Text color={colors.warning}>
+            ⚠ No server detected. Start a server or use --endpoint.
+          </Text>
+        </Box>
+      )}
+      {serverStatus === "connecting" && (
+        <Box marginTop={1}>
+          <Text color={colors.dim}>Connecting to server...</Text>
+        </Box>
+      )}
+
+      {/* Conversation */}
+      <Box flexDirection="column" flexGrow={1} marginTop={1}>
+        {visible.length === 0 && serverStatus === "connected" && (
+          <Text color={colors.dim}>
+            Type a message below to start the demo.
+          </Text>
+        )}
+        {visible.map((msg) => (
+          <Box key={msg.id} flexDirection="column" marginBottom={1}>
+            {msg.role === "user" ? (
+              <Text>
+                <Text color={colors.user} bold>
+                  You:{" "}
+                </Text>
+                <Text>{msg.content}</Text>
+              </Text>
+            ) : (
+              <Box flexDirection="column">
+                <Text>
+                  <Text color={colors.primary} bold>
+                    Agent:{" "}
+                  </Text>
+                  <Text color={colors.assistant}>
+                    {msg.content}
+                    {msg.streaming && <Text color={colors.dim}>▊</Text>}
+                    {msg.interrupted && (
+                      <Text color={colors.warning}> [interrupted]</Text>
+                    )}
+                  </Text>
+                </Text>
+              </Box>
+            )}
+          </Box>
+        ))}
+      </Box>
+    </Box>
+  );
+}
+
+function formatFeatureName(feature: string): string {
+  return feature
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
diff --git a/src/services/ai-transport-demo/ui/DebugPanel.tsx b/src/services/ai-transport-demo/ui/DebugPanel.tsx
new file mode 100644
index 000000000..885f60653
--- /dev/null
+++ b/src/services/ai-transport-demo/ui/DebugPanel.tsx
@@ -0,0 +1,51 @@
+/**
+ * Collapsible debug console showing transport-level events.
+ */
+
+import React from "react";
+import { Box, Text } from "ink";
+import type { LogEntry } from "./hooks/use-scrollable-log.js";
+import { colors } from "./theme.js";
+
+interface DebugPanelProps {
+  entries: LogEntry[];
+  expanded: boolean;
+  maxVisible?: number;
+}
+
+export function DebugPanel({
+  entries,
+  expanded,
+  maxVisible = 6,
+}: DebugPanelProps) {
+  if (!expanded) {
+    return (
+      <Box>
+        <Text color={colors.dim}>
+          🔍 Debug ({entries.length} events) — Tab to expand
+        </Text>
+      </Box>
+    );
+  }
+
+  const visible = entries.slice(-maxVisible);
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="single"
+      borderColor={colors.dim}
+      paddingX={1}
+    >
+      <Text bold color={colors.dim}>
+        🔍 Debug — Tab to collapse
+      </Text>
+      {visible.length === 0 && <Text color={colors.dim}>No events yet.</Text>}
+      {visible.map((entry, i) => (
+        <Text key={i} wrap="truncate" color={colors.dim}>
+          {entry.timestamp} {entry.message}
+        </Text>
+      ))}
+    </Box>
+  );
+}
diff --git a/src/services/ai-transport-demo/ui/InputBar.tsx b/src/services/ai-transport-demo/ui/InputBar.tsx
new file mode 100644
index 000000000..d5b6a1f11
--- /dev/null
+++ b/src/services/ai-transport-demo/ui/InputBar.tsx
@@ -0,0 +1,58 @@
+/**
+ * Text input bar at the bottom of the TUI.
+ */
+
+import React, { useState } from "react";
+import { Box, Text } from "ink";
+import TextInput from "ink-text-input";
+import { colors } from "./theme.js";
+
+interface InputBarProps {
+  onSubmit: (text: string) => void;
+  isStreaming: boolean;
+  disabled?: boolean;
+  placeholder?: string;
+}
+
+export function InputBar({
+  onSubmit,
+  isStreaming,
+  disabled = false,
+  placeholder = "Type a message...",
+}: InputBarProps) {
+  const [value, setValue] = useState("");
+
+  const handleSubmit = (text: string) => {
+    if (text.trim() && !disabled) {
+      onSubmit(text.trim());
+      setValue("");
+    }
+  };
+
+  return (
+    <Box flexDirection="column">
+      <Box>
+        <Text color={colors.primary} bold>
+          {">"}{" "}
+        </Text>
+        {disabled ? (
+          <Text color={colors.dim}>{placeholder}</Text>
+        ) : (
+          <TextInput
+            value={value}
+            onChange={setValue}
+            onSubmit={handleSubmit}
+            placeholder={placeholder}
+          />
+        )}
+      </Box>
+      <Box>
+        <Text color={colors.dim}>
+          {isStreaming
+            ? "Ctrl+C cancel stream │ Ctrl+D quit"
+            : "Enter send │ Tab debug │ Ctrl+D quit"}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
diff --git a/src/services/ai-transport-demo/ui/ServerPanel.tsx b/src/services/ai-transport-demo/ui/ServerPanel.tsx
new file mode 100644
index 000000000..5672ca3db
--- /dev/null
+++ b/src/services/ai-transport-demo/ui/ServerPanel.tsx
@@ -0,0 +1,79 @@
+/**
+ * Server panel — shows the server-side log of activity.
+ * The server IS the log. No separate events section.
+ */
+
+import React from "react";
+import { Box, Text } from "ink";
+import type { LogEntry } from "./hooks/use-scrollable-log.js";
+import { colors, symbols } from "./theme.js";
+
+interface ServerPanelProps {
+  entries: LogEntry[];
+  port?: number;
+  isRunning: boolean;
+  maxVisible?: number;
+}
+
+export function ServerPanel({
+  entries,
+  port,
+  isRunning,
+  maxVisible = 20,
+}: ServerPanelProps) {
+  // Show the most recent entries
+  const visible = entries.slice(-maxVisible);
+
+  return (
+    <Box flexDirection="column" flexGrow={1}>
+      {/* Header */}
+      <Box>
+        <Text bold>
+          {symbols.server} Server
+          {port ? (
+            <Text color={isRunning ? colors.success : colors.dim}>
+              {" "}
+              {isRunning ? `${symbols.listening} :${port}` : "(stopped)"}
+            </Text>
+          ) : (
+            <Text color={colors.dim}> (starting...)</Text>
+          )}
+        </Text>
+      </Box>
+
+      {/* Log entries */}
+      <Box flexDirection="column" flexGrow={1} marginTop={1}>
+        {visible.length === 0 && (
+          <Text color={colors.dim}>Waiting for activity...</Text>
+        )}
+        {visible.map((entry, i) => (
+          <Text key={i} wrap="truncate">
+            <Text color={colors.dim}>{entry.timestamp}</Text>{" "}
+            <Text>{colorizeLogMessage(entry.message)}</Text>
+          </Text>
+        ))}
+      </Box>
+    </Box>
+  );
+}
+
+function colorizeLogMessage(message: string): React.ReactElement {
+  // Colorize based on message content
+  if (message.startsWith(symbols.incoming)) {
+    return <Text color={colors.primary}>{message}</Text>;
+  }
+
+  if (message.startsWith(symbols.outgoing)) {
+    return <Text color={colors.assistant}>{message}</Text>;
+  }
+
+  if (message.startsWith(symbols.feature)) {
+    return <Text color={colors.event}>{message}</Text>;
+  }
+
+  if (message.includes("error") || message.includes("Error")) {
+    return <Text color={colors.error}>{message}</Text>;
+  }
+
+  return <Text>{message}</Text>;
+}
diff --git a/src/services/ai-transport-demo/ui/hooks/use-scrollable-log.ts b/src/services/ai-transport-demo/ui/hooks/use-scrollable-log.ts
new file mode 100644
index 000000000..06935e576
--- /dev/null
+++ b/src/services/ai-transport-demo/ui/hooks/use-scrollable-log.ts
@@ -0,0 +1,44 @@
+/**
+ * Hook for managing a scrollable log of timestamped entries.
+ */
+
+import { useState, useCallback } from "react";
+
+export interface LogEntry {
+  timestamp: string;
+  message: string;
+}
+
+function formatTime(): string {
+  const now = new Date();
+  return now.toLocaleTimeString("en-GB", {
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    fractionalSecondDigits: 3,
+  });
+}
+
+export function useScrollableLog(maxEntries = 200) {
+  const [entries, setEntries] = useState<LogEntry[]>([]);
+
+  const addEntry = useCallback(
+    (message: string) => {
+      setEntries((prev) => {
+        const next = [...prev, { timestamp: formatTime(), message }];
+        if (next.length > maxEntries) {
+          return next.slice(next.length - maxEntries);
+        }
+
+        return next;
+      });
+    },
+    [maxEntries],
+  );
+
+  const clear = useCallback(() => {
+    setEntries([]);
+  }, []);
+
+  return { entries, addEntry, clear };
+}
diff --git a/src/services/ai-transport-demo/ui/theme.ts b/src/services/ai-transport-demo/ui/theme.ts
new file mode 100644
index 000000000..861718169
--- /dev/null
+++ b/src/services/ai-transport-demo/ui/theme.ts
@@ -0,0 +1,50 @@
+/**
+ * Shared theme constants for the demo TUI.
+ * Consistent with the CLI's existing chalk color scheme.
+ */
+
+export const colors = {
+  /** Primary elements — command names, resources */
+  primary: "cyan",
+  /** Success messages */
+  success: "green",
+  /** Warnings */
+  warning: "yellow",
+  /** Error messages */
+  error: "red",
+  /** User messages */
+  user: "white",
+  /** Assistant/agent messages */
+  assistant: "whiteBright",
+  /** Timestamps and secondary info */
+  dim: "gray",
+  /** Event types and labels */
+  event: "yellow",
+  /** Client ID / user identity */
+  clientId: "blue",
+  /** Panel borders */
+  border: "gray",
+  /** Active/highlighted border */
+  activeBorder: "cyan",
+  /** Header text */
+  header: "bold",
+} as const;
+
+export const symbols = {
+  /** Server listening indicator */
+  listening: "●",
+  /** Incoming message */
+  incoming: "←",
+  /** Outgoing message/token */
+  outgoing: "→",
+  /** Warning */
+  warn: "⚠",
+  /** Feature highlight */
+  feature: "⚡",
+  /** Debug toggle hint */
+  debug: "🔍",
+  /** Client panel */
+  client: "💬",
+  /** Server panel */
+  server: "🖥",
+} as const;
diff --git a/test/unit/commands/ai-transport/demo/lib/client-discovery.test.ts b/test/unit/commands/ai-transport/demo/lib/client-discovery.test.ts
index 63db625db..a2ff09011 100644
--- a/test/unit/commands/ai-transport/demo/lib/client-discovery.test.ts
+++ b/test/unit/commands/ai-transport/demo/lib/client-discovery.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import { discoverServer } from "../../../../../../src/commands/ai-transport/demo/lib/client-discovery.js";
+import { discoverServer } from "../../../../../../src/services/ai-transport-demo/lib/client-discovery.js";
 
 function createMockChannel(opts?: {
   presenceMembers?: Array<{ data: unknown; clientId?: string; action?: string }>;
diff --git a/test/unit/commands/ai-transport/demo/lib/codec.test.ts b/test/unit/commands/ai-transport/demo/lib/codec.test.ts
index 494bff592..b73404489 100644
--- a/test/unit/commands/ai-transport/demo/lib/codec.test.ts
+++ b/test/unit/commands/ai-transport/demo/lib/codec.test.ts
@@ -2,8 +2,8 @@ import { describe, it, expect } from "vitest";
 import {
   DemoCodec,
   type DemoMessage,
-} from "../../../../../../src/commands/ai-transport/demo/lib/codec.js";
-import type { FakeLLMEvent } from "../../../../../../src/commands/ai-transport/demo/lib/fake-llm.js";
+} from "../../../../../../src/services/ai-transport-demo/lib/codec.js";
+import type { FakeLLMEvent } from "../../../../../../src/services/ai-transport-demo/lib/fake-llm.js";
 
 describe("DemoCodec", () => {
   describe("isTerminal", () => {
diff --git a/test/unit/commands/ai-transport/demo/lib/fake-llm.test.ts b/test/unit/commands/ai-transport/demo/lib/fake-llm.test.ts
index 2af8591d5..7b8743ae9 100644
--- a/test/unit/commands/ai-transport/demo/lib/fake-llm.test.ts
+++ b/test/unit/commands/ai-transport/demo/lib/fake-llm.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect } from "vitest";
 import {
   createFakeLLMStream,
   type FakeLLMEvent,
-} from "../../../../../../src/commands/ai-transport/demo/lib/fake-llm.js";
+} from "../../../../../../src/services/ai-transport-demo/lib/fake-llm.js";
 
 async function collectEvents(
   stream: ReadableStream<FakeLLMEvent>,
diff --git a/test/unit/commands/ai-transport/demo/lib/mutable-messages.test.ts b/test/unit/commands/ai-transport/demo/lib/mutable-messages.test.ts
index 3751b877c..c2a284797 100644
--- a/test/unit/commands/ai-transport/demo/lib/mutable-messages.test.ts
+++ b/test/unit/commands/ai-transport/demo/lib/mutable-messages.test.ts
@@ -4,7 +4,7 @@ import {
   checkViaControlApi,
   checkViaDataPlane,
   enableMutableMessages,
-} from "../../../../../../src/commands/ai-transport/demo/lib/mutable-messages.js";
+} from "../../../../../../src/services/ai-transport-demo/lib/mutable-messages.js";
 import type { ControlApi } from "../../../../../../src/services/control-api.js";
 
 function createMockControlApi(
diff --git a/test/unit/commands/ai-transport/demo/lib/server.test.ts b/test/unit/commands/ai-transport/demo/lib/server.test.ts
index ce461807c..63e074771 100644
--- a/test/unit/commands/ai-transport/demo/lib/server.test.ts
+++ b/test/unit/commands/ai-transport/demo/lib/server.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, vi, afterEach } from "vitest";
 import {
   createDemoServer,
   type DemoServer,
-} from "../../../../../../src/commands/ai-transport/demo/lib/server.js";
+} from "../../../../../../src/services/ai-transport-demo/lib/server.js";
 
 function createMockChannel() {
   return {

From 9a5861d9bd1f4434f48113860ff1d70eab3dd0f0 Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Wed, 15 Apr 2026 22:14:30 +0200
Subject: [PATCH 05/17] fix: redesign TUI layout and fix Ink CI rendering issue
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Move debug console and input bar inside the client panel border
  for a clearer client/server separation
- Debug events always visible (2 lines default, Tab expands to 8)
- Input bar with Claude Code-style prompt inside client panel
- Server panel as standalone log with space for future controls
- Fix Ink not rendering due to CI_* env var triggering is-in-ci
  detection — dynamically import ink after setting CI=0
- Use round border style for cleaner panel appearance

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/commands/ai-transport/demo/streaming.ts   |  40 +++--
 src/services/ai-transport-demo/ui/App.tsx     | 152 +++++++++++-------
 .../ai-transport-demo/ui/ClientPanel.tsx      | 102 +++++-------
 .../ai-transport-demo/ui/DebugPanel.tsx       |  41 +++--
 .../ai-transport-demo/ui/InputBar.tsx         |  24 ++-
 5 files changed, 191 insertions(+), 168 deletions(-)

diff --git a/src/commands/ai-transport/demo/streaming.ts b/src/commands/ai-transport/demo/streaming.ts
index d4ce9e633..550570c15 100644
--- a/src/commands/ai-transport/demo/streaming.ts
+++ b/src/commands/ai-transport/demo/streaming.ts
@@ -1,11 +1,9 @@
 import React from "react";
 import { Flags } from "@oclif/core";
-import { render } from "ink";
 
 import { ControlBaseCommand } from "../../../control-base-command.js";
 import { productApiFlags } from "../../../flags.js";
 import isTestMode from "../../../utils/test-mode.js";
-import { App } from "../../../services/ai-transport-demo/ui/App.js";
 
 export default class StreamingDemo extends ControlBaseCommand {
   static override description =
@@ -70,15 +68,35 @@ export default class StreamingDemo extends ControlBaseCommand {
       return;
     }
 
-    // Render the TUI
-    const { waitUntilExit } = render(
-      React.createElement(App, {
-        role,
-        feature: "streaming",
-        channelName,
-      }),
-    );
+    // Ink's is-in-ci detects any env var starting with CI_ and suppresses
+    // interactive output. CI_BYPASS_SECRET or similar vars trigger this even
+    // on dev machines. We must set CI=0 before importing ink so the module-level
+    // check evaluates to false.
+    const prevCi = process.env.CI;
+    process.env.CI = "0";
 
-    await waitUntilExit();
+    try {
+      // Dynamic import so CI=0 is set before ink's is-in-ci evaluates
+      const { render } = await import("ink");
+      const { App } = await import(
+        "../../../services/ai-transport-demo/ui/App.js"
+      );
+
+      const { waitUntilExit } = render(
+        React.createElement(App, {
+          role,
+          feature: "streaming",
+          channelName,
+        }),
+      );
+
+      await waitUntilExit();
+    } finally {
+      if (prevCi === undefined) {
+        delete process.env.CI;
+      } else {
+        process.env.CI = prevCi;
+      }
+    }
   }
 }
diff --git a/src/services/ai-transport-demo/ui/App.tsx b/src/services/ai-transport-demo/ui/App.tsx
index 17bde197c..5818a3683 100644
--- a/src/services/ai-transport-demo/ui/App.tsx
+++ b/src/services/ai-transport-demo/ui/App.tsx
@@ -1,11 +1,12 @@
 /**
  * Root Ink component for AI Transport demos.
  *
- * Renders the split-pane TUI with client (left) and server (right) panels,
- * a debug console, and an input bar.
+ * Two clear panels side by side:
+ * - Client (left): conversation + debug events + input — all inside one border
+ * - Server (right): activity log, with space for future controls at the bottom
  */
 
-import React, { useState } from "react";
+import React, { useState, useEffect } from "react";
 import { Box, Text, useApp, useInput, useStdout } from "ink";
 import { ClientPanel, type ConversationMessage } from "./ClientPanel.js";
 import { ServerPanel } from "./ServerPanel.js";
@@ -15,15 +16,10 @@ import { useScrollableLog } from "./hooks/use-scrollable-log.js";
 import { colors } from "./theme.js";
 
 export interface AppProps {
-  /** Which role the demo is running as. */
   role: "both" | "client" | "server";
-  /** The demo feature name. */
   feature: string;
-  /** The Ably channel name. */
   channelName: string;
-  /** Callback when user submits a message. */
   onSendMessage?: (text: string) => void;
-  /** Callback when user requests cancel (Ctrl+C). */
   onCancel?: () => void;
 }
 
@@ -36,22 +32,32 @@ export function App({
 }: AppProps) {
   const { exit } = useApp();
   const { stdout } = useStdout();
-  const terminalHeight = stdout?.rows ?? 24;
-  const terminalWidth = stdout?.columns ?? 80;
+  const [dims, setDims] = useState({
+    width: stdout?.columns ?? 80,
+    height: stdout?.rows ?? 24,
+  });
 
   const [debugExpanded, setDebugExpanded] = useState(false);
   const [isStreaming] = useState(false);
-
-  // Placeholder conversation messages
   const [messages] = useState<ConversationMessage[]>([]);
 
-  // Server log
   const serverLog = useScrollableLog();
-
-  // Debug log
   const debugLog = useScrollableLog();
 
-  // Keyboard handling
+  useEffect(() => {
+    const onResize = () => {
+      setDims({
+        width: stdout?.columns ?? 80,
+        height: stdout?.rows ?? 24,
+      });
+    };
+
+    stdout?.on("resize", onResize);
+    return () => {
+      stdout?.off("resize", onResize);
+    };
+  }, [stdout]);
+
   useInput((input, key) => {
     if (input === "d" && key.ctrl) {
       exit();
@@ -75,66 +81,104 @@ export function App({
   const showClient = role === "both" || role === "client";
   const showServer = role === "both" || role === "server";
 
-  // Calculate panel heights
-  const debugHeight = debugExpanded ? 8 : 1;
-  const inputHeight = 2;
-  const mainHeight = terminalHeight - debugHeight - inputHeight - 2;
+  const clientWidth = showServer ? Math.floor(dims.width * 0.6) : dims.width;
+
+  // Debug: 2 lines always visible, 8 when expanded
+  const debugLines = debugExpanded ? 8 : 2;
 
   return (
-    <Box flexDirection="column" height={terminalHeight}>
-      {/* Main panels */}
-      <Box flexDirection="row" height={mainHeight}>
-        {showClient && (
-          <Box
-            flexDirection="column"
-            flexGrow={showServer ? 2 : 1}
-            borderStyle="single"
-            borderColor={colors.activeBorder}
-            paddingX={1}
-            width={showServer ? Math.floor(terminalWidth * 0.6) : undefined}
-          >
+    <Box flexDirection="row" height={dims.height} width={dims.width}>
+      {/* ── Client panel ── */}
+      {showClient && (
+        <Box
+          flexDirection="column"
+          borderStyle="round"
+          borderColor={colors.activeBorder}
+          width={clientWidth}
+        >
+          {/* Header */}
+          <Box paddingX={1}>
+            <Text bold>
+              💬 AI Transport Demo:{" "}
+              <Text color={colors.primary}>{formatFeatureName(feature)}</Text>
+            </Text>
+          </Box>
+          <Box paddingX={1}>
+            <Text color={colors.dim}>Channel: {channelName}</Text>
+          </Box>
+
+          {/* Conversation area — fills available space */}
+          <Box flexDirection="column" flexGrow={1} paddingX={1} marginTop={1}>
             <ClientPanel
-              feature={feature}
-              channelName={channelName}
               messages={messages}
               serverStatus="connected"
-              maxVisible={mainHeight - 4}
+              isStreaming={isStreaming}
             />
           </Box>
-        )}
 
-        {showServer && (
+          {/* Debug events — always visible, 2 lines default */}
           <Box
             flexDirection="column"
-            flexGrow={1}
+            paddingX={1}
             borderStyle="single"
+            borderTop
+            borderBottom={false}
+            borderLeft={false}
+            borderRight={false}
             borderColor={colors.border}
+          >
+            <DebugPanel
+              entries={debugLog.entries}
+              expanded={debugExpanded}
+              visibleLines={debugLines}
+            />
+          </Box>
+
+          {/* Input — part of the client panel */}
+          <Box
             paddingX={1}
+            borderStyle="single"
+            borderTop
+            borderBottom={false}
+            borderLeft={false}
+            borderRight={false}
+            borderColor={colors.border}
           >
+            <InputBar onSubmit={handleSendMessage} isStreaming={isStreaming} />
+          </Box>
+        </Box>
+      )}
+
+      {/* ── Server panel ── */}
+      {showServer && (
+        <Box
+          flexDirection="column"
+          flexGrow={1}
+          borderStyle="round"
+          borderColor={colors.border}
+        >
+          {/* Server log — fills the panel */}
+          <Box flexDirection="column" flexGrow={1} paddingX={1}>
             <ServerPanel
               entries={serverLog.entries}
               isRunning={false}
-              maxVisible={mainHeight - 3}
+              maxVisible={dims.height - 4}
             />
           </Box>
-        )}
-      </Box>
-
-      {/* Debug panel (client side only in both mode) */}
-      {showClient && (
-        <DebugPanel entries={debugLog.entries} expanded={debugExpanded} />
-      )}
 
-      {/* Input bar (only when client is shown) */}
-      {showClient ? (
-        <InputBar onSubmit={handleSendMessage} isStreaming={isStreaming} />
-      ) : (
-        <Box>
-          <Text color={colors.dim}>
-            Server mode — no input. Ctrl+D to quit.
-          </Text>
+          {/* Future: server controls bar would go here */}
+          {/* <Box paddingX={1} borderStyle="single" borderTop ...>
+               Restart │ Disconnect │ Kill stream
+             </Box> */}
         </Box>
       )}
     </Box>
   );
 }
+
+function formatFeatureName(feature: string): string {
+  return feature
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
diff --git a/src/services/ai-transport-demo/ui/ClientPanel.tsx b/src/services/ai-transport-demo/ui/ClientPanel.tsx
index 4a4b76574..a7e9827b2 100644
--- a/src/services/ai-transport-demo/ui/ClientPanel.tsx
+++ b/src/services/ai-transport-demo/ui/ClientPanel.tsx
@@ -1,5 +1,6 @@
 /**
- * Client panel — shows the conversation (user messages + assistant responses).
+ * Client panel — the conversation area showing user messages and agent responses.
+ * Header, debug, and input are handled by App; this is just the message list.
  */
 
 import React from "react";
@@ -10,96 +11,65 @@ export interface ConversationMessage {
   id: string;
   role: "user" | "assistant";
   content: string;
-  /** Whether this message is still being streamed. */
   streaming?: boolean;
-  /** Whether this message was interrupted (barge-in). */
   interrupted?: boolean;
 }
 
 interface ClientPanelProps {
-  feature: string;
-  channelName: string;
   messages: ConversationMessage[];
   serverStatus: "connecting" | "connected" | "not-found";
-  maxVisible?: number;
+  isStreaming: boolean;
 }
 
 export function ClientPanel({
-  feature,
-  channelName,
   messages,
   serverStatus,
-  maxVisible = 20,
+  isStreaming,
 }: ClientPanelProps) {
-  const visible = messages.slice(-maxVisible);
-
   return (
     <Box flexDirection="column" flexGrow={1}>
-      {/* Header */}
-      <Box flexDirection="column">
-        <Text bold>
-          💬 AI Transport Demo:{" "}
-          <Text color={colors.primary}>{formatFeatureName(feature)}</Text>
-        </Text>
-        <Text color={colors.dim}>Channel: {channelName}</Text>
-      </Box>
-
-      {/* Server status */}
       {serverStatus === "not-found" && (
-        <Box marginTop={1}>
-          <Text color={colors.warning}>
-            ⚠ No server detected. Start a server or use --endpoint.
-          </Text>
-        </Box>
+        <Text color={colors.warning}>
+          ⚠ No server detected. Start a server or use --endpoint.
+        </Text>
       )}
       {serverStatus === "connecting" && (
-        <Box marginTop={1}>
-          <Text color={colors.dim}>Connecting to server...</Text>
-        </Box>
+        <Text color={colors.dim}>Connecting to server...</Text>
       )}
 
-      {/* Conversation */}
-      <Box flexDirection="column" flexGrow={1} marginTop={1}>
-        {visible.length === 0 && serverStatus === "connected" && (
+      {messages.length === 0 &&
+        serverStatus === "connected" &&
+        !isStreaming && (
           <Text color={colors.dim}>
             Type a message below to start the demo.
           </Text>
         )}
-        {visible.map((msg) => (
-          <Box key={msg.id} flexDirection="column" marginBottom={1}>
-            {msg.role === "user" ? (
-              <Text>
-                <Text color={colors.user} bold>
-                  You:{" "}
-                </Text>
-                <Text>{msg.content}</Text>
+
+      {messages.map((msg) => (
+        <Box key={msg.id} flexDirection="column" marginBottom={1}>
+          {msg.role === "user" ? (
+            <Text>
+              <Text color={colors.user} bold>
+                You:{" "}
+              </Text>
+              <Text>{msg.content}</Text>
+            </Text>
+          ) : (
+            <Text>
+              <Text color={colors.primary} bold>
+                Agent:{" "}
+              </Text>
+              <Text color={colors.assistant}>
+                {msg.content}
+                {msg.streaming && <Text color={colors.dim}>▊</Text>}
+                {msg.interrupted && (
+                  <Text color={colors.warning}> [interrupted]</Text>
+                )}
               </Text>
-            ) : (
-              <Box flexDirection="column">
-                <Text>
-                  <Text color={colors.primary} bold>
-                    Agent:{" "}
-                  </Text>
-                  <Text color={colors.assistant}>
-                    {msg.content}
-                    {msg.streaming && <Text color={colors.dim}>▊</Text>}
-                    {msg.interrupted && (
-                      <Text color={colors.warning}> [interrupted]</Text>
-                    )}
-                  </Text>
-                </Text>
-              </Box>
-            )}
-          </Box>
-        ))}
-      </Box>
+            </Text>
+          )}
+        </Box>
+      ))}
     </Box>
   );
 }
-
-function formatFeatureName(feature: string): string {
-  return feature
-    .split("-")
-    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-    .join(" ");
-}
diff --git a/src/services/ai-transport-demo/ui/DebugPanel.tsx b/src/services/ai-transport-demo/ui/DebugPanel.tsx
index 885f60653..d3400d6b9 100644
--- a/src/services/ai-transport-demo/ui/DebugPanel.tsx
+++ b/src/services/ai-transport-demo/ui/DebugPanel.tsx
@@ -1,5 +1,6 @@
 /**
- * Collapsible debug console showing transport-level events.
+ * Debug console showing transport-level events.
+ * Always shows at least a few lines; Tab toggles between compact and expanded.
  */
 
 import React from "react";
@@ -10,39 +11,33 @@ import { colors } from "./theme.js";
 interface DebugPanelProps {
   entries: LogEntry[];
   expanded: boolean;
-  maxVisible?: number;
+  /** Number of lines to show (2 compact, 8 expanded) */
+  visibleLines?: number;
 }
 
 export function DebugPanel({
   entries,
   expanded,
-  maxVisible = 6,
+  visibleLines = 2,
 }: DebugPanelProps) {
-  if (!expanded) {
-    return (
-      <Box>
-        <Text color={colors.dim}>
-          🔍 Debug ({entries.length} events) — Tab to expand
-        </Text>
-      </Box>
-    );
-  }
-
-  const visible = entries.slice(-maxVisible);
+  const visible = entries.slice(-visibleLines);
+  const hiddenCount = Math.max(0, entries.length - visibleLines);
 
   return (
-    <Box
-      flexDirection="column"
-      borderStyle="single"
-      borderColor={colors.dim}
-      paddingX={1}
-    >
-      <Text bold color={colors.dim}>
-        🔍 Debug — Tab to collapse
+    <Box flexDirection="column">
+      <Text color={colors.dim}>
+        🔍 Debug{" "}
+        {hiddenCount > 0 && !expanded && (
+          <Text color={colors.dim}>({hiddenCount} more) </Text>
+        )}
+        <Text color={colors.dim}>— Tab {expanded ? "less" : "more"}</Text>
       </Text>
-      {visible.length === 0 && <Text color={colors.dim}>No events yet.</Text>}
+      {visible.length === 0 && (
+        <Text color={colors.dim}> Waiting for events...</Text>
+      )}
       {visible.map((entry, i) => (
         <Text key={i} wrap="truncate" color={colors.dim}>
+          {"  "}
           {entry.timestamp} {entry.message}
         </Text>
       ))}
diff --git a/src/services/ai-transport-demo/ui/InputBar.tsx b/src/services/ai-transport-demo/ui/InputBar.tsx
index d5b6a1f11..3e3d3d7fe 100644
--- a/src/services/ai-transport-demo/ui/InputBar.tsx
+++ b/src/services/ai-transport-demo/ui/InputBar.tsx
@@ -1,5 +1,5 @@
 /**
- * Text input bar at the bottom of the TUI.
+ * Text input — sits inside the client panel, Claude Code-style.
  */
 
 import React, { useState } from "react";
@@ -11,14 +11,12 @@ interface InputBarProps {
   onSubmit: (text: string) => void;
   isStreaming: boolean;
   disabled?: boolean;
-  placeholder?: string;
 }
 
 export function InputBar({
   onSubmit,
   isStreaming,
   disabled = false,
-  placeholder = "Type a message...",
 }: InputBarProps) {
   const [value, setValue] = useState("");
 
@@ -32,27 +30,25 @@ export function InputBar({
   return (
     <Box flexDirection="column">
       <Box>
-        <Text color={colors.primary} bold>
-          {">"}{" "}
+        <Text color={colors.success} bold>
+          {"❯ "}
         </Text>
         {disabled ? (
-          <Text color={colors.dim}>{placeholder}</Text>
+          <Text color={colors.dim}>Waiting for server...</Text>
         ) : (
           <TextInput
             value={value}
             onChange={setValue}
             onSubmit={handleSubmit}
-            placeholder={placeholder}
+            placeholder="Type a message..."
           />
         )}
       </Box>
-      <Box>
-        <Text color={colors.dim}>
-          {isStreaming
-            ? "Ctrl+C cancel stream │ Ctrl+D quit"
-            : "Enter send │ Tab debug │ Ctrl+D quit"}
-        </Text>
-      </Box>
+      <Text color={colors.dim}>
+        {isStreaming
+          ? "  Ctrl+C cancel │ Ctrl+D quit"
+          : "  Enter send │ Tab debug │ Ctrl+D quit"}
+      </Text>
     </Box>
   );
 }

From 0f6c3135479c6449881a86e7a7c4bee23f14100b Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Wed, 15 Apr 2026 23:07:27 +0200
Subject: [PATCH 06/17] feat: wire streaming demo end-to-end with error
 handling

- Orchestrator connects server transport, client transport, HTTP server,
  and fake LLM via the @ably/ai-transport SDK
- useDemo hook connects orchestrator events to React UI state
- Graceful mutable messages (93002) error handling: detects the error,
  closes Ably connection to stop NACK flood, shows setup instructions
- Fix duplicate user messages (don't re-publish from server)
- Fix turn.end() crash after connection close

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/commands/ai-transport/demo/streaming.ts   |  76 +++-
 .../ai-transport-demo/lib/orchestrator.ts     | 325 ++++++++++++++++++
 src/services/ai-transport-demo/lib/server.ts  |  31 +-
 src/services/ai-transport-demo/ui/App.tsx     | 147 ++++++--
 .../ai-transport-demo/ui/hooks/use-demo.ts    |  96 ++++++
 5 files changed, 627 insertions(+), 48 deletions(-)
 create mode 100644 src/services/ai-transport-demo/lib/orchestrator.ts
 create mode 100644 src/services/ai-transport-demo/ui/hooks/use-demo.ts

diff --git a/src/commands/ai-transport/demo/streaming.ts b/src/commands/ai-transport/demo/streaming.ts
index 550570c15..597b798cc 100644
--- a/src/commands/ai-transport/demo/streaming.ts
+++ b/src/commands/ai-transport/demo/streaming.ts
@@ -2,8 +2,10 @@ import React from "react";
 import { Flags } from "@oclif/core";
 
 import { ControlBaseCommand } from "../../../control-base-command.js";
-import { productApiFlags } from "../../../flags.js";
+import { productApiFlags, clientIdFlag } from "../../../flags.js";
 import isTestMode from "../../../utils/test-mode.js";
+import { createOrchestrator } from "../../../services/ai-transport-demo/lib/orchestrator.js";
+import type { DemoOrchestrator } from "../../../services/ai-transport-demo/lib/orchestrator.js";
 
 export default class StreamingDemo extends ControlBaseCommand {
   static override description =
@@ -17,6 +19,7 @@ export default class StreamingDemo extends ControlBaseCommand {
 
   static override flags = {
     ...productApiFlags,
+    ...clientIdFlag,
     role: Flags.string({
       description: "Run as both client and server, or just one side",
       options: ["both", "client", "server"],
@@ -35,6 +38,9 @@ export default class StreamingDemo extends ControlBaseCommand {
     }),
   };
 
+  private orchestrator: DemoOrchestrator | null = null;
+  private ablyClient: import("ably").Realtime | null = null;
+
   async run(): Promise<void> {
     const { flags } = await this.parse(StreamingDemo);
 
@@ -58,8 +64,10 @@ export default class StreamingDemo extends ControlBaseCommand {
     const channelName =
       flags.channel ??
       `ai-demo:streaming-${Math.random().toString(36).slice(2, 6)}`;
+    const clientId =
+      flags["client-id"] ?? `demo-${Math.random().toString(36).slice(2, 8)}`;
 
-    // In test mode, just output a marker and return (Ink can't render in tests)
+    // In test mode, output a marker and return (Ink can't render in tests)
     if (isTestMode()) {
       this.log(
         `AI Transport Streaming Demo (coming soon). ` +
@@ -68,15 +76,52 @@ export default class StreamingDemo extends ControlBaseCommand {
       return;
     }
 
-    // Ink's is-in-ci detects any env var starting with CI_ and suppresses
-    // interactive output. CI_BYPASS_SECRET or similar vars trigger this even
-    // on dev machines. We must set CI=0 before importing ink so the module-level
-    // check evaluates to false.
+    // Create Ably client
+    this.ablyClient = await this.createAblyRealtimeClient(flags);
+    if (!this.ablyClient) {
+      this.fail("Failed to create Ably client", flags, "aiTransportDemo");
+    }
+
+    const channel = this.ablyClient.channels.get(channelName);
+
+    // Create the orchestrator (startup is triggered by the App component
+    // after event listeners are attached, so no events are missed)
+    this.orchestrator = createOrchestrator({
+      channel,
+      feature: "streaming",
+      endpoint: flags.endpoint,
+      clientId,
+      onFatalError: () => {
+        // Close the Ably connection to stop the SDK retrying
+        if (this.ablyClient) {
+          this.ablyClient.close();
+          this.ablyClient = null;
+        }
+      },
+    });
+
+    // Catch unhandled errors from the Ably SDK (e.g., mutable messages 93002)
+    // that are thrown from WebSocket message handlers outside our try/catch.
+    // We emit the event on the orchestrator so the TUI shows the setup screen.
+    const orchestratorRef = this.orchestrator;
+    const unhandledHandler = (error: Error) => {
+      const msg = String(error);
+      if (msg.includes("93002") || msg.includes("mutableMessages")) {
+        orchestratorRef?.emit("mutableMessagesRequired");
+        return;
+      }
+
+      // For other errors, log to stderr but don't crash the TUI
+      process.stderr.write(`Unhandled error: ${msg}\n`);
+    };
+
+    process.on("uncaughtException", unhandledHandler);
+
+    // Bypass Ink's CI detection (CI_* env vars trigger is-in-ci)
     const prevCi = process.env.CI;
     process.env.CI = "0";
 
     try {
-      // Dynamic import so CI=0 is set before ink's is-in-ci evaluates
       const { render } = await import("ink");
       const { App } = await import(
         "../../../services/ai-transport-demo/ui/App.js"
@@ -87,11 +132,14 @@ export default class StreamingDemo extends ControlBaseCommand {
           role,
           feature: "streaming",
           channelName,
+          orchestrator: this.orchestrator,
         }),
       );
 
       await waitUntilExit();
     } finally {
+      process.off("uncaughtException", unhandledHandler);
+
       if (prevCi === undefined) {
         delete process.env.CI;
       } else {
@@ -99,4 +147,18 @@ export default class StreamingDemo extends ControlBaseCommand {
       }
     }
   }
+
+  async finally(error: Error | undefined): Promise<void> {
+    if (this.orchestrator) {
+      await this.orchestrator.close();
+      this.orchestrator = null;
+    }
+
+    if (this.ablyClient) {
+      this.ablyClient.close();
+      this.ablyClient = null;
+    }
+
+    await super.finally(error);
+  }
 }
diff --git a/src/services/ai-transport-demo/lib/orchestrator.ts b/src/services/ai-transport-demo/lib/orchestrator.ts
new file mode 100644
index 000000000..cd7919f7f
--- /dev/null
+++ b/src/services/ai-transport-demo/lib/orchestrator.ts
@@ -0,0 +1,325 @@
+/**
+ * Demo orchestrator — wires the server transport, client transport,
+ * HTTP server, fake LLM, and presence discovery together.
+ *
+ * Emits events that the UI consumes to update panels.
+ */
+
+import { EventEmitter } from "node:events";
+import type * as Ably from "ably";
+import { createServerTransport, createClientTransport } from "@ably/ai-transport";
+import type {
+  ServerTransport,
+  ClientTransport,
+  TurnLifecycleEvent,
+} from "@ably/ai-transport";
+
+import { DemoCodec, type DemoMessage } from "./codec.js";
+import { createFakeLLMStream, type FakeLLMEvent } from "./fake-llm.js";
+import {
+  createDemoServer,
+  type DemoServer,
+  type AitRequestBody,
+} from "./server.js";
+import { discoverServer } from "./client-discovery.js";
+
+export interface OrchestratorOptions {
+  /** The Ably channel for the demo. */
+  channel: Ably.RealtimeChannel;
+  /** Which demo feature is running. */
+  feature: string;
+  /** Optional endpoint to use instead of presence discovery. */
+  endpoint?: string;
+  /** Client ID for presence and messages. */
+  clientId: string;
+  /** Called when the Ably connection should be closed (e.g., fatal config error). */
+  onFatalError?: () => void;
+}
+
+/** Error code for mutable messages not enabled. */
+const MUTABLE_MESSAGES_ERROR_CODE = 93002;
+
+export interface DemoOrchestrator extends EventEmitter {
+  startServer(): Promise<void>;
+  startClient(): Promise<void>;
+  sendMessage(text: string): Promise<void>;
+  cancelActiveTurn(): Promise<void>;
+  isStreaming(): boolean;
+  close(): Promise<void>;
+
+  on(event: "serverLog", listener: (message: string) => void): this;
+  on(event: "debugLog", listener: (message: string) => void): this;
+  on(event: "messages", listener: (msgs: DemoMessage[]) => void): this;
+  on(event: "serverReady", listener: (data: { port: number }) => void): this;
+  on(event: "clientConnected", listener: () => void): this;
+  on(event: "turnEnd", listener: (data: { turnId: string; reason: string }) => void): this;
+  on(event: "mutableMessagesRequired", listener: () => void): this;
+  on(event: "error", listener: (error: Error) => void): this;
+}
+
+export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrator {
+  const { channel, feature, endpoint: explicitEndpoint, clientId, onFatalError } = options;
+  const emitter = new EventEmitter() as DemoOrchestrator;
+
+  let demoServer: DemoServer | null = null;
+  let serverTransport: ServerTransport<FakeLLMEvent, DemoMessage> | null = null;
+  let clientTransport: ClientTransport<FakeLLMEvent, DemoMessage> | null = null;
+  let serverEndpoint: string | null = explicitEndpoint ?? null;
+  let activeTurnAbort: AbortController | null = null;
+  let streaming = false;
+
+  // ── Server side ──
+
+  emitter.startServer = async () => {
+    emitter.emit("serverLog", "Starting server...");
+
+    serverTransport = createServerTransport<FakeLLMEvent, DemoMessage>({
+      channel,
+      codec: DemoCodec,
+    });
+
+    demoServer = await createDemoServer({
+      channel,
+      onRequest: (body: AitRequestBody) => {
+        handleServerRequest(body);
+      },
+    });
+
+    demoServer.events.on("log", (msg: string) => {
+      emitter.emit("serverLog", msg);
+    });
+
+    serverEndpoint = demoServer.url;
+    emitter.emit("serverReady", { port: demoServer.port });
+    emitter.emit("serverLog", `Ready on :${demoServer.port}`);
+  };
+
+  async function handleServerRequest(body: AitRequestBody) {
+    if (!serverTransport) return;
+
+    // Extract user message text from the AIT SDK's POST body
+    const userMessage =
+      body.messages?.[0]?.message?.content ?? "(empty message)";
+    const turnId = body.turnId;
+
+    const abortController = new AbortController();
+    activeTurnAbort = abortController;
+    streaming = true;
+
+    emitter.emit("serverLog", `→ turn:start ${turnId.slice(0, 8)}…`);
+
+    let turn: ReturnType<typeof serverTransport.newTurn> | null = null;
+
+    try {
+      turn = serverTransport.newTurn({
+        turnId,
+        clientId: body.clientId ?? clientId,
+      });
+
+      await turn.start();
+
+      // Note: we do NOT call turn.addMessages() here because the client
+      // transport already published the user message to the channel when
+      // it called send(). Re-publishing would cause a duplicate.
+
+      // Stream fake LLM response through the encoder
+      const llmStream = createFakeLLMStream({
+        feature,
+        userMessage,
+        signal: abortController.signal,
+      });
+
+      emitter.emit("serverLog", "→ streaming response...");
+
+      const result = await turn.streamResponse(llmStream);
+
+      try {
+        await turn.end(result.reason);
+      } catch {
+        // Connection may already be closing
+      }
+
+      emitter.emit(
+        "serverLog",
+        `← turn:end ${turnId.slice(0, 8)}… (${result.reason})`,
+      );
+      emitter.emit("turnEnd", { turnId, reason: result.reason });
+    } catch (error: unknown) {
+      if (isMutableMessagesError(error)) {
+        emitter.emit("serverLog", "✗ Mutable messages not enabled");
+        // Close transports and Ably connection immediately to stop the
+        // SDK from retrying inflight operations that keep getting NACKed.
+        // Do this before emitting the event so the UI shows cleanly.
+        onFatalError?.();
+        emitter.close().catch(() => {});
+        emitter.emit("mutableMessagesRequired");
+        return;
+      }
+
+      // For non-fatal errors, try to end the turn gracefully
+      if (turn) {
+        try {
+          await turn.end("error");
+        } catch {
+          // Connection may already be closing
+        }
+      }
+
+      const errorMsg =
+        typeof error === "object" && error !== null && "message" in error
+          ? (error as { message: string }).message
+          : String(error);
+      emitter.emit(
+        "serverLog",
+        `✗ turn ${turnId.slice(0, 8)}… failed: ${errorMsg}`,
+      );
+      emitter.emit(
+        "error",
+        error instanceof Error ? error : new Error(String(error)),
+      );
+    } finally {
+      streaming = false;
+      activeTurnAbort = null;
+    }
+  }
+
+  // ── Client side ──
+
+  emitter.startClient = async () => {
+    emitter.emit("debugLog", "Starting client...");
+
+    // Discover server if no explicit endpoint
+    if (!serverEndpoint) {
+      emitter.emit("debugLog", "Discovering server via presence...");
+      const discovered = await discoverServer(channel, 10_000, (msg) => {
+        emitter.emit("debugLog", msg);
+      });
+
+      if (!discovered) {
+        emitter.emit("debugLog", "No server found");
+        return;
+      }
+
+      serverEndpoint = discovered.endpoint;
+    }
+
+    emitter.emit("debugLog", `Server at ${serverEndpoint}`);
+
+    // Create the AIT client transport
+    clientTransport = createClientTransport<FakeLLMEvent, DemoMessage>({
+      channel,
+      codec: DemoCodec,
+      clientId,
+      api: serverEndpoint,
+    });
+
+    // Subscribe to message changes — emit the full message list on each update
+    clientTransport.on("message", () => {
+      const msgs = clientTransport!.getMessages();
+      emitter.emit("messages", msgs);
+    });
+
+    // Subscribe to turn lifecycle events
+    clientTransport.on("turn", (event: TurnLifecycleEvent) => {
+      emitter.emit("debugLog", `[turn] ${event.type} (${event.turnId})`);
+    });
+
+    // Subscribe to errors
+    clientTransport.on("error", (error: Ably.ErrorInfo) => {
+      emitter.emit("debugLog", `[transport] error: ${error.message}`);
+    });
+
+    emitter.emit("clientConnected");
+    emitter.emit("debugLog", "Client connected");
+  };
+
+  emitter.sendMessage = async (text: string) => {
+    if (!clientTransport) {
+      emitter.emit("debugLog", "No client transport — cannot send");
+      return;
+    }
+
+    emitter.emit("debugLog", `Sending: "${text.slice(0, 40)}..."`);
+
+    try {
+      const userMsg: DemoMessage = {
+        id: `user-${Date.now()}`,
+        role: "user",
+        content: text,
+      };
+
+      const activeTurn = await clientTransport.send(userMsg);
+
+      // Consume the stream to drive the transport (messages arrive via 'message' event)
+      const reader = activeTurn.stream.getReader();
+      while (true) {
+        const { done } = await reader.read();
+        if (done) break;
+      }
+    } catch (error: unknown) {
+      emitter.emit("debugLog", `Send failed: ${String(error)}`);
+    }
+  };
+
+  emitter.cancelActiveTurn = async () => {
+    if (activeTurnAbort) {
+      activeTurnAbort.abort();
+      emitter.emit("debugLog", "Cancel signal sent (server-side)");
+    }
+
+    if (clientTransport) {
+      await clientTransport.cancel({ own: true });
+      emitter.emit("debugLog", "Cancel signal sent (client-side)");
+    }
+  };
+
+  emitter.isStreaming = () => streaming;
+
+  emitter.close = async () => {
+    if (activeTurnAbort) {
+      activeTurnAbort.abort();
+    }
+
+    if (clientTransport) {
+      try {
+        await clientTransport.close();
+      } catch {
+        // ignore cleanup errors
+      }
+
+      clientTransport = null;
+    }
+
+    if (serverTransport) {
+      try {
+        serverTransport.close();
+      } catch {
+        // ignore cleanup errors
+      }
+
+      serverTransport = null;
+    }
+
+    if (demoServer) {
+      await demoServer.close();
+      demoServer = null;
+    }
+  };
+
+  return emitter;
+}
+
+function isMutableMessagesError(error: unknown): boolean {
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code: number }).code === MUTABLE_MESSAGES_ERROR_CODE
+  ) {
+    return true;
+  }
+
+  // Check stringified error for the code
+  const msg = String(error);
+  return msg.includes("93002") || msg.includes("mutableMessages");
+}
diff --git a/src/services/ai-transport-demo/lib/server.ts b/src/services/ai-transport-demo/lib/server.ts
index 8a5b6c61b..23190e406 100644
--- a/src/services/ai-transport-demo/lib/server.ts
+++ b/src/services/ai-transport-demo/lib/server.ts
@@ -10,19 +10,26 @@ import { createServer, type Server, type IncomingMessage, type ServerResponse }
 import { EventEmitter } from "node:events";
 import getPort from "get-port";
 import type * as Ably from "ably";
+import { symbols } from "../ui/theme.js";
 
 export interface DemoServerOptions {
   /** The Ably channel to enter presence on. */
   channel: Ably.RealtimeChannel;
-  /** Callback when a user message is received via HTTP POST. */
-  onMessage: (body: MessageRequestBody) => void;
+  /** Callback when an AIT SDK POST request is received. */
+  onRequest: (body: AitRequestBody) => void;
 }
 
-export interface MessageRequestBody {
-  /** The user's message text. */
-  message: string;
-  /** Optional client ID. */
+/**
+ * The request body format sent by the AIT client transport's send().
+ * Contains turnId, clientId, messages (MessageWithHeaders[]), history, etc.
+ */
+export interface AitRequestBody {
+  turnId: string;
   clientId?: string;
+  messages: Array<{ message: { id: string; role: string; content: string } }>;
+  history?: unknown[];
+  parent?: string | null;
+  forkOf?: string;
 }
 
 export interface DemoServer {
@@ -49,7 +56,7 @@ export class DemoServerEvents extends EventEmitter {
 export async function createDemoServer(
   options: DemoServerOptions,
 ): Promise<DemoServer> {
-  const { channel, onMessage } = options;
+  const { channel, onRequest } = options;
   const events = new DemoServerEvents();
 
   // Find an available port
@@ -77,9 +84,13 @@ export async function createDemoServer(
         });
         req.on("end", () => {
           try {
-            const parsed = JSON.parse(body) as MessageRequestBody;
-            events.emitLog(`Received message: "${truncate(parsed.message, 50)}"`);
-            onMessage(parsed);
+            const parsed = JSON.parse(body) as AitRequestBody;
+            const firstMsg = parsed.messages?.[0]?.message;
+            const preview = firstMsg?.content
+              ? truncate(firstMsg.content, 50)
+              : "(no content)";
+            events.emitLog(`${symbols.incoming} Received: "${preview}"`);
+            onRequest(parsed);
             res.writeHead(200, { "Content-Type": "application/json" });
             res.end(JSON.stringify({ ok: true }));
           } catch {
diff --git a/src/services/ai-transport-demo/ui/App.tsx b/src/services/ai-transport-demo/ui/App.tsx
index 5818a3683..33b00793c 100644
--- a/src/services/ai-transport-demo/ui/App.tsx
+++ b/src/services/ai-transport-demo/ui/App.tsx
@@ -8,28 +8,23 @@
 
 import React, { useState, useEffect } from "react";
 import { Box, Text, useApp, useInput, useStdout } from "ink";
-import { ClientPanel, type ConversationMessage } from "./ClientPanel.js";
+import { ClientPanel } from "./ClientPanel.js";
 import { ServerPanel } from "./ServerPanel.js";
 import { DebugPanel } from "./DebugPanel.js";
 import { InputBar } from "./InputBar.js";
 import { useScrollableLog } from "./hooks/use-scrollable-log.js";
+import { useDemo } from "./hooks/use-demo.js";
 import { colors } from "./theme.js";
+import type { DemoOrchestrator } from "../lib/orchestrator.js";
 
 export interface AppProps {
   role: "both" | "client" | "server";
   feature: string;
   channelName: string;
-  onSendMessage?: (text: string) => void;
-  onCancel?: () => void;
+  orchestrator: DemoOrchestrator | null;
 }
 
-export function App({
-  role,
-  feature,
-  channelName,
-  onSendMessage,
-  onCancel,
-}: AppProps) {
+export function App({ role, feature, channelName, orchestrator }: AppProps) {
   const { exit } = useApp();
   const { stdout } = useStdout();
   const [dims, setDims] = useState({
@@ -38,12 +33,69 @@ export function App({
   });
 
   const [debugExpanded, setDebugExpanded] = useState(false);
-  const [isStreaming] = useState(false);
-  const [messages] = useState<ConversationMessage[]>([]);
+  const [mutableMessagesError, setMutableMessagesError] = useState(false);
+
+  const {
+    messages,
+    isStreaming,
+    serverPort,
+    serverRunning,
+    clientConnected,
+    sendMessage,
+    cancelStream,
+  } = useDemo(orchestrator);
 
   const serverLog = useScrollableLog();
   const debugLog = useScrollableLog();
 
+  // Wire orchestrator events to log panels, then start server/client.
+  // Starting happens inside useEffect so event listeners are attached first
+  // and no events are missed.
+  const [started, setStarted] = useState(false);
+
+  useEffect(() => {
+    if (!orchestrator) return;
+
+    const onServerLog = (msg: string) => serverLog.addEntry(msg);
+    const onDebugLog = (msg: string) => debugLog.addEntry(msg);
+
+    const onMutableRequired = () => setMutableMessagesError(true);
+
+    orchestrator.on("serverLog", onServerLog);
+    orchestrator.on("debugLog", onDebugLog);
+    orchestrator.on("mutableMessagesRequired", onMutableRequired);
+
+    return () => {
+      orchestrator.off("serverLog", onServerLog);
+      orchestrator.off("debugLog", onDebugLog);
+      orchestrator.off("mutableMessagesRequired", onMutableRequired);
+    };
+  }, [orchestrator, serverLog.addEntry, debugLog.addEntry]);
+
+  // Start server and client after listeners are attached
+  useEffect(() => {
+    if (!orchestrator || started) return;
+    setStarted(true);
+
+    const startup = async () => {
+      const runServer = role === "both" || role === "server";
+      const runClient = role === "both" || role === "client";
+
+      if (runServer) {
+        await orchestrator.startServer();
+      }
+
+      if (runClient) {
+        await orchestrator.startClient();
+      }
+    };
+
+    startup().catch((error: unknown) => {
+      debugLog.addEntry(`Startup error: ${String(error)}`);
+    });
+  }, [orchestrator, role, started, debugLog]);
+
+  // Track terminal resize
   useEffect(() => {
     const onResize = () => {
       setDims({
@@ -58,6 +110,7 @@ export function App({
     };
   }, [stdout]);
 
+  // Keyboard handling
   useInput((input, key) => {
     if (input === "d" && key.ctrl) {
       exit();
@@ -65,7 +118,7 @@ export function App({
     }
 
     if (input === "c" && key.ctrl && isStreaming) {
-      onCancel?.();
+      cancelStream();
       return;
     }
 
@@ -74,25 +127,58 @@ export function App({
     }
   });
 
-  const handleSendMessage = (text: string) => {
-    onSendMessage?.(text);
-  };
-
   const showClient = role === "both" || role === "client";
   const showServer = role === "both" || role === "server";
 
   const clientWidth = showServer ? Math.floor(dims.width * 0.6) : dims.width;
-
-  // Debug: 2 lines always visible, 8 when expanded
   const debugLines = debugExpanded ? 8 : 2;
 
+  // Server status for client panel
+  const serverStatus = clientConnected
+    ? "connected"
+    : orchestrator
+      ? "connecting"
+      : "not-found";
+
+  // Show mutable messages setup instructions if the error is triggered
+  if (mutableMessagesError) {
+    return (
+      <Box flexDirection="column" paddingX={1}>
+        <Text bold color={colors.error}>
+          Setup Required: Mutable Messages
+        </Text>
+        <Text>
+          AI Transport requires <Text bold>mutable messages</Text> on the{" "}
+          <Text color={colors.primary}>ai-demo</Text> namespace.
+        </Text>
+        <Text> </Text>
+        <Text>To set this up, either:</Text>
+        <Text>
+          {"  "}1.{" "}
+          <Text color={colors.primary}>
+            ably apps rules create --name ai-demo --mutable-messages
+          </Text>
+        </Text>
+        <Text>
+          {"  "}2. Dashboard: App {">"} Settings {">"} Rules {">"} add ai-demo
+          with Mutable messages
+        </Text>
+        <Text> </Text>
+        <Text color={colors.dim}>
+          Docs: https://ably.com/docs/channels/options/mutable-messages | Press
+          Ctrl+D to exit
+        </Text>
+      </Box>
+    );
+  }
+
   return (
     <Box flexDirection="row" height={dims.height} width={dims.width}>
       {/* ── Client panel ── */}
       {showClient && (
         <Box
           flexDirection="column"
-          borderStyle="round"
+          borderStyle="single"
           borderColor={colors.activeBorder}
           width={clientWidth}
         >
@@ -111,12 +197,12 @@ export function App({
           <Box flexDirection="column" flexGrow={1} paddingX={1} marginTop={1}>
             <ClientPanel
               messages={messages}
-              serverStatus="connected"
+              serverStatus={serverStatus}
               isStreaming={isStreaming}
             />
           </Box>
 
-          {/* Debug events — always visible, 2 lines default */}
+          {/* Debug events — always visible */}
           <Box
             flexDirection="column"
             paddingX={1}
@@ -144,7 +230,11 @@ export function App({
             borderRight={false}
             borderColor={colors.border}
           >
-            <InputBar onSubmit={handleSendMessage} isStreaming={isStreaming} />
+            <InputBar
+              onSubmit={sendMessage}
+              isStreaming={isStreaming}
+              disabled={!clientConnected}
+            />
           </Box>
         </Box>
       )}
@@ -154,22 +244,17 @@ export function App({
         <Box
           flexDirection="column"
           flexGrow={1}
-          borderStyle="round"
+          borderStyle="single"
           borderColor={colors.border}
         >
-          {/* Server log — fills the panel */}
           <Box flexDirection="column" flexGrow={1} paddingX={1}>
             <ServerPanel
               entries={serverLog.entries}
-              isRunning={false}
+              port={serverPort ?? undefined}
+              isRunning={serverRunning}
               maxVisible={dims.height - 4}
             />
           </Box>
-
-          {/* Future: server controls bar would go here */}
-          {/* <Box paddingX={1} borderStyle="single" borderTop ...>
-               Restart │ Disconnect │ Kill stream
-             </Box> */}
         </Box>
       )}
     </Box>
diff --git a/src/services/ai-transport-demo/ui/hooks/use-demo.ts b/src/services/ai-transport-demo/ui/hooks/use-demo.ts
new file mode 100644
index 000000000..7e72b4ce3
--- /dev/null
+++ b/src/services/ai-transport-demo/ui/hooks/use-demo.ts
@@ -0,0 +1,96 @@
+/**
+ * React hook that connects the DemoOrchestrator to UI state.
+ * Manages conversation messages, streaming status, and server/client state.
+ */
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import type { ConversationMessage } from "../ClientPanel.js";
+import type { DemoOrchestrator } from "../../lib/orchestrator.js";
+import type { DemoMessage } from "../../lib/codec.js";
+
+interface UseDemoResult {
+  messages: ConversationMessage[];
+  isStreaming: boolean;
+  serverPort: number | null;
+  serverRunning: boolean;
+  clientConnected: boolean;
+  sendMessage: (text: string) => void;
+  cancelStream: () => void;
+}
+
+export function useDemo(orchestrator: DemoOrchestrator | null): UseDemoResult {
+  const [messages, setMessages] = useState<ConversationMessage[]>([]);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [serverPort, setServerPort] = useState<number | null>(null);
+  const [serverRunning, setServerRunning] = useState(false);
+  const [clientConnected, setClientConnected] = useState(false);
+
+  const orchestratorRef = useRef(orchestrator);
+  orchestratorRef.current = orchestrator;
+
+  useEffect(() => {
+    if (!orchestrator) return;
+
+    const onServerReady = (data: { port: number }) => {
+      setServerPort(data.port);
+      setServerRunning(true);
+    };
+
+    const onClientConnected = () => {
+      setClientConnected(true);
+    };
+
+    // The orchestrator emits the full message list from the AIT client transport
+    const onMessages = (msgs: DemoMessage[]) => {
+      setMessages(
+        msgs.map((m) => ({
+          id: m.id,
+          role: m.role,
+          content: m.content,
+        })),
+      );
+    };
+
+    const onTurnEnd = () => {
+      setIsStreaming(false);
+    };
+
+    const onError = () => {
+      setIsStreaming(false);
+    };
+
+    orchestrator.on("serverReady", onServerReady);
+    orchestrator.on("clientConnected", onClientConnected);
+    orchestrator.on("messages", onMessages);
+    orchestrator.on("turnEnd", onTurnEnd);
+    orchestrator.on("error", onError);
+
+    return () => {
+      orchestrator.off("serverReady", onServerReady);
+      orchestrator.off("clientConnected", onClientConnected);
+      orchestrator.off("messages", onMessages);
+      orchestrator.off("turnEnd", onTurnEnd);
+      orchestrator.off("error", onError);
+    };
+  }, [orchestrator]);
+
+  const sendMessage = useCallback((text: string) => {
+    if (!orchestratorRef.current) return;
+    setIsStreaming(true);
+    orchestratorRef.current.sendMessage(text);
+  }, []);
+
+  const cancelStream = useCallback(() => {
+    orchestratorRef.current?.cancelActiveTurn();
+  }, []);
+
+  return {
+    messages,
+    isStreaming,
+    serverPort,
+    serverRunning,
+    clientConnected,
+    sendMessage,
+    cancelStream,
+  };
+}

From cd02e4ec02ddc20a311df8f9b4b689927b0b6871 Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Wed, 15 Apr 2026 23:09:38 +0200
Subject: [PATCH 07/17] feat: add --value-only flag to auth keys current

Outputs just the raw API key value with no formatting, making it
easy to use in shell scripts and environment variables:

  ABLY_API_KEY=$(ably auth keys current --value-only) node my-app.js

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/commands/auth/keys/current.ts            | 12 +++++++++++-
 test/unit/commands/auth/keys/current.test.ts | 14 ++++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/src/commands/auth/keys/current.ts b/src/commands/auth/keys/current.ts
index 1999ca59a..8d5471fc4 100644
--- a/src/commands/auth/keys/current.ts
+++ b/src/commands/auth/keys/current.ts
@@ -11,7 +11,7 @@ export default class KeysCurrentCommand extends ControlBaseCommand {
     "$ ably auth keys current",
     "$ ably auth keys current --app APP_ID",
     "$ ably auth keys current --json",
-    "$ ably auth keys current --pretty-json",
+    "$ ABLY_API_KEY=$(ably auth keys current --value-only) node my-script.js",
   ];
 
   static flags = {
@@ -20,6 +20,10 @@ export default class KeysCurrentCommand extends ControlBaseCommand {
       description: "The app ID (defaults to current app)",
       env: "ABLY_APP_ID",
     }),
+    "value-only": Flags.boolean({
+      description:
+        "Output only the raw API key value, useful for scripting and environment variables",
+    }),
   };
 
   async run(): Promise<void> {
@@ -52,6 +56,12 @@ export default class KeysCurrentCommand extends ControlBaseCommand {
       );
     }
 
+    // --value-only: output just the raw API key string, nothing else
+    if (flags["value-only"]) {
+      this.log(apiKey);
+      return;
+    }
+
     // Extract the key ID (part before the colon)
     const keyId = this.configManager.getKeyId(appId) || apiKey.split(":")[0];
     const keyLabel = this.configManager.getKeyName(appId) || "Unnamed key";
diff --git a/test/unit/commands/auth/keys/current.test.ts b/test/unit/commands/auth/keys/current.test.ts
index ff81eb0dd..be60f4838 100644
--- a/test/unit/commands/auth/keys/current.test.ts
+++ b/test/unit/commands/auth/keys/current.test.ts
@@ -47,6 +47,20 @@ describe("auth:keys:current command", () => {
       expect(result).toHaveProperty("key");
       expect(result.key).toHaveProperty("value");
     });
+
+    it("should output only the raw key value with --value-only", async () => {
+      const mockConfig = getMockConfigManager();
+      const apiKey = mockConfig.getApiKey()!;
+      const { stdout } = await runCommand(
+        ["auth:keys:current", "--value-only"],
+        import.meta.url,
+      );
+
+      // Should be just the key, nothing else
+      expect(stdout.trim()).toBe(apiKey);
+      expect(stdout).not.toContain("Account");
+      expect(stdout).not.toContain("App");
+    });
   });
 
   standardHelpTests("auth:keys:current", import.meta.url);

From e680b0b6000d464c130bcab291553248be3cf424 Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Wed, 15 Apr 2026 23:38:39 +0200
Subject: [PATCH 08/17] fix: suppress AIT SDK NACK spam on mutable messages
 error

When mutableMessages is not enabled, the AIT encoder floods stderr
with [AblySDK Error] NACK logs and PromiseRejectionHandledWarnings.
These are a known SDK issue (reported separately) but we need the
demo to handle it gracefully.

Intercept console.error/console.log and process warnings to suppress
the NACK flood once the mutable messages error is detected. The TUI
error panel shows the clean setup instructions instead.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/commands/ai-transport/demo/streaming.ts | 67 +++++++++++++++++++--
 1 file changed, 62 insertions(+), 5 deletions(-)

diff --git a/src/commands/ai-transport/demo/streaming.ts b/src/commands/ai-transport/demo/streaming.ts
index 597b798cc..5601376bf 100644
--- a/src/commands/ai-transport/demo/streaming.ts
+++ b/src/commands/ai-transport/demo/streaming.ts
@@ -100,22 +100,75 @@ export default class StreamingDemo extends ControlBaseCommand {
       },
     });
 
-    // Catch unhandled errors from the Ably SDK (e.g., mutable messages 93002)
-    // that are thrown from WebSocket message handlers outside our try/catch.
-    // We emit the event on the orchestrator so the TUI shows the setup screen.
+    // The AIT SDK encoder has a known issue where it floods stderr with
+    // NACK errors and PromiseRejectionHandledWarnings when mutableMessages
+    // is not enabled. We suppress these so the TUI error panel can present
+    // a clean message. All suppression is removed in the finally block.
     const orchestratorRef = this.orchestrator;
+    let mutableErrorDetected = false;
+
+    // 1. Catch uncaught exceptions from the SDK's WebSocket handler
     const unhandledHandler = (error: Error) => {
       const msg = String(error);
       if (msg.includes("93002") || msg.includes("mutableMessages")) {
-        orchestratorRef?.emit("mutableMessagesRequired");
+        if (!mutableErrorDetected) {
+          mutableErrorDetected = true;
+          orchestratorRef?.emit("mutableMessagesRequired");
+        }
+
+        return;
+      }
+
+      if (msg.includes("80017") || msg.includes("Connection closed")) {
+        // Expected after we close the connection on mutable messages error
         return;
       }
 
-      // For other errors, log to stderr but don't crash the TUI
       process.stderr.write(`Unhandled error: ${msg}\n`);
     };
 
+    // 2. Intercept console.error to suppress [AblySDK Error] NACK spam
+    const originalConsoleError = console.error;
+    const originalConsoleLog = console.log;
+    const suppressedConsole = (...args: unknown[]) => {
+      const msg = args.map(String).join(" ");
+      if (
+        mutableErrorDetected &&
+        (msg.includes("93002") ||
+          msg.includes("mutableMessages") ||
+          msg.includes("onNack") ||
+          msg.includes("80017") ||
+          msg.includes("failQueuedMessages"))
+      ) {
+        return; // Suppress
+      }
+
+      originalConsoleError(...args);
+    };
+
+    console.error = suppressedConsole;
+    console.log = (...args: unknown[]) => {
+      const msg = args.map(String).join(" ");
+      if (mutableErrorDetected && msg.includes("Ably:")) {
+        return; // Suppress SDK log output after error detected
+      }
+
+      originalConsoleLog(...args);
+    };
+
+    // 3. Suppress PromiseRejectionHandledWarning from the encoder's
+    //    fire-and-forget pattern
+    const warningHandler = (warning: Error) => {
+      if (warning.name === "PromiseRejectionHandledWarning") {
+        return; // Suppress
+      }
+
+      process.emit("warning", warning);
+    };
+
     process.on("uncaughtException", unhandledHandler);
+    process.removeAllListeners("warning");
+    process.on("warning", warningHandler);
 
     // Bypass Ink's CI detection (CI_* env vars trigger is-in-ci)
     const prevCi = process.env.CI;
@@ -138,7 +191,11 @@ export default class StreamingDemo extends ControlBaseCommand {
 
       await waitUntilExit();
     } finally {
+      // Restore all suppression
       process.off("uncaughtException", unhandledHandler);
+      process.removeAllListeners("warning");
+      console.error = originalConsoleError;
+      console.log = originalConsoleLog;
 
       if (prevCi === undefined) {
         delete process.env.CI;

From 6fe49b12bb5c0a29ba1fc10db66c1500db1a055d Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Thu, 16 Apr 2026 01:10:31 +0200
Subject: [PATCH 09/17] fix: update server test for AIT request body format

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../ai-transport/demo/lib/server.test.ts      | 63 +++++++++++--------
 1 file changed, 36 insertions(+), 27 deletions(-)

diff --git a/test/unit/commands/ai-transport/demo/lib/server.test.ts b/test/unit/commands/ai-transport/demo/lib/server.test.ts
index 63e074771..f66e3c418 100644
--- a/test/unit/commands/ai-transport/demo/lib/server.test.ts
+++ b/test/unit/commands/ai-transport/demo/lib/server.test.ts
@@ -26,9 +26,9 @@ describe("server", () => {
   describe("createDemoServer", () => {
     it("should start a server on an available port", async () => {
       const channel = createMockChannel();
-      const onMessage = vi.fn();
+      const onRequest = vi.fn();
 
-      server = await createDemoServer({ channel, onMessage });
+      server = await createDemoServer({ channel, onRequest });
 
       expect(server.port).toBeGreaterThan(0);
       expect(server.url).toBe(`http://localhost:${server.port}`);
@@ -36,56 +36,65 @@ describe("server", () => {
 
     it("should enter presence with the endpoint URL", async () => {
       const channel = createMockChannel();
-      const onMessage = vi.fn();
+      const onRequest = vi.fn();
 
-      server = await createDemoServer({ channel, onMessage });
+      server = await createDemoServer({ channel, onRequest });
 
       expect(channel.presence.enter).toHaveBeenCalledWith({
         endpoint: server.url,
       });
     });
 
-    it("should handle POST requests with JSON body", async () => {
+    it("should handle POST requests with AIT SDK format", async () => {
       const channel = createMockChannel();
-      const onMessage = vi.fn();
+      const onRequest = vi.fn();
 
-      server = await createDemoServer({ channel, onMessage });
+      server = await createDemoServer({ channel, onRequest });
+
+      const aitBody = {
+        turnId: "turn-1",
+        clientId: "user-1",
+        messages: [{ message: { id: "m1", role: "user", content: "Hello" } }],
+      };
 
       const response = await fetch(server.url, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ message: "Hello" }),
+        body: JSON.stringify(aitBody),
       });
 
       expect(response.status).toBe(200);
       const data = await response.json();
       expect(data).toEqual({ ok: true });
-      expect(onMessage).toHaveBeenCalledWith({ message: "Hello" });
+      expect(onRequest).toHaveBeenCalledWith(aitBody);
     });
 
     it("should handle POST to /api/chat endpoint", async () => {
       const channel = createMockChannel();
-      const onMessage = vi.fn();
+      const onRequest = vi.fn();
+
+      server = await createDemoServer({ channel, onRequest });
 
-      server = await createDemoServer({ channel, onMessage });
+      const aitBody = {
+        turnId: "turn-2",
+        messages: [{ message: { id: "m2", role: "user", content: "Hi" } }],
+      };
 
       const response = await fetch(`${server.url}/api/chat`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ message: "Hello from /api/chat" }),
+        body: JSON.stringify(aitBody),
       });
 
       expect(response.status).toBe(200);
-      expect(onMessage).toHaveBeenCalledWith({
-        message: "Hello from /api/chat",
-      });
+      expect(onRequest).toHaveBeenCalledWith(aitBody);
     });
 
     it("should return 400 for invalid JSON", async () => {
       const channel = createMockChannel();
-      const onMessage = vi.fn();
+      const onRequest = vi.fn();
 
-      server = await createDemoServer({ channel, onMessage });
+      server = await createDemoServer({ channel, onRequest });
 
       const response = await fetch(server.url, {
         method: "POST",
@@ -94,14 +103,14 @@ describe("server", () => {
       });
 
       expect(response.status).toBe(400);
-      expect(onMessage).not.toHaveBeenCalled();
+      expect(onRequest).not.toHaveBeenCalled();
     });
 
     it("should return 404 for unknown routes", async () => {
       const channel = createMockChannel();
-      const onMessage = vi.fn();
+      const onRequest = vi.fn();
 
-      server = await createDemoServer({ channel, onMessage });
+      server = await createDemoServer({ channel, onRequest });
 
       const response = await fetch(`${server.url}/unknown`);
 
@@ -110,10 +119,10 @@ describe("server", () => {
 
     it("should emit log events", async () => {
       const channel = createMockChannel();
-      const onMessage = vi.fn();
+      const onRequest = vi.fn();
       const logs: string[] = [];
 
-      server = await createDemoServer({ channel, onMessage });
+      server = await createDemoServer({ channel, onRequest });
       server.events.on("log", (msg: string) => logs.push(msg));
 
       await fetch(server.url, {
@@ -122,14 +131,14 @@ describe("server", () => {
         body: JSON.stringify({ message: "Test" }),
       });
 
-      expect(logs.some((l) => l.includes("Received message"))).toBe(true);
+      expect(logs.some((l) => l.includes("Received"))).toBe(true);
     });
 
     it("should leave presence and stop on close", async () => {
       const channel = createMockChannel();
-      const onMessage = vi.fn();
+      const onRequest = vi.fn();
 
-      server = await createDemoServer({ channel, onMessage });
+      server = await createDemoServer({ channel, onRequest });
       await server.close();
 
       expect(channel.presence.leave).toHaveBeenCalled();
@@ -147,9 +156,9 @@ describe("server", () => {
     it("should continue if presence enter fails", async () => {
       const channel = createMockChannel();
       channel.presence.enter.mockRejectedValue(new Error("presence error"));
-      const onMessage = vi.fn();
+      const onRequest = vi.fn();
 
-      server = await createDemoServer({ channel, onMessage });
+      server = await createDemoServer({ channel, onRequest });
 
       // Server should still be running despite presence failure
       expect(server.port).toBeGreaterThan(0);

From dadaec772db29fb0d976ed5ad71d294dc203cf15 Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Thu, 16 Apr 2026 22:46:47 +0200
Subject: [PATCH 10/17] feat: add role modes, clean mutable messages error
 handling

- Role modes: --role client/server show appropriate single-panel views
- Server-only mode shows channel name + connect command for other terminal
- serverNotFound event when presence discovery times out
- serverStatus tracked properly in useDemo hook
- Mutable messages error: auto-exits after rendering error panel using
  useEffect (no setTimeout), message stays on screen
- Fix error leak after exit: keep stdout/stderr interceptors active
  through entire cleanup lifecycle, only restore in class finally()
  after Ably client is fully closed

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/commands/ai-transport/demo/streaming.ts   | 114 ++++++++++--------
 .../ai-transport-demo/lib/orchestrator.ts     |   4 +-
 src/services/ai-transport-demo/ui/App.tsx     |  91 ++++++++------
 .../ai-transport-demo/ui/hooks/use-demo.ts    |  12 ++
 4 files changed, 132 insertions(+), 89 deletions(-)

diff --git a/src/commands/ai-transport/demo/streaming.ts b/src/commands/ai-transport/demo/streaming.ts
index 5601376bf..1db82187d 100644
--- a/src/commands/ai-transport/demo/streaming.ts
+++ b/src/commands/ai-transport/demo/streaming.ts
@@ -40,6 +40,9 @@ export default class StreamingDemo extends ControlBaseCommand {
 
   private orchestrator: DemoOrchestrator | null = null;
   private ablyClient: import("ably").Realtime | null = null;
+  private origStdoutWrite: typeof process.stdout.write | null = null;
+  private origStderrWrite: typeof process.stderr.write | null = null;
+  private unhandledHandler: ((error: Error) => void) | null = null;
 
   async run(): Promise<void> {
     const { flags } = await this.parse(StreamingDemo);
@@ -100,10 +103,11 @@ export default class StreamingDemo extends ControlBaseCommand {
       },
     });
 
-    // The AIT SDK encoder has a known issue where it floods stderr with
-    // NACK errors and PromiseRejectionHandledWarnings when mutableMessages
-    // is not enabled. We suppress these so the TUI error panel can present
-    // a clean message. All suppression is removed in the finally block.
+    // The AIT SDK encoder floods stderr/stdout with NACK errors and
+    // PromiseRejectionHandledWarnings when mutableMessages is not enabled.
+    // The SDK's logger captures console.log/warn at module load time in
+    // closures, so overriding console.* doesn't work. We must intercept
+    // at the process.stdout/stderr.write level.
     const orchestratorRef = this.orchestrator;
     let mutableErrorDetected = false;
 
@@ -120,55 +124,43 @@ export default class StreamingDemo extends ControlBaseCommand {
       }
 
       if (msg.includes("80017") || msg.includes("Connection closed")) {
-        // Expected after we close the connection on mutable messages error
         return;
       }
 
-      process.stderr.write(`Unhandled error: ${msg}\n`);
+      this.origStderrWrite?.call(process.stderr, `Unhandled error: ${msg}\n`);
     };
 
-    // 2. Intercept console.error to suppress [AblySDK Error] NACK spam
-    const originalConsoleError = console.error;
-    const originalConsoleLog = console.log;
-    const suppressedConsole = (...args: unknown[]) => {
-      const msg = args.map(String).join(" ");
-      if (
-        mutableErrorDetected &&
-        (msg.includes("93002") ||
-          msg.includes("mutableMessages") ||
-          msg.includes("onNack") ||
-          msg.includes("80017") ||
-          msg.includes("failQueuedMessages"))
-      ) {
-        return; // Suppress
-      }
-
-      originalConsoleError(...args);
-    };
-
-    console.error = suppressedConsole;
-    console.log = (...args: unknown[]) => {
-      const msg = args.map(String).join(" ");
-      if (mutableErrorDetected && msg.includes("Ably:")) {
-        return; // Suppress SDK log output after error detected
-      }
-
-      originalConsoleLog(...args);
-    };
-
-    // 3. Suppress PromiseRejectionHandledWarning from the encoder's
-    //    fire-and-forget pattern
-    const warningHandler = (warning: Error) => {
-      if (warning.name === "PromiseRejectionHandledWarning") {
-        return; // Suppress
-      }
-
-      process.emit("warning", warning);
-    };
+    // 2. Intercept process.stdout.write and process.stderr.write to
+    //    suppress [AblySDK Error] NACK spam and PromiseRejectionHandledWarning.
+    //    This is the only reliable way since the SDK captures console.*
+    //    references at module load time.
+    const origStdoutWrite = process.stdout.write;
+    const origStderrWrite = process.stderr.write;
+    this.origStdoutWrite = origStdoutWrite;
+    this.origStderrWrite = origStderrWrite;
+    this.unhandledHandler = unhandledHandler;
+
+    const isSuppressable = (str: string): boolean =>
+      mutableErrorDetected &&
+      (str.includes("93002") ||
+        str.includes("mutableMessages") ||
+        str.includes("onNack") ||
+        str.includes("80017") ||
+        str.includes("failQueuedMessages") ||
+        str.includes("PromiseRejectionHandledWarning") ||
+        str.includes("AblySDK Error"));
+
+    process.stdout.write = ((chunk: unknown, ...args: unknown[]) => {
+      if (typeof chunk === "string" && isSuppressable(chunk)) return true;
+      return origStdoutWrite.apply(process.stdout, [chunk, ...args] as never);
+    }) as typeof process.stdout.write;
+
+    process.stderr.write = ((chunk: unknown, ...args: unknown[]) => {
+      if (typeof chunk === "string" && isSuppressable(chunk)) return true;
+      return origStderrWrite.apply(process.stderr, [chunk, ...args] as never);
+    }) as typeof process.stderr.write;
 
     process.on("uncaughtException", unhandledHandler);
-    process.removeAllListeners("warning");
-    process.on("warning", warningHandler);
 
     // Bypass Ink's CI detection (CI_* env vars trigger is-in-ci)
     const prevCi = process.env.CI;
@@ -191,12 +183,8 @@ export default class StreamingDemo extends ControlBaseCommand {
 
       await waitUntilExit();
     } finally {
-      // Restore all suppression
-      process.off("uncaughtException", unhandledHandler);
-      process.removeAllListeners("warning");
-      console.error = originalConsoleError;
-      console.log = originalConsoleLog;
-
+      // Only restore CI env here — stdout/stderr interceptors are restored
+      // in the class finally() after Ably client is fully closed
       if (prevCi === undefined) {
         delete process.env.CI;
       } else {
@@ -206,6 +194,8 @@ export default class StreamingDemo extends ControlBaseCommand {
   }
 
   async finally(error: Error | undefined): Promise<void> {
+    // Close orchestrator and Ably client while interceptors are still active
+    // so any SDK cleanup output is suppressed
     if (this.orchestrator) {
       await this.orchestrator.close();
       this.orchestrator = null;
@@ -216,6 +206,26 @@ export default class StreamingDemo extends ControlBaseCommand {
       this.ablyClient = null;
     }
 
+    // Small delay to let any final SDK async cleanup complete while
+    // interceptors are still active
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // Now restore stdout/stderr and uncaughtException handler
+    if (this.origStdoutWrite) {
+      process.stdout.write = this.origStdoutWrite;
+      this.origStdoutWrite = null;
+    }
+
+    if (this.origStderrWrite) {
+      process.stderr.write = this.origStderrWrite;
+      this.origStderrWrite = null;
+    }
+
+    if (this.unhandledHandler) {
+      process.off("uncaughtException", this.unhandledHandler);
+      this.unhandledHandler = null;
+    }
+
     await super.finally(error);
   }
 }
diff --git a/src/services/ai-transport-demo/lib/orchestrator.ts b/src/services/ai-transport-demo/lib/orchestrator.ts
index cd7919f7f..e5be1ec10 100644
--- a/src/services/ai-transport-demo/lib/orchestrator.ts
+++ b/src/services/ai-transport-demo/lib/orchestrator.ts
@@ -52,6 +52,7 @@ export interface DemoOrchestrator extends EventEmitter {
   on(event: "messages", listener: (msgs: DemoMessage[]) => void): this;
   on(event: "serverReady", listener: (data: { port: number }) => void): this;
   on(event: "clientConnected", listener: () => void): this;
+  on(event: "serverNotFound", listener: () => void): this;
   on(event: "turnEnd", listener: (data: { turnId: string; reason: string }) => void): this;
   on(event: "mutableMessagesRequired", listener: () => void): this;
   on(event: "error", listener: (error: Error) => void): this;
@@ -196,7 +197,8 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
       });
 
       if (!discovered) {
-        emitter.emit("debugLog", "No server found");
+        emitter.emit("debugLog", "No server found within timeout");
+        emitter.emit("serverNotFound");
         return;
       }
 
diff --git a/src/services/ai-transport-demo/ui/App.tsx b/src/services/ai-transport-demo/ui/App.tsx
index 33b00793c..ab68c5ff4 100644
--- a/src/services/ai-transport-demo/ui/App.tsx
+++ b/src/services/ai-transport-demo/ui/App.tsx
@@ -41,6 +41,7 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
     serverPort,
     serverRunning,
     clientConnected,
+    serverStatus,
     sendMessage,
     cancelStream,
   } = useDemo(orchestrator);
@@ -134,42 +135,8 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
   const debugLines = debugExpanded ? 8 : 2;
 
   // Server status for client panel
-  const serverStatus = clientConnected
-    ? "connected"
-    : orchestrator
-      ? "connecting"
-      : "not-found";
-
-  // Show mutable messages setup instructions if the error is triggered
   if (mutableMessagesError) {
-    return (
-      <Box flexDirection="column" paddingX={1}>
-        <Text bold color={colors.error}>
-          Setup Required: Mutable Messages
-        </Text>
-        <Text>
-          AI Transport requires <Text bold>mutable messages</Text> on the{" "}
-          <Text color={colors.primary}>ai-demo</Text> namespace.
-        </Text>
-        <Text> </Text>
-        <Text>To set this up, either:</Text>
-        <Text>
-          {"  "}1.{" "}
-          <Text color={colors.primary}>
-            ably apps rules create --name ai-demo --mutable-messages
-          </Text>
-        </Text>
-        <Text>
-          {"  "}2. Dashboard: App {">"} Settings {">"} Rules {">"} add ai-demo
-          with Mutable messages
-        </Text>
-        <Text> </Text>
-        <Text color={colors.dim}>
-          Docs: https://ably.com/docs/channels/options/mutable-messages | Press
-          Ctrl+D to exit
-        </Text>
-      </Box>
-    );
+    return <MutableMessagesError />;
   }
 
   return (
@@ -247,12 +214,23 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
           borderStyle="single"
           borderColor={colors.border}
         >
+          {/* Show channel info in server-only mode */}
+          {!showClient && (
+            <Box paddingX={1} flexDirection="column">
+              <Text bold>{formatFeatureName(feature)} Demo — Server</Text>
+              <Text color={colors.dim}>Channel: {channelName}</Text>
+              <Text color={colors.dim}>
+                Connect a client: ably ai-transport demo {feature} --role client
+                --channel {channelName}
+              </Text>
+            </Box>
+          )}
           <Box flexDirection="column" flexGrow={1} paddingX={1}>
             <ServerPanel
               entries={serverLog.entries}
               port={serverPort ?? undefined}
               isRunning={serverRunning}
-              maxVisible={dims.height - 4}
+              maxVisible={dims.height - (showClient ? 4 : 8)}
             />
           </Box>
         </Box>
@@ -261,6 +239,47 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
   );
 }
 
+/**
+ * Renders the mutable messages error and exits after the frame is painted.
+ * useEffect fires after React commits the render, so exit() is called
+ * once the message is visible on screen.
+ */
+function MutableMessagesError() {
+  const { exit } = useApp();
+
+  useEffect(() => {
+    exit();
+  }, [exit]);
+
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      <Text bold color={colors.error}>
+        Setup Required: Mutable Messages
+      </Text>
+      <Text>
+        AI Transport requires <Text bold>mutable messages</Text> on the{" "}
+        <Text color={colors.primary}>ai-demo</Text> namespace.
+      </Text>
+      <Text> </Text>
+      <Text>To set this up, either:</Text>
+      <Text>
+        {"  "}1.{" "}
+        <Text color={colors.primary}>
+          ably apps rules create --name ai-demo --mutable-messages
+        </Text>
+      </Text>
+      <Text>
+        {"  "}2. Dashboard: App {">"} Settings {">"} Rules {">"} add ai-demo
+        with Mutable messages
+      </Text>
+      <Text> </Text>
+      <Text color={colors.dim}>
+        Docs: https://ably.com/docs/channels/options/mutable-messages
+      </Text>
+    </Box>
+  );
+}
+
 function formatFeatureName(feature: string): string {
   return feature
     .split("-")
diff --git a/src/services/ai-transport-demo/ui/hooks/use-demo.ts b/src/services/ai-transport-demo/ui/hooks/use-demo.ts
index 7e72b4ce3..58b964f76 100644
--- a/src/services/ai-transport-demo/ui/hooks/use-demo.ts
+++ b/src/services/ai-transport-demo/ui/hooks/use-demo.ts
@@ -8,12 +8,15 @@ import type { ConversationMessage } from "../ClientPanel.js";
 import type { DemoOrchestrator } from "../../lib/orchestrator.js";
 import type { DemoMessage } from "../../lib/codec.js";
 
+type ServerStatus = "connecting" | "connected" | "not-found";
+
 interface UseDemoResult {
   messages: ConversationMessage[];
   isStreaming: boolean;
   serverPort: number | null;
   serverRunning: boolean;
   clientConnected: boolean;
+  serverStatus: ServerStatus;
   sendMessage: (text: string) => void;
   cancelStream: () => void;
 }
@@ -24,6 +27,7 @@ export function useDemo(orchestrator: DemoOrchestrator | null): UseDemoResult {
   const [serverPort, setServerPort] = useState<number | null>(null);
   const [serverRunning, setServerRunning] = useState(false);
   const [clientConnected, setClientConnected] = useState(false);
+  const [serverStatus, setServerStatus] = useState<ServerStatus>("connecting");
 
   const orchestratorRef = useRef(orchestrator);
   orchestratorRef.current = orchestrator;
@@ -38,6 +42,11 @@ export function useDemo(orchestrator: DemoOrchestrator | null): UseDemoResult {
 
     const onClientConnected = () => {
       setClientConnected(true);
+      setServerStatus("connected");
+    };
+
+    const onServerNotFound = () => {
+      setServerStatus("not-found");
     };
 
     // The orchestrator emits the full message list from the AIT client transport
@@ -61,6 +70,7 @@ export function useDemo(orchestrator: DemoOrchestrator | null): UseDemoResult {
 
     orchestrator.on("serverReady", onServerReady);
     orchestrator.on("clientConnected", onClientConnected);
+    orchestrator.on("serverNotFound", onServerNotFound);
     orchestrator.on("messages", onMessages);
     orchestrator.on("turnEnd", onTurnEnd);
     orchestrator.on("error", onError);
@@ -68,6 +78,7 @@ export function useDemo(orchestrator: DemoOrchestrator | null): UseDemoResult {
     return () => {
       orchestrator.off("serverReady", onServerReady);
       orchestrator.off("clientConnected", onClientConnected);
+      orchestrator.off("serverNotFound", onServerNotFound);
       orchestrator.off("messages", onMessages);
       orchestrator.off("turnEnd", onTurnEnd);
       orchestrator.off("error", onError);
@@ -90,6 +101,7 @@ export function useDemo(orchestrator: DemoOrchestrator | null): UseDemoResult {
     serverPort,
     serverRunning,
     clientConnected,
+    serverStatus,
     sendMessage,
     cancelStream,
   };

From f19da2620359cc723ad6c6997807a7b75f258056 Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Fri, 17 Apr 2026 00:17:17 +0200
Subject: [PATCH 11/17] fix: validate channel namespace and make error dialog
 dynamic
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Reject --channel without a namespace (no colon) — can't suggest a
  rule to create without knowing the namespace
- Make mutable messages error dialog dynamic — shows the actual
  namespace from the channel name, not hardcoded "ai-demo"
- Default auto-generated channels still use ai-demo: namespace

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/commands/ai-transport/demo/streaming.ts       | 14 ++++++++++++++
 src/services/ai-transport-demo/ui/App.tsx         | 11 ++++++-----
 .../commands/ai-transport/demo/streaming.test.ts  | 15 ++++++++++++---
 3 files changed, 32 insertions(+), 8 deletions(-)

diff --git a/src/commands/ai-transport/demo/streaming.ts b/src/commands/ai-transport/demo/streaming.ts
index 1db82187d..c8166f600 100644
--- a/src/commands/ai-transport/demo/streaming.ts
+++ b/src/commands/ai-transport/demo/streaming.ts
@@ -64,6 +64,20 @@ export default class StreamingDemo extends ControlBaseCommand {
     }
 
     const role = (flags.role ?? "both") as "both" | "client" | "server";
+
+    // Channel must include a namespace (colon separator) because AI Transport
+    // requires mutable messages, which is configured per-namespace via rules.
+    // Without a namespace, we can't guide the user to create the right rule.
+    if (flags.channel && !flags.channel.includes(":")) {
+      this.fail(
+        `Channel name must include a namespace (e.g. "my-namespace:${flags.channel}"). ` +
+          `AI Transport requires mutable messages, which is enabled per-namespace via rules. ` +
+          `If you don't have a namespace, omit --channel and the demo will use "ai-demo:" by default.`,
+        flags,
+        "aiTransportDemo",
+      );
+    }
+
     const channelName =
       flags.channel ??
       `ai-demo:streaming-${Math.random().toString(36).slice(2, 6)}`;
diff --git a/src/services/ai-transport-demo/ui/App.tsx b/src/services/ai-transport-demo/ui/App.tsx
index ab68c5ff4..4992d7045 100644
--- a/src/services/ai-transport-demo/ui/App.tsx
+++ b/src/services/ai-transport-demo/ui/App.tsx
@@ -136,7 +136,8 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
 
   // Server status for client panel
   if (mutableMessagesError) {
-    return <MutableMessagesError />;
+    const namespace = channelName.split(":")[0] || "ai-demo";
+    return <MutableMessagesError namespace={namespace} />;
   }
 
   return (
@@ -244,7 +245,7 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
  * useEffect fires after React commits the render, so exit() is called
  * once the message is visible on screen.
  */
-function MutableMessagesError() {
+function MutableMessagesError({ namespace }: { namespace: string }) {
   const { exit } = useApp();
 
   useEffect(() => {
@@ -258,18 +259,18 @@ function MutableMessagesError() {
       </Text>
       <Text>
         AI Transport requires <Text bold>mutable messages</Text> on the{" "}
-        <Text color={colors.primary}>ai-demo</Text> namespace.
+        <Text color={colors.primary}>{namespace}</Text> namespace.
       </Text>
       <Text> </Text>
       <Text>To set this up, either:</Text>
       <Text>
         {"  "}1.{" "}
         <Text color={colors.primary}>
-          ably apps rules create --name ai-demo --mutable-messages
+          ably apps rules create --name {namespace} --mutable-messages
         </Text>
       </Text>
       <Text>
-        {"  "}2. Dashboard: App {">"} Settings {">"} Rules {">"} add ai-demo
+        {"  "}2. Dashboard: App {">"} Settings {">"} Rules {">"} add {namespace}{" "}
         with Mutable messages
       </Text>
       <Text> </Text>
diff --git a/test/unit/commands/ai-transport/demo/streaming.test.ts b/test/unit/commands/ai-transport/demo/streaming.test.ts
index f5c48d754..5bfaa4dd7 100644
--- a/test/unit/commands/ai-transport/demo/streaming.test.ts
+++ b/test/unit/commands/ai-transport/demo/streaming.test.ts
@@ -37,13 +37,22 @@ describe("ai-transport:demo:streaming command", () => {
       expect(stdout).toContain("Role: client");
     });
 
-    it("should accept channel flag", async () => {
+    it("should accept channel flag with namespace", async () => {
       const { stdout } = await runCommand(
-        ["ai-transport:demo:streaming", "--channel", "test-channel"],
+        ["ai-transport:demo:streaming", "--channel", "my-ns:test-channel"],
         import.meta.url,
       );
 
-      expect(stdout).toContain("Channel: test-channel");
+      expect(stdout).toContain("Channel: my-ns:test-channel");
+    });
+
+    it("should reject channel without namespace", async () => {
+      const { error } = await runCommand(
+        ["ai-transport:demo:streaming", "--channel", "no-namespace"],
+        import.meta.url,
+      );
+
+      expect(error?.message).toContain("must include a namespace");
     });
   });
 

From ab9d84d6c4aea8a281bb79c5fdbb50d988461bf7 Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Tue, 21 Apr 2026 23:22:37 +0200
Subject: [PATCH 12/17] fix(ai-transport): forward codec encoder options to
 correlate stream events
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The demo's createEncoder was dropping options.extras.headers and options.onMessage
when wrapping createEncoderCore. The server transport passes transport-level
headers (x-ably-turn-id, x-ably-role, x-ably-msg-id) via options.extras.headers,
and without them the client's stream router could not correlate incoming events
to active turns — the ActiveTurn.stream never received any events and the UI
saw no streaming response.

Add regression tests that fail if the encoder stops forwarding headers or
the onMessage hook.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/services/ai-transport-demo/lib/codec.ts   | 24 +++++--
 .../ai-transport/demo/lib/codec.test.ts       | 71 ++++++++++++++++++-
 2 files changed, 90 insertions(+), 5 deletions(-)

diff --git a/src/services/ai-transport-demo/lib/codec.ts b/src/services/ai-transport-demo/lib/codec.ts
index da75233b3..89bcd83a7 100644
--- a/src/services/ai-transport-demo/lib/codec.ts
+++ b/src/services/ai-transport-demo/lib/codec.ts
@@ -44,9 +44,12 @@ function createDemoEncoder(
   channel: ChannelWriter,
   options?: EncoderOptions,
 ): StreamEncoder<FakeLLMEvent, DemoMessage> {
-  const core = createEncoderCore(channel, {
-    clientId: options?.clientId,
-  });
+  // CRITICAL: forward ALL options (including extras.headers and onMessage)
+  // to the encoder core. The server transport passes transport-level headers
+  // via options.extras.headers (turn ID, role, parent, msg-id). Without these,
+  // the client's stream router can't correlate incoming events to active
+  // turns (it looks up turnId via HEADER_TURN_ID from message headers).
+  const core = createEncoderCore(channel, options);
   let activeStreamId: string | null = null;
 
   return {
@@ -117,12 +120,20 @@ function createDemoEncoder(
 
 // ── Decoder ──────────────────────────────────────────────────────
 
+/** Optional debug hook — set by orchestrator for tracing decoder calls */
+let decoderDebug: ((msg: string) => void) | null = null;
+export function setDecoderDebug(fn: ((msg: string) => void) | null): void {
+  decoderDebug = fn;
+}
+
 function createDemoDecoder(): StreamDecoder<FakeLLMEvent, DemoMessage> {
   const hooks: DecoderCoreHooks<FakeLLMEvent, DemoMessage> = {
     buildStartEvents(
       tracker: StreamTrackerState,
     ): DecoderOutput<FakeLLMEvent, DemoMessage>[] {
-      // Emit a text-delta for the initial data from startStream
+      decoderDebug?.(
+        `buildStart name=${tracker.name} accumulated=${tracker.accumulated?.length ?? 0}`,
+      );
       if (tracker.accumulated) {
         return [
           {
@@ -140,6 +151,7 @@ function createDemoDecoder(): StreamDecoder<FakeLLMEvent, DemoMessage> {
       tracker: StreamTrackerState,
       delta: string,
     ): DecoderOutput<FakeLLMEvent, DemoMessage>[] {
+      decoderDebug?.(`buildDelta delta=${delta.length} chars`);
       return [
         {
           kind: "event",
@@ -152,6 +164,9 @@ function createDemoDecoder(): StreamDecoder<FakeLLMEvent, DemoMessage> {
     buildEndEvents(
       tracker: StreamTrackerState,
     ): DecoderOutput<FakeLLMEvent, DemoMessage>[] {
+      decoderDebug?.(
+        `buildEnd acc=${tracker.accumulated?.length ?? 0} chars`,
+      );
       return [
         {
           kind: "event",
@@ -170,6 +185,7 @@ function createDemoDecoder(): StreamDecoder<FakeLLMEvent, DemoMessage> {
     },
 
     decodeDiscrete(payload): DecoderOutput<FakeLLMEvent, DemoMessage>[] {
+      decoderDebug?.(`decodeDiscrete name=${payload.name}`);
       if (payload.name === USER_MESSAGE_NAME) {
         const data = JSON.parse(payload.data as string) as DemoMessage;
         return [{ kind: "message", message: data }];
diff --git a/test/unit/commands/ai-transport/demo/lib/codec.test.ts b/test/unit/commands/ai-transport/demo/lib/codec.test.ts
index b73404489..6d6458d6f 100644
--- a/test/unit/commands/ai-transport/demo/lib/codec.test.ts
+++ b/test/unit/commands/ai-transport/demo/lib/codec.test.ts
@@ -1,10 +1,24 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import {
   DemoCodec,
   type DemoMessage,
 } from "../../../../../../src/services/ai-transport-demo/lib/codec.js";
 import type { FakeLLMEvent } from "../../../../../../src/services/ai-transport-demo/lib/fake-llm.js";
 
+function createMockChannelWriter() {
+  return {
+    publish: vi
+      .fn()
+      .mockResolvedValue({ serial: "01700000000000-000@abc:001" }),
+    appendMessage: vi
+      .fn()
+      .mockResolvedValue({ serial: "01700000000000-000@abc:002" }),
+    updateMessage: vi
+      .fn()
+      .mockResolvedValue({ serial: "01700000000000-000@abc:003" }),
+  };
+}
+
 describe("DemoCodec", () => {
   describe("isTerminal", () => {
     it("should return true for finish events", () => {
@@ -119,4 +133,59 @@ describe("DemoCodec", () => {
       expect(acc.messages[0].content).toBe("Updated");
     });
   });
+
+  describe("createEncoder - options forwarding", () => {
+    // This test exists to catch a critical bug: if the encoder drops
+    // options.extras (transport headers) or options.onMessage, the server's
+    // published messages won't carry the turn-correlation headers
+    // (x-ably-turn-id, etc.). Without those headers, the client's stream
+    // router can't correlate events to active turns, and the ActiveTurn.stream
+    // never receives any events. The streaming demo breaks silently.
+    it("should forward options.extras.headers to published messages", async () => {
+      const channel = createMockChannelWriter();
+      const turnHeaders = {
+        "x-ably-turn-id": "turn-abc123",
+        "x-ably-role": "assistant",
+        "x-ably-msg-id": "msg-xyz",
+      };
+
+      const encoder = DemoCodec.createEncoder(channel as never, {
+        extras: { headers: turnHeaders },
+      });
+
+      // Publish a user message — headers must be on the published message
+      await encoder.writeMessages([
+        { id: "msg-1", role: "user", content: "Hello" },
+      ]);
+
+      expect(channel.publish).toHaveBeenCalled();
+      const publishCall = channel.publish.mock.calls[0];
+      const publishedMsg = publishCall[0];
+      const headersOnMsg = Array.isArray(publishedMsg)
+        ? publishedMsg[0]?.extras?.headers
+        : publishedMsg?.extras?.headers;
+
+      // Verify all turn headers are on the published message
+      for (const [key, value] of Object.entries(turnHeaders)) {
+        expect(headersOnMsg).toMatchObject({ [key]: value });
+      }
+    });
+
+    it("should forward options.onMessage hook for pre-publish mutation", async () => {
+      const channel = createMockChannelWriter();
+      const onMessage = vi.fn();
+
+      const encoder = DemoCodec.createEncoder(channel as never, {
+        extras: { headers: { "x-ably-turn-id": "turn-1" } },
+        onMessage,
+      });
+
+      await encoder.writeMessages([
+        { id: "msg-1", role: "user", content: "Hi" },
+      ]);
+
+      // onMessage should be called before each publish with the Ably message
+      expect(onMessage).toHaveBeenCalled();
+    });
+  });
 });

From 39300e7c2355e177667c656b09e743dfd04fd82d Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Tue, 21 Apr 2026 23:22:48 +0200
Subject: [PATCH 13/17] feat(ai-transport): probe presence entries for liveness
 during discovery

Ably does not immediately remove presence entries when a demo server crashes
uncleanly, so stale http endpoints linger on the channel. Previously the
client picked the first entry (or the newest by timestamp) and happily POSTed
to a dead server.

Sort candidates by timestamp newest-first and HTTP-probe each with an OPTIONS
request (750ms timeout) before accepting. If none respond, subscribe to
presence and probe each new 'enter'/'present' event so late-arriving live
servers supersede stale ones.

Add tests covering: probe rejection of stale entries, fallback to live entry,
and the client-first scenario where only stale entries exist until a real
server starts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../ai-transport-demo/lib/client-discovery.ts | 88 +++++++++++++----
 .../demo/lib/client-discovery.test.ts         | 98 ++++++++++++++++++-
 2 files changed, 166 insertions(+), 20 deletions(-)

diff --git a/src/services/ai-transport-demo/lib/client-discovery.ts b/src/services/ai-transport-demo/lib/client-discovery.ts
index 65f277d3c..e6289f242 100644
--- a/src/services/ai-transport-demo/lib/client-discovery.ts
+++ b/src/services/ai-transport-demo/lib/client-discovery.ts
@@ -32,46 +32,76 @@ export async function discoverServer(
 ): Promise<DiscoveredServer | null> {
   onLog?.("Searching for server via presence...");
 
-  // First, check if the server is already present
+  // Check current presence members. Ably does not immediately remove
+  // presence entries when a server crashes (unclean shutdown), so there
+  // can be stale entries lingering on the channel. We probe each
+  // candidate for liveness (HTTP OPTIONS) before accepting it, preferring
+  // the most recent entry first.
   try {
     const members = await channel.presence.get();
-    for (const member of members) {
-      const server = extractServerFromPresence(member);
-      if (server) {
-        onLog?.(`Found server at ${server.endpoint}`);
-        return server;
+    const candidates = members
+      .map((m) => ({
+        server: extractServerFromPresence(m),
+        timestamp: m.timestamp ?? 0,
+      }))
+      .filter(
+        (x): x is { server: DiscoveredServer; timestamp: number } =>
+          x.server !== null,
+      )
+      .sort((a, b) => b.timestamp - a.timestamp);
+
+    if (candidates.length > 0) {
+      onLog?.(
+        `Probing ${candidates.length} presence entry(s) for liveness...`,
+      );
+      for (const candidate of candidates) {
+        if (await isReachable(candidate.server.endpoint)) {
+          onLog?.(`Found live server at ${candidate.server.endpoint}`);
+          return candidate.server;
+        }
+        onLog?.(`Skipping unreachable entry: ${candidate.server.endpoint}`);
       }
     }
   } catch {
     // Channel might not be attached yet, fall through to subscribe
   }
 
-  // Subscribe to presence and wait for a server to appear
+  // No live server yet — subscribe to presence and wait for one to
+  // enter. Probe each entry as it arrives so late-arriving stale
+  // entries (e.g. history replay) don't take precedence over real
+  // live servers.
   return new Promise<DiscoveredServer | null>((resolve) => {
     let resolved = false;
+    let timeoutHandle: NodeJS.Timeout | undefined;
 
     const cleanup = () => {
       if (!resolved) {
         resolved = true;
+        if (timeoutHandle) clearTimeout(timeoutHandle);
         channel.presence.unsubscribe(onPresenceEvent);
       }
     };
 
-    const onPresenceEvent = (message: Ably.PresenceMessage) => {
-      if (message.action === "enter" || message.action === "present") {
-        const server = extractServerFromPresence(message);
-        if (server) {
-          onLog?.(`Found server at ${server.endpoint}`);
-          cleanup();
-          resolve(server);
-        }
+    const onPresenceEvent = async (message: Ably.PresenceMessage) => {
+      if (resolved) return;
+      if (message.action !== "enter" && message.action !== "present") {
+        return;
+      }
+      const server = extractServerFromPresence(message);
+      if (!server) return;
+      if (await isReachable(server.endpoint)) {
+        if (resolved) return;
+        onLog?.(`Found live server at ${server.endpoint}`);
+        cleanup();
+        resolve(server);
+      } else {
+        onLog?.(`Ignoring unreachable presence: ${server.endpoint}`);
       }
     };
 
     channel.presence.subscribe(onPresenceEvent);
 
-    // Timeout
-    setTimeout(() => {
+    timeoutHandle = setTimeout(() => {
       if (!resolved) {
         onLog?.("No server found within timeout");
         cleanup();
@@ -81,6 +111,30 @@ export async function discoverServer(
   });
 }
 
+/**
+ * Quickly probe whether an endpoint is actually reachable. Uses OPTIONS
+ * (the demo server responds with 204 + CORS headers) so the probe is
+ * cheap and side-effect free.
+ */
+async function isReachable(
+  endpoint: string,
+  probeTimeoutMs = 750,
+): Promise<boolean> {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), probeTimeoutMs);
+    const res = await fetch(endpoint, {
+      method: "OPTIONS",
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+    // Any non-5xx response means something is listening.
+    return res.status < 500;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Extract server info from a presence message.
  * The server enters presence with { endpoint: "http://localhost:PORT" }.
diff --git a/test/unit/commands/ai-transport/demo/lib/client-discovery.test.ts b/test/unit/commands/ai-transport/demo/lib/client-discovery.test.ts
index a2ff09011..133e36b9b 100644
--- a/test/unit/commands/ai-transport/demo/lib/client-discovery.test.ts
+++ b/test/unit/commands/ai-transport/demo/lib/client-discovery.test.ts
@@ -1,8 +1,13 @@
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { discoverServer } from "../../../../../../src/services/ai-transport-demo/lib/client-discovery.js";
 
 function createMockChannel(opts?: {
-  presenceMembers?: Array<{ data: unknown; clientId?: string; action?: string }>;
+  presenceMembers?: Array<{
+    data: unknown;
+    clientId?: string;
+    action?: string;
+    timestamp?: number;
+  }>;
 }) {
   let subscribeCallback: ((msg: any) => void) | null = null;
 
@@ -26,15 +31,42 @@ function createMockChannel(opts?: {
       data: unknown;
       clientId?: string;
       action: string;
+      timestamp?: number;
     }) {
       subscribeCallback?.(member);
     },
   } as any;
 }
 
+/**
+ * Install a fake `fetch` that answers the HTTP liveness probe based on
+ * a map of endpoint→reachable. discoverServer uses OPTIONS requests to
+ * check each candidate endpoint.
+ */
+function installFetchMock(reachable: Record<string, boolean>) {
+  const fn = vi.fn(async (url: string | URL) => {
+    const key = String(url);
+    if (reachable[key]) {
+      return new Response(null, { status: 204 });
+    }
+    throw new Error(`ECONNREFUSED: ${key}`);
+  });
+  vi.stubGlobal("fetch", fn);
+  return fn;
+}
+
 describe("client-discovery", () => {
+  beforeEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
   describe("discoverServer", () => {
     it("should find server from existing presence members", async () => {
+      installFetchMock({ "http://localhost:12345": true });
       const channel = createMockChannel({
         presenceMembers: [
           {
@@ -53,6 +85,7 @@ describe("client-discovery", () => {
     });
 
     it("should find server when it enters after subscription", async () => {
+      installFetchMock({ "http://localhost:9999": true });
       const channel = createMockChannel({ presenceMembers: [] });
 
       // Start discovery, then simulate server entering
@@ -75,6 +108,64 @@ describe("client-discovery", () => {
       });
     });
 
+    it("should skip unreachable presence entries and pick a live one", async () => {
+      installFetchMock({
+        "http://localhost:57057": false, // stale entry
+        "http://localhost:58116": true, // live server
+      });
+      const channel = createMockChannel({
+        presenceMembers: [
+          {
+            data: { endpoint: "http://localhost:57057" },
+            clientId: "stale",
+            timestamp: 2000, // newer timestamp, but unreachable
+          },
+          {
+            data: { endpoint: "http://localhost:58116" },
+            clientId: "live",
+            timestamp: 1000, // older, but reachable
+          },
+        ],
+      });
+
+      const result = await discoverServer(channel, 1000);
+
+      expect(result).toEqual({
+        endpoint: "http://localhost:58116",
+        clientId: "live",
+      });
+    });
+
+    it("should wait for a reachable server when presence only has stale entries", async () => {
+      installFetchMock({
+        "http://localhost:57057": false, // stale
+        "http://localhost:58116": true, // new live server enters after
+      });
+      const channel = createMockChannel({
+        presenceMembers: [
+          {
+            data: { endpoint: "http://localhost:57057" },
+            clientId: "stale",
+          },
+        ],
+      });
+
+      const discoveryPromise = discoverServer(channel, 5000);
+      await new Promise((resolve) => setTimeout(resolve, 20));
+
+      channel._simulatePresenceEvent({
+        action: "enter",
+        data: { endpoint: "http://localhost:58116" },
+        clientId: "live",
+      });
+
+      const result = await discoveryPromise;
+      expect(result).toEqual({
+        endpoint: "http://localhost:58116",
+        clientId: "live",
+      });
+    });
+
     it("should return null when no server found within timeout", async () => {
       const channel = createMockChannel({ presenceMembers: [] });
 
@@ -114,6 +205,7 @@ describe("client-discovery", () => {
     });
 
     it("should call onLog callback", async () => {
+      installFetchMock({ "http://localhost:12345": true });
       const channel = createMockChannel({
         presenceMembers: [
           { data: { endpoint: "http://localhost:12345" } },
@@ -126,7 +218,7 @@ describe("client-discovery", () => {
       expect(logs.some((l) => l.includes("Searching for server"))).toBe(
         true,
       );
-      expect(logs.some((l) => l.includes("Found server"))).toBe(true);
+      expect(logs.some((l) => l.includes("live server"))).toBe(true);
     });
 
     it("should handle presence.get failure gracefully", async () => {

From d5d6012c9538ad14947e2e9bca9a4dccd2871d47 Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Tue, 21 Apr 2026 23:23:41 +0200
Subject: [PATCH 14/17] =?UTF-8?q?feat(ai-transport):=20streaming=20demo=20?=
 =?UTF-8?q?polish=20=E2=80=94=20ordering,=20scrollback,=20UX?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Complete the end-to-end streaming demo with the fixes that make it usable
in practice.

Message ordering
  Publish user messages via turn.addMessages() on the server so they land
  on the channel with a real serial. The client transport's send() only
  does an optimistic local insert; without the server also publishing,
  user messages stayed at null-serial and sorted AFTER serial-bearing
  assistant responses in ConversationTree.flatten(). The client
  de-duplicates via its _ownMsgIds set keyed on x-ably-msg-id, so no
  double-render.

Server log: in-place token progress with turn IDs
  New "serverStatus" event on the orchestrator carries a transient
  single-line status. Every text-delta emits "<turnId>… streaming: N
  tokens" which updates in place rather than appending a line per token.
  Cleared on turn end or error; the final "turn:end N tokens" line then
  appends to history. All lifecycle logs (turn:start, streaming response,
  turn:end, failures) now lead with a short turn ID so you can correlate
  them.

Conversation viewport + scrollback
  ClientPanel rewritten to slice messages into a bounded viewport with
  independent head/tail crop. Required because Ink does not clip flex
  overflow — content taller than the client panel would push the debug
  log and input bar off the bottom. selectWindow() computes absolute
  line ranges per message and head-crops content above the window,
  tail-crops content below, so the right slice renders whether the
  window is at the top of history, middle, or pinned to live bottom.

  PageUp/PageDown (Fn+↑/↓ on Mac) scroll by ~90% of a screen with one
  line of overlap. Home/End (Fn+←/→) jump to top and back to live.
  Sending a new message auto-resets to live. When new tokens arrive
  while scrolled up, the offset is adjusted so the view stays anchored
  to the absolute content the user was reading rather than drifting
  with the stream. "↓ N lines below · End to jump to live" and
  "↑ N lines above" hints show at the viewport edges.

Misc UI fixes
  * Every message (not just assistant) gets a blank separator line above
    it so "You:" doesn't butt up against the previous "Agent:" response.
  * Drop the 🖥 emoji from the server panel header — it renders as two
    terminal columns but Ink measures it as one, which crowded the
    "Server" label and shifted the right border by one column.
  * Revert fake-LLM baseDelayMs from 80ms back to 40ms — the comment
    about rate limits was wrong; appendMessage is not rate-limited at
    the 50/sec per-channel publish ceiling.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/commands/ai-transport/demo/streaming.ts   |  30 ++-
 .../ai-transport-demo/lib/fake-llm.ts         |   2 +-
 .../ai-transport-demo/lib/orchestrator.ts     |  96 ++++++--
 src/services/ai-transport-demo/lib/server.ts  |   5 +-
 src/services/ai-transport-demo/ui/App.tsx     | 102 +++++++-
 .../ai-transport-demo/ui/ClientPanel.tsx      | 229 ++++++++++++++++--
 .../ai-transport-demo/ui/InputBar.tsx         |   4 +-
 .../ai-transport-demo/ui/ServerPanel.tsx      |  12 +-
 .../ai-transport-demo/ui/hooks/use-demo.ts    |   7 +-
 src/services/ai-transport-demo/ui/theme.ts    |   6 -
 10 files changed, 425 insertions(+), 68 deletions(-)

diff --git a/src/commands/ai-transport/demo/streaming.ts b/src/commands/ai-transport/demo/streaming.ts
index c8166f600..888b51afb 100644
--- a/src/commands/ai-transport/demo/streaming.ts
+++ b/src/commands/ai-transport/demo/streaming.ts
@@ -141,7 +141,17 @@ export default class StreamingDemo extends ControlBaseCommand {
         return;
       }
 
-      this.origStderrWrite?.call(process.stderr, `Unhandled error: ${msg}\n`);
+      // Route rate limit and other SDK errors to the server log
+      // instead of dumping them to stderr
+      if (msg.includes("Rate limit") || msg.includes("rate limit")) {
+        orchestratorRef?.emit("serverLog", `⚠ Rate limit hit`);
+        return;
+      }
+
+      orchestratorRef?.emit(
+        "serverLog",
+        `⚠ ${msg.slice(0, 80)}`,
+      );
     };
 
     // 2. Intercept process.stdout.write and process.stderr.write to
@@ -155,14 +165,16 @@ export default class StreamingDemo extends ControlBaseCommand {
     this.unhandledHandler = unhandledHandler;
 
     const isSuppressable = (str: string): boolean =>
-      mutableErrorDetected &&
-      (str.includes("93002") ||
-        str.includes("mutableMessages") ||
-        str.includes("onNack") ||
-        str.includes("80017") ||
-        str.includes("failQueuedMessages") ||
-        str.includes("PromiseRejectionHandledWarning") ||
-        str.includes("AblySDK Error"));
+      (mutableErrorDetected &&
+        (str.includes("93002") ||
+          str.includes("mutableMessages") ||
+          str.includes("onNack") ||
+          str.includes("80017") ||
+          str.includes("failQueuedMessages") ||
+          str.includes("PromiseRejectionHandledWarning") ||
+          str.includes("AblySDK Error"))) ||
+      str.includes("Rate limit") ||
+      str.includes("rate limit");
 
     process.stdout.write = ((chunk: unknown, ...args: unknown[]) => {
       if (typeof chunk === "string" && isSuppressable(chunk)) return true;
diff --git a/src/services/ai-transport-demo/lib/fake-llm.ts b/src/services/ai-transport-demo/lib/fake-llm.ts
index b7a4103b5..8771012a0 100644
--- a/src/services/ai-transport-demo/lib/fake-llm.ts
+++ b/src/services/ai-transport-demo/lib/fake-llm.ts
@@ -17,7 +17,7 @@ export interface FakeLLMOptions {
   feature: string;
   /** The user's message (for keyword matching). */
   userMessage: string;
-  /** Override the base delay between tokens in ms (default ~40ms). */
+  /** Override the base delay between tokens in ms (default 40ms). */
   baseDelayMs?: number;
   /** AbortSignal to cancel generation early. */
   signal?: AbortSignal;
diff --git a/src/services/ai-transport-demo/lib/orchestrator.ts b/src/services/ai-transport-demo/lib/orchestrator.ts
index e5be1ec10..871919893 100644
--- a/src/services/ai-transport-demo/lib/orchestrator.ts
+++ b/src/services/ai-transport-demo/lib/orchestrator.ts
@@ -14,7 +14,7 @@ import type {
   TurnLifecycleEvent,
 } from "@ably/ai-transport";
 
-import { DemoCodec, type DemoMessage } from "./codec.js";
+import { DemoCodec, setDecoderDebug, type DemoMessage } from "./codec.js";
 import { createFakeLLMStream, type FakeLLMEvent } from "./fake-llm.js";
 import {
   createDemoServer,
@@ -48,6 +48,7 @@ export interface DemoOrchestrator extends EventEmitter {
   close(): Promise<void>;
 
   on(event: "serverLog", listener: (message: string) => void): this;
+  on(event: "serverStatus", listener: (status: string | null) => void): this;
   on(event: "debugLog", listener: (message: string) => void): this;
   on(event: "messages", listener: (msgs: DemoMessage[]) => void): this;
   on(event: "serverReady", listener: (data: { port: number }) => void): this;
@@ -68,6 +69,26 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
   let serverEndpoint: string | null = explicitEndpoint ?? null;
   let activeTurnAbort: AbortController | null = null;
   let streaming = false;
+  let activeClientTurnId: string | null = null;
+
+  function emitMessages(): void {
+    if (!clientTransport) return;
+    const msgs = clientTransport.getMessages();
+    // When a turn is active, mark the last assistant message as streaming
+    // so the UI can show the cursor indicator.
+    const withStreamingFlag: Array<DemoMessage & { streaming?: boolean }> =
+      msgs.map((m, i) => {
+        if (
+          activeClientTurnId &&
+          i === msgs.length - 1 &&
+          m.role === "assistant"
+        ) {
+          return { ...m, streaming: true };
+        }
+        return m;
+      });
+    emitter.emit("messages", withStreamingFlag);
+  }
 
   // ── Server side ──
 
@@ -107,7 +128,8 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
     activeTurnAbort = abortController;
     streaming = true;
 
-    emitter.emit("serverLog", `→ turn:start ${turnId.slice(0, 8)}…`);
+    const shortTurnId = turnId.slice(0, 8);
+    emitter.emit("serverLog", `→ ${shortTurnId}… turn:start`);
 
     let turn: ReturnType<typeof serverTransport.newTurn> | null = null;
 
@@ -119,20 +141,49 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
 
       await turn.start();
 
-      // Note: we do NOT call turn.addMessages() here because the client
-      // transport already published the user message to the channel when
-      // it called send(). Re-publishing would cause a duplicate.
+      // Publish the user message(s) back to the channel via addMessages().
+      // The client transport's send() only inserts them optimistically into
+      // its local tree (with no serial) and sends them in the HTTP POST body
+      // — it does NOT publish them on the channel. Without addMessages the
+      // user message stays at null-serial, which sorts AFTER serial-bearing
+      // assistant messages in ConversationTree.flatten(). The client
+      // de-duplicates via its _ownMsgIds set using the x-ably-msg-id header.
+      if (body.messages && body.messages.length > 0) {
+        await turn.addMessages(
+          body.messages.map((m) => ({
+            message: m.message as DemoMessage,
+            headers: m.headers ?? {},
+          })),
+        );
+      }
 
-      // Stream fake LLM response through the encoder
+      // Stream fake LLM response through the encoder, counting tokens so
+      // we can surface periodic progress updates on the server log.
+      let tokenCount = 0;
       const llmStream = createFakeLLMStream({
         feature,
         userMessage,
         signal: abortController.signal,
       });
+      const progressStream = new TransformStream<FakeLLMEvent, FakeLLMEvent>({
+        transform(event, controller) {
+          if (event.type === "text-delta") {
+            tokenCount++;
+            // In-place status update — the UI renders this as a single
+            // line that overwrites itself, rather than appending to the log.
+            emitter.emit(
+              "serverStatus",
+              `${shortTurnId}… streaming: ${tokenCount} tokens`,
+            );
+          }
+          controller.enqueue(event);
+        },
+      });
 
-      emitter.emit("serverLog", "→ streaming response...");
-
-      const result = await turn.streamResponse(llmStream);
+      emitter.emit("serverLog", `→ ${shortTurnId}… streaming response`);
+      const result = await turn.streamResponse(
+        llmStream.pipeThrough(progressStream),
+      );
 
       try {
         await turn.end(result.reason);
@@ -140,9 +191,11 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
         // Connection may already be closing
       }
 
+      // Clear the in-place status and append the final log line
+      emitter.emit("serverStatus", null);
       emitter.emit(
         "serverLog",
-        `← turn:end ${turnId.slice(0, 8)}… (${result.reason})`,
+        `← ${shortTurnId}… turn:end ${tokenCount} tokens (${result.reason})`,
       );
       emitter.emit("turnEnd", { turnId, reason: result.reason });
     } catch (error: unknown) {
@@ -172,7 +225,7 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
           : String(error);
       emitter.emit(
         "serverLog",
-        `✗ turn ${turnId.slice(0, 8)}… failed: ${errorMsg}`,
+        `✗ ${shortTurnId}… failed: ${errorMsg}`,
       );
       emitter.emit(
         "error",
@@ -181,6 +234,7 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
     } finally {
       streaming = false;
       activeTurnAbort = null;
+      emitter.emit("serverStatus", null);
     }
   }
 
@@ -189,6 +243,9 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
   emitter.startClient = async () => {
     emitter.emit("debugLog", "Starting client...");
 
+    // Decoder debug is noisy — leave off for now
+    setDecoderDebug(null);
+
     // Discover server if no explicit endpoint
     if (!serverEndpoint) {
       emitter.emit("debugLog", "Discovering server via presence...");
@@ -217,8 +274,7 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
 
     // Subscribe to message changes — emit the full message list on each update
     clientTransport.on("message", () => {
-      const msgs = clientTransport!.getMessages();
-      emitter.emit("messages", msgs);
+      emitMessages();
     });
 
     // Subscribe to turn lifecycle events
@@ -251,14 +307,26 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
       };
 
       const activeTurn = await clientTransport.send(userMsg);
+      activeClientTurnId = activeTurn.turnId;
 
-      // Consume the stream to drive the transport (messages arrive via 'message' event)
+      // The AIT client transport accumulates progressively and fires a
+      // `message` event on every decoded text-delta (see the on('message')
+      // handler in startClient). We just need to drain the stream so the
+      // transport's internal processing runs to completion.
       const reader = activeTurn.stream.getReader();
       while (true) {
         const { done } = await reader.read();
         if (done) break;
       }
+
+      activeClientTurnId = null;
+      emitMessages();
+      emitter.emit("turnEnd", {
+        turnId: activeTurn.turnId,
+        reason: "complete",
+      });
     } catch (error: unknown) {
+      activeClientTurnId = null;
       emitter.emit("debugLog", `Send failed: ${String(error)}`);
     }
   };
diff --git a/src/services/ai-transport-demo/lib/server.ts b/src/services/ai-transport-demo/lib/server.ts
index 23190e406..41dcdbdfc 100644
--- a/src/services/ai-transport-demo/lib/server.ts
+++ b/src/services/ai-transport-demo/lib/server.ts
@@ -26,7 +26,10 @@ export interface DemoServerOptions {
 export interface AitRequestBody {
   turnId: string;
   clientId?: string;
-  messages: Array<{ message: { id: string; role: string; content: string } }>;
+  messages: Array<{
+    message: { id: string; role: string; content: string };
+    headers?: Record<string, string>;
+  }>;
   history?: unknown[];
   parent?: string | null;
   forkOf?: string;
diff --git a/src/services/ai-transport-demo/ui/App.tsx b/src/services/ai-transport-demo/ui/App.tsx
index 4992d7045..bead75ab6 100644
--- a/src/services/ai-transport-demo/ui/App.tsx
+++ b/src/services/ai-transport-demo/ui/App.tsx
@@ -6,9 +6,9 @@
  * - Server (right): activity log, with space for future controls at the bottom
  */
 
-import React, { useState, useEffect } from "react";
+import React, { useState, useEffect, useRef } from "react";
 import { Box, Text, useApp, useInput, useStdout } from "ink";
-import { ClientPanel } from "./ClientPanel.js";
+import { ClientPanel, totalRenderedLines } from "./ClientPanel.js";
 import { ServerPanel } from "./ServerPanel.js";
 import { DebugPanel } from "./DebugPanel.js";
 import { InputBar } from "./InputBar.js";
@@ -34,6 +34,7 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
 
   const [debugExpanded, setDebugExpanded] = useState(false);
   const [mutableMessagesError, setMutableMessagesError] = useState(false);
+  const [scrollOffsetLines, setScrollOffsetLines] = useState(0);
 
   const {
     messages,
@@ -48,6 +49,7 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
 
   const serverLog = useScrollableLog();
   const debugLog = useScrollableLog();
+  const [serverStatusLine, setServerStatusLine] = useState<string | null>(null);
 
   // Wire orchestrator events to log panels, then start server/client.
   // Starting happens inside useEffect so event listeners are attached first
@@ -58,16 +60,20 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
     if (!orchestrator) return;
 
     const onServerLog = (msg: string) => serverLog.addEntry(msg);
+    const onServerStatus = (status: string | null) =>
+      setServerStatusLine(status);
     const onDebugLog = (msg: string) => debugLog.addEntry(msg);
 
     const onMutableRequired = () => setMutableMessagesError(true);
 
     orchestrator.on("serverLog", onServerLog);
+    orchestrator.on("serverStatus", onServerStatus);
     orchestrator.on("debugLog", onDebugLog);
     orchestrator.on("mutableMessagesRequired", onMutableRequired);
 
     return () => {
       orchestrator.off("serverLog", onServerLog);
+      orchestrator.off("serverStatus", onServerStatus);
       orchestrator.off("debugLog", onDebugLog);
       orchestrator.off("mutableMessagesRequired", onMutableRequired);
     };
@@ -111,6 +117,32 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
     };
   }, [stdout]);
 
+  const showClient = role === "both" || role === "client";
+  const showServer = role === "both" || role === "server";
+
+  const clientWidth = showServer ? Math.floor(dims.width * 0.6) : dims.width;
+  const debugLines = debugExpanded ? 8 : 2;
+
+  // Budget lines for the conversation area so it can't push the debug
+  // panel and input off the bottom of the terminal. The layout inside the
+  // client panel border is:
+  //   header (2)  +  marginTop (1)  +  conversation  +
+  //   debug border/header (2) + debug lines  +
+  //   input border/header (2) + input line (1)  +
+  //   outer border (2)
+  const conversationLines = Math.max(
+    3,
+    dims.height - (2 + 1 + 2 + debugLines + 2 + 1 + 2),
+  );
+  // Approximate usable width inside the conversation area (paddingX=1 on
+  // both sides + 2 for the outer border).
+  const conversationWidth = Math.max(10, clientWidth - 4);
+
+  // Total lines the conversation would render if unbounded. Used to
+  // maintain scroll position as new tokens arrive during streaming.
+  const totalLines = totalRenderedLines(messages, conversationWidth);
+  const maxScrollable = Math.max(0, totalLines - conversationLines);
+
   // Keyboard handling
   useInput((input, key) => {
     if (input === "d" && key.ctrl) {
@@ -125,14 +157,57 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
 
     if (key.tab) {
       setDebugExpanded((prev) => !prev);
+      return;
+    }
+
+    // Scroll: page up/down step ~90% of a screen so there's a line of
+    // context overlap between pages. Home/End jump to top/live.
+    const pageStep = Math.max(1, Math.floor(conversationLines * 0.9));
+    if (key.pageUp) {
+      setScrollOffsetLines((prev) => Math.min(prev + pageStep, maxScrollable));
+      return;
+    }
+    if (key.pageDown) {
+      setScrollOffsetLines((prev) => Math.max(0, prev - pageStep));
+      return;
+    }
+    if (key.meta && key.upArrow) {
+      // Home
+      setScrollOffsetLines(maxScrollable);
+      return;
+    }
+    if (key.meta && key.downArrow) {
+      // End
+      setScrollOffsetLines(0);
+      return;
     }
   });
 
-  const showClient = role === "both" || role === "client";
-  const showServer = role === "both" || role === "server";
+  // When content grows while the user is scrolled up, bump the offset by
+  // the growth delta so their view stays anchored to the same absolute
+  // content rather than drifting with the stream.
+  const prevTotalLinesRef = useRef(totalLines);
+  useEffect(() => {
+    const delta = totalLines - prevTotalLinesRef.current;
+    if (delta > 0 && scrollOffsetLines > 0) {
+      setScrollOffsetLines((prev) => Math.min(prev + delta, maxScrollable));
+    }
+    prevTotalLinesRef.current = totalLines;
+  }, [totalLines, scrollOffsetLines, maxScrollable]);
 
-  const clientWidth = showServer ? Math.floor(dims.width * 0.6) : dims.width;
-  const debugLines = debugExpanded ? 8 : 2;
+  // Reset to follow mode whenever the user sends a new message. We detect
+  // a send by watching the message count; any growth of user messages
+  // means a new turn was kicked off from this client.
+  const prevMsgCountRef = useRef(messages.length);
+  useEffect(() => {
+    if (messages.length > prevMsgCountRef.current) {
+      const newest = messages.at(-1);
+      if (newest?.role === "user") {
+        setScrollOffsetLines(0);
+      }
+    }
+    prevMsgCountRef.current = messages.length;
+  }, [messages]);
 
   // Server status for client panel
   if (mutableMessagesError) {
@@ -161,12 +236,22 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
             <Text color={colors.dim}>Channel: {channelName}</Text>
           </Box>
 
-          {/* Conversation area — fills available space */}
-          <Box flexDirection="column" flexGrow={1} paddingX={1} marginTop={1}>
+          {/* Conversation area — height-bounded so overflow doesn't push
+              the debug panel and input bar off the bottom. */}
+          <Box
+            flexDirection="column"
+            height={conversationLines}
+            paddingX={1}
+            marginTop={1}
+            overflow="hidden"
+          >
             <ClientPanel
               messages={messages}
               serverStatus={serverStatus}
               isStreaming={isStreaming}
+              maxLines={conversationLines}
+              contentWidth={conversationWidth}
+              scrollOffsetLines={scrollOffsetLines}
             />
           </Box>
 
@@ -229,6 +314,7 @@ export function App({ role, feature, channelName, orchestrator }: AppProps) {
           <Box flexDirection="column" flexGrow={1} paddingX={1}>
             <ServerPanel
               entries={serverLog.entries}
+              status={serverStatusLine}
               port={serverPort ?? undefined}
               isRunning={serverRunning}
               maxVisible={dims.height - (showClient ? 4 : 8)}
diff --git a/src/services/ai-transport-demo/ui/ClientPanel.tsx b/src/services/ai-transport-demo/ui/ClientPanel.tsx
index a7e9827b2..d60776c05 100644
--- a/src/services/ai-transport-demo/ui/ClientPanel.tsx
+++ b/src/services/ai-transport-demo/ui/ClientPanel.tsx
@@ -19,13 +19,49 @@ interface ClientPanelProps {
   messages: ConversationMessage[];
   serverStatus: "connecting" | "connected" | "not-found";
   isStreaming: boolean;
+  /** Total lines available inside the conversation box. */
+  maxLines: number;
+  /** Approximate usable character width inside the panel (for wrap estimation). */
+  contentWidth: number;
+  /** Lines scrolled up from the bottom (0 = follow latest). */
+  scrollOffsetLines: number;
+}
+
+interface WindowSlice {
+  msg: ConversationMessage;
+  displayContent: string;
+  headEllipsis: boolean;
+  tailEllipsis: boolean;
+  /** True if this is the first slice in the viewport (no top margin). */
+  isFirst: boolean;
 }
 
 export function ClientPanel({
   messages,
   serverStatus,
   isStreaming,
+  maxLines,
+  contentWidth,
+  scrollOffsetLines,
 }: ClientPanelProps) {
+  // Compute the visible window: walk messages, find those whose line ranges
+  // intersect the viewport, and head/tail-crop content as needed so that
+  // any scroll position (top of history, middle, live at the bottom) shows
+  // the right slice of content.
+  const { slices, totalLines } = selectWindow(
+    messages,
+    maxLines,
+    contentWidth,
+    scrollOffsetLines,
+  );
+  const linesBelowViewport = scrollOffsetLines;
+  const hasMoreBelow = linesBelowViewport > 0;
+  const linesAboveViewport = Math.max(
+    0,
+    totalLines - scrollOffsetLines - maxLines,
+  );
+  const hasMoreAbove = linesAboveViewport > 0;
+
   return (
     <Box flexDirection="column" flexGrow={1}>
       {serverStatus === "not-found" && (
@@ -45,31 +81,178 @@ export function ClientPanel({
           </Text>
         )}
 
-      {messages.map((msg) => (
-        <Box key={msg.id} flexDirection="column" marginBottom={1}>
-          {msg.role === "user" ? (
-            <Text>
-              <Text color={colors.user} bold>
-                You:{" "}
-              </Text>
-              <Text>{msg.content}</Text>
-            </Text>
-          ) : (
-            <Text>
-              <Text color={colors.primary} bold>
-                Agent:{" "}
+      {hasMoreBelow && (
+        <Text color={colors.dim}>
+          ↓ {linesBelowViewport} line{linesBelowViewport === 1 ? "" : "s"} below
+          {" · "}End to jump to live
+        </Text>
+      )}
+      {slices.map((slice) => {
+        const { msg, displayContent, headEllipsis, tailEllipsis, isFirst } =
+          slice;
+        const content =
+          (headEllipsis ? "…" : "") +
+          displayContent +
+          (tailEllipsis ? "…" : "");
+        return (
+          <Box key={msg.id} flexDirection="column" marginTop={isFirst ? 0 : 1}>
+            {msg.role === "user" ? (
+              <Text>
+                <Text color={colors.user} bold>
+                  You:{" "}
+                </Text>
+                <Text>{content}</Text>
               </Text>
-              <Text color={colors.assistant}>
-                {msg.content}
-                {msg.streaming && <Text color={colors.dim}>▊</Text>}
-                {msg.interrupted && (
-                  <Text color={colors.warning}> [interrupted]</Text>
-                )}
+            ) : (
+              <Text>
+                <Text color={colors.primary} bold>
+                  Agent:{" "}
+                </Text>
+                <Text color={colors.assistant}>
+                  {content}
+                  {msg.streaming && !tailEllipsis && (
+                    <Text color={colors.dim}>▊</Text>
+                  )}
+                  {msg.interrupted && (
+                    <Text color={colors.warning}> [interrupted]</Text>
+                  )}
+                </Text>
               </Text>
-            </Text>
-          )}
-        </Box>
-      ))}
+            )}
+          </Box>
+        );
+      })}
+      {hasMoreAbove && (
+        <Text color={colors.dim}>
+          ↑ {linesAboveViewport} line{linesAboveViewport === 1 ? "" : "s"} above
+        </Text>
+      )}
     </Box>
   );
 }
+
+/**
+ * Word-boundary wrapping leaves gaps at line ends — a line rarely fills to
+ * the terminal width. Scale the effective width down so our line-count
+ * estimates match what Ink actually renders and we don't overshoot the
+ * height budget.
+ */
+const WRAP_EFFICIENCY = 0.85;
+
+function effectiveWidth(contentWidth: number): number {
+  return Math.max(1, Math.floor(contentWidth * WRAP_EFFICIENCY));
+}
+
+/**
+ * Total rendered-line count for the whole conversation. Used by App.tsx
+ * to clamp the scroll offset and to maintain scroll position as content
+ * grows during streaming.
+ */
+export function totalRenderedLines(
+  messages: ConversationMessage[],
+  contentWidth: number,
+): number {
+  let total = 0;
+  for (let i = 0; i < messages.length; i++) {
+    const separator = i > 0 ? 1 : 0;
+    total += estimateMessageLines(messages[i], contentWidth) + separator;
+  }
+  return total;
+}
+
+/**
+ * Slice the conversation to the lines currently inside the scrollable
+ * viewport. Handles both head- and tail-crop independently: when the user
+ * scrolls to the top of the history, the *first* message should show its
+ * beginning; when the user is at the live bottom, the newest message
+ * shows its end (streaming tail).
+ *
+ * offset = 0 means the viewport sits against the bottom of the content.
+ * offset = maxScrollable means the viewport sits against the top.
+ */
+function selectWindow(
+  messages: ConversationMessage[],
+  maxLines: number,
+  contentWidth: number,
+  offset: number,
+): { slices: WindowSlice[]; totalLines: number } {
+  const effWidth = effectiveWidth(contentWidth);
+  if (messages.length === 0 || maxLines <= 0) {
+    return { slices: [], totalLines: 0 };
+  }
+
+  // Absolute line positions (from top of the virtual conversation).
+  type Position = { top: number; bottom: number };
+  const positions: Position[] = [];
+  let cursor = 0;
+  for (let i = 0; i < messages.length; i++) {
+    const sep = i > 0 ? 1 : 0;
+    cursor += sep;
+    const top = cursor;
+    const msgLines = estimateMessageLines(messages[i], contentWidth);
+    cursor += msgLines;
+    positions.push({ top, bottom: cursor });
+  }
+  const totalLines = cursor;
+
+  // Viewport in absolute line coordinates. `offset` is measured from the
+  // bottom so offset=0 → viewport flush with bottom.
+  const windowBottom = totalLines - offset;
+  const windowTop = windowBottom - maxLines;
+
+  const slices: WindowSlice[] = [];
+  for (let i = 0; i < messages.length; i++) {
+    const { top, bottom } = positions[i];
+    // Entirely above the viewport (older content scrolled off the top)
+    if (bottom <= windowTop) continue;
+    // Entirely below the viewport (newer content scrolled off the bottom)
+    if (top >= windowBottom) break;
+
+    const linesAbove = Math.max(0, windowTop - top);
+    const linesBelow = Math.max(0, bottom - windowBottom);
+    const rolePrefixLen = messages[i].role === "user" ? 5 : 7;
+
+    let displayContent = messages[i].content;
+
+    // Head-crop: the first `linesAbove` display lines of this message are
+    // above the viewport. The very first line carries the role prefix
+    // ("You: ") so subtract that from the first line's char budget.
+    if (linesAbove > 0) {
+      const skipChars = Math.max(0, linesAbove * effWidth - rolePrefixLen);
+      displayContent = displayContent.slice(
+        Math.min(skipChars, displayContent.length),
+      );
+    }
+
+    // Tail-crop: the last `linesBelow` display lines are below the viewport.
+    if (linesBelow > 0) {
+      const keepChars = Math.max(
+        0,
+        displayContent.length - linesBelow * effWidth,
+      );
+      displayContent = displayContent.slice(0, keepChars);
+    }
+
+    slices.push({
+      msg: messages[i],
+      displayContent,
+      headEllipsis: linesAbove > 0,
+      tailEllipsis: linesBelow > 0,
+      isFirst: slices.length === 0,
+    });
+  }
+
+  return { slices, totalLines };
+}
+
+/** Estimate how many terminal lines a message will occupy once wrapped. */
+function estimateMessageLines(
+  msg: ConversationMessage,
+  contentWidth: number,
+): number {
+  // Role label ("You: " or "Agent: ") plus content, plus trailing indicators.
+  const rolePrefixLen = msg.role === "user" ? 5 : 7;
+  const suffixLen = (msg.streaming ? 1 : 0) + (msg.interrupted ? 14 : 0);
+  const totalChars = rolePrefixLen + msg.content.length + suffixLen;
+  return Math.max(1, Math.ceil(totalChars / effectiveWidth(contentWidth)));
+}
diff --git a/src/services/ai-transport-demo/ui/InputBar.tsx b/src/services/ai-transport-demo/ui/InputBar.tsx
index 3e3d3d7fe..e27845711 100644
--- a/src/services/ai-transport-demo/ui/InputBar.tsx
+++ b/src/services/ai-transport-demo/ui/InputBar.tsx
@@ -46,8 +46,8 @@ export function InputBar({
       </Box>
       <Text color={colors.dim}>
         {isStreaming
-          ? "  Ctrl+C cancel │ Ctrl+D quit"
-          : "  Enter send │ Tab debug │ Ctrl+D quit"}
+          ? "  Ctrl+C cancel │ PgUp/PgDn scroll │ Ctrl+D quit"
+          : "  Enter send │ Tab debug │ PgUp/PgDn scroll │ Ctrl+D quit"}
       </Text>
     </Box>
   );
diff --git a/src/services/ai-transport-demo/ui/ServerPanel.tsx b/src/services/ai-transport-demo/ui/ServerPanel.tsx
index 5672ca3db..7e8dddeb1 100644
--- a/src/services/ai-transport-demo/ui/ServerPanel.tsx
+++ b/src/services/ai-transport-demo/ui/ServerPanel.tsx
@@ -10,6 +10,7 @@ import { colors, symbols } from "./theme.js";
 
 interface ServerPanelProps {
   entries: LogEntry[];
+  status: string | null;
   port?: number;
   isRunning: boolean;
   maxVisible?: number;
@@ -17,6 +18,7 @@ interface ServerPanelProps {
 
 export function ServerPanel({
   entries,
+  status,
   port,
   isRunning,
   maxVisible = 20,
@@ -29,7 +31,7 @@ export function ServerPanel({
       {/* Header */}
       <Box>
         <Text bold>
-          {symbols.server} Server
+          Server
           {port ? (
             <Text color={isRunning ? colors.success : colors.dim}>
               {" "}
@@ -43,7 +45,7 @@ export function ServerPanel({
 
       {/* Log entries */}
       <Box flexDirection="column" flexGrow={1} marginTop={1}>
-        {visible.length === 0 && (
+        {visible.length === 0 && !status && (
           <Text color={colors.dim}>Waiting for activity...</Text>
         )}
         {visible.map((entry, i) => (
@@ -52,6 +54,12 @@ export function ServerPanel({
             <Text>{colorizeLogMessage(entry.message)}</Text>
           </Text>
         ))}
+        {/* In-place status line — updates rather than appends */}
+        {status && (
+          <Text color={colors.event} wrap="truncate">
+            → {status}
+          </Text>
+        )}
       </Box>
     </Box>
   );
diff --git a/src/services/ai-transport-demo/ui/hooks/use-demo.ts b/src/services/ai-transport-demo/ui/hooks/use-demo.ts
index 58b964f76..a1fa0e850 100644
--- a/src/services/ai-transport-demo/ui/hooks/use-demo.ts
+++ b/src/services/ai-transport-demo/ui/hooks/use-demo.ts
@@ -49,13 +49,16 @@ export function useDemo(orchestrator: DemoOrchestrator | null): UseDemoResult {
       setServerStatus("not-found");
     };
 
-    // The orchestrator emits the full message list from the AIT client transport
-    const onMessages = (msgs: DemoMessage[]) => {
+    // The orchestrator emits the full message list from the AIT client
+    // transport. Progressive streaming updates include an optional `streaming`
+    // flag on the in-progress assistant message for the cursor indicator.
+    const onMessages = (msgs: Array<DemoMessage & { streaming?: boolean }>) => {
       setMessages(
         msgs.map((m) => ({
           id: m.id,
           role: m.role,
           content: m.content,
+          streaming: m.streaming,
         })),
       );
     };
diff --git a/src/services/ai-transport-demo/ui/theme.ts b/src/services/ai-transport-demo/ui/theme.ts
index 861718169..1739e4d46 100644
--- a/src/services/ai-transport-demo/ui/theme.ts
+++ b/src/services/ai-transport-demo/ui/theme.ts
@@ -41,10 +41,4 @@ export const symbols = {
   warn: "⚠",
   /** Feature highlight */
   feature: "⚡",
-  /** Debug toggle hint */
-  debug: "🔍",
-  /** Client panel */
-  client: "💬",
-  /** Server panel */
-  server: "🖥",
 } as const;

From deb551459dc95165ab24b7243f0acebad7962799 Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Tue, 21 Apr 2026 23:41:18 +0200
Subject: [PATCH 15/17] =?UTF-8?q?feat(ai-transport):=20barge-in=20demo=20?=
 =?UTF-8?q?=E2=80=94=20interrupt=20a=20streaming=20response?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduce the second demo in the ai-transport topic. Type a message while
the agent is still streaming and the in-flight response is cancelled,
marked interrupted in the UI, and a new turn starts for the new message.

Implementation
  * New command src/commands/ai-transport/demo/barge-in.ts, plus
    response bank responses/barge-in.ts full of deliberately long,
    self-aware replies that invite the user to interrupt.
  * Shared runner lib/run-demo.ts extracted from the old streaming.ts
    so barge-in (and the future cancel demo) stay as thin command
    shells. streaming.ts re-pointed at the shared runner.
  * orchestrator.sendMessage() detects an in-flight own turn and
    publishes clientTransport.cancel({own: true}) before starting the
    new turn. The currently-streaming assistant message id is added to
    interruptedMessageIds, and emitMessages() passes both `streaming`
    and `interrupted` flags through to the UI.
  * use-demo.ts hook forwards the new `interrupted` flag. ClientPanel
    already renders "[interrupted]" in warning colour.

README regenerated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  46 +++-
 src/commands/ai-transport/demo/barge-in.ts    |  65 +++++
 src/commands/ai-transport/demo/streaming.ts   | 230 ++--------------
 .../ai-transport-demo/lib/fake-llm.ts         |  10 +-
 .../ai-transport-demo/lib/orchestrator.ts     |  64 ++++-
 .../lib/responses/barge-in.ts                 |  20 ++
 .../ai-transport-demo/lib/run-demo.ts         | 256 ++++++++++++++++++
 .../ai-transport-demo/ui/hooks/use-demo.ts    |  11 +-
 8 files changed, 469 insertions(+), 233 deletions(-)
 create mode 100644 src/commands/ai-transport/demo/barge-in.ts
 create mode 100644 src/services/ai-transport-demo/lib/responses/barge-in.ts
 create mode 100644 src/services/ai-transport-demo/lib/run-demo.ts

diff --git a/README.md b/README.md
index f5b5fe17a..de6974fdc 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,7 @@ $ ably-interactive
 * [`ably accounts switch [ALIAS]`](#ably-accounts-switch-alias)
 * [`ably ai-transport`](#ably-ai-transport)
 * [`ably ai-transport demo`](#ably-ai-transport-demo)
+* [`ably ai-transport demo barge-in`](#ably-ai-transport-demo-barge-in)
 * [`ably ai-transport demo streaming`](#ably-ai-transport-demo-streaming)
 * [`ably apps`](#ably-apps)
 * [`ably apps create`](#ably-apps-create)
@@ -428,19 +429,55 @@ EXAMPLES
 
 _See code: [src/commands/ai-transport/demo/index.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/ai-transport/demo/index.ts)_
 
+## `ably ai-transport demo barge-in`
+
+Demo AI Transport barge-in: interrupt a streaming response mid-flight
+
+```
+USAGE
+  $ ably ai-transport demo barge-in [-v] [--json | --pretty-json] [--client-id <value>] [--role both|client|server] [--channel
+    <value>] [--endpoint <value>] [--auth-endpoint <value>]
+
+FLAGS
+  -v, --verbose                Output verbose logs
+      --auth-endpoint=<value>  Auth endpoint returning JWT tokens (client-only, for external servers)
+      --channel=<value>        Channel name to use (auto-generated if not provided)
+      --client-id=<value>      Overrides any default client ID when using API authentication. Use "none" to explicitly
+                               set no client ID. Not applicable when using token authentication.
+      --endpoint=<value>       Server HTTP endpoint for sending messages (client-only, skips presence discovery)
+      --json                   Output in JSON format
+      --pretty-json            Output in colorized JSON format
+      --role=<option>          [default: both] Run as both client and server, or just one side
+                               <options: both|client|server>
+
+DESCRIPTION
+  Demo AI Transport barge-in: interrupt a streaming response mid-flight
+
+EXAMPLES
+  $ ably ai-transport demo barge-in
+
+  $ ably ai-transport demo barge-in --role client --channel my-session
+
+  $ ably ai-transport demo barge-in --role server
+```
+
+_See code: [src/commands/ai-transport/demo/barge-in.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/ai-transport/demo/barge-in.ts)_
+
 ## `ably ai-transport demo streaming`
 
 Demo AI Transport token streaming in a split-pane TUI
 
 ```
 USAGE
-  $ ably ai-transport demo streaming [-v] [--json | --pretty-json] [--role both|client|server] [--channel <value>] [--endpoint
-    <value>] [--auth-endpoint <value>]
+  $ ably ai-transport demo streaming [-v] [--json | --pretty-json] [--client-id <value>] [--role both|client|server] [--channel
+    <value>] [--endpoint <value>] [--auth-endpoint <value>]
 
 FLAGS
   -v, --verbose                Output verbose logs
       --auth-endpoint=<value>  Auth endpoint returning JWT tokens (client-only, for external servers)
       --channel=<value>        Channel name to use (auto-generated if not provided)
+      --client-id=<value>      Overrides any default client ID when using API authentication. Use "none" to explicitly
+                               set no client ID. Not applicable when using token authentication.
       --endpoint=<value>       Server HTTP endpoint for sending messages (client-only, skips presence discovery)
       --json                   Output in JSON format
       --pretty-json            Output in colorized JSON format
@@ -1094,13 +1131,14 @@ Show the current API key for the selected app
 
 ```
 USAGE
-  $ ably auth keys current [-v] [--json | --pretty-json] [--app <value>]
+  $ ably auth keys current [-v] [--json | --pretty-json] [--app <value>] [--value-only]
 
 FLAGS
   -v, --verbose      Output verbose logs
       --app=<value>  The app ID (defaults to current app)
       --json         Output in JSON format
       --pretty-json  Output in colorized JSON format
+      --value-only   Output only the raw API key value, useful for scripting and environment variables
 
 DESCRIPTION
   Show the current API key for the selected app
@@ -1112,7 +1150,7 @@ EXAMPLES
 
   $ ably auth keys current --json
 
-  $ ably auth keys current --pretty-json
+  $ ABLY_API_KEY=$(ably auth keys current --value-only) node my-script.js
 ```
 
 _See code: [src/commands/auth/keys/current.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/auth/keys/current.ts)_
diff --git a/src/commands/ai-transport/demo/barge-in.ts b/src/commands/ai-transport/demo/barge-in.ts
new file mode 100644
index 000000000..fc62b7ed9
--- /dev/null
+++ b/src/commands/ai-transport/demo/barge-in.ts
@@ -0,0 +1,65 @@
+import { Flags } from "@oclif/core";
+
+import { ControlBaseCommand } from "../../../control-base-command.js";
+import { productApiFlags, clientIdFlag } from "../../../flags.js";
+import {
+  runDemo,
+  cleanupDemo,
+  type RunDemoHandles,
+  type DemoCommandHost,
+} from "../../../services/ai-transport-demo/lib/run-demo.js";
+
+export default class BargeInDemo extends ControlBaseCommand {
+  static override description =
+    "Demo AI Transport barge-in: interrupt a streaming response mid-flight";
+
+  static override examples = [
+    "<%= config.bin %> <%= command.id %>",
+    "<%= config.bin %> <%= command.id %> --role client --channel my-session",
+    "<%= config.bin %> <%= command.id %> --role server",
+  ];
+
+  static override flags = {
+    ...productApiFlags,
+    ...clientIdFlag,
+    role: Flags.string({
+      description: "Run as both client and server, or just one side",
+      options: ["both", "client", "server"],
+      default: "both",
+    }),
+    channel: Flags.string({
+      description: "Channel name to use (auto-generated if not provided)",
+    }),
+    endpoint: Flags.string({
+      description:
+        "Server HTTP endpoint for sending messages (client-only, skips presence discovery)",
+    }),
+    "auth-endpoint": Flags.string({
+      description:
+        "Auth endpoint returning JWT tokens (client-only, for external servers)",
+    }),
+  };
+
+  private handles: RunDemoHandles = {
+    orchestrator: null,
+    ablyClient: null,
+    origStdoutWrite: null,
+    origStderrWrite: null,
+    unhandledHandler: null,
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(BargeInDemo);
+    const host: DemoCommandHost = {
+      log: (msg) => this.log(msg),
+      fail: (msg, component) => this.fail(msg, flags, component),
+      createAblyRealtimeClient: () => this.createAblyRealtimeClient(flags),
+    };
+    await runDemo(host, { feature: "barge-in", flags }, this.handles);
+  }
+
+  async finally(error: Error | undefined): Promise<void> {
+    await cleanupDemo(this.handles);
+    await super.finally(error);
+  }
+}
diff --git a/src/commands/ai-transport/demo/streaming.ts b/src/commands/ai-transport/demo/streaming.ts
index 888b51afb..5566ce49f 100644
--- a/src/commands/ai-transport/demo/streaming.ts
+++ b/src/commands/ai-transport/demo/streaming.ts
@@ -1,11 +1,13 @@
-import React from "react";
 import { Flags } from "@oclif/core";
 
 import { ControlBaseCommand } from "../../../control-base-command.js";
 import { productApiFlags, clientIdFlag } from "../../../flags.js";
-import isTestMode from "../../../utils/test-mode.js";
-import { createOrchestrator } from "../../../services/ai-transport-demo/lib/orchestrator.js";
-import type { DemoOrchestrator } from "../../../services/ai-transport-demo/lib/orchestrator.js";
+import {
+  runDemo,
+  cleanupDemo,
+  type RunDemoHandles,
+  type DemoCommandHost,
+} from "../../../services/ai-transport-demo/lib/run-demo.js";
 
 export default class StreamingDemo extends ControlBaseCommand {
   static override description =
@@ -38,220 +40,26 @@ export default class StreamingDemo extends ControlBaseCommand {
     }),
   };
 
-  private orchestrator: DemoOrchestrator | null = null;
-  private ablyClient: import("ably").Realtime | null = null;
-  private origStdoutWrite: typeof process.stdout.write | null = null;
-  private origStderrWrite: typeof process.stderr.write | null = null;
-  private unhandledHandler: ((error: Error) => void) | null = null;
+  private handles: RunDemoHandles = {
+    orchestrator: null,
+    ablyClient: null,
+    origStdoutWrite: null,
+    origStderrWrite: null,
+    unhandledHandler: null,
+  };
 
   async run(): Promise<void> {
     const { flags } = await this.parse(StreamingDemo);
-
-    if (flags.endpoint && flags.role !== "client") {
-      this.fail(
-        "--endpoint can only be used with --role client",
-        flags,
-        "aiTransportDemo",
-      );
-    }
-
-    if (flags["auth-endpoint"] && flags.role !== "client") {
-      this.fail(
-        "--auth-endpoint can only be used with --role client",
-        flags,
-        "aiTransportDemo",
-      );
-    }
-
-    const role = (flags.role ?? "both") as "both" | "client" | "server";
-
-    // Channel must include a namespace (colon separator) because AI Transport
-    // requires mutable messages, which is configured per-namespace via rules.
-    // Without a namespace, we can't guide the user to create the right rule.
-    if (flags.channel && !flags.channel.includes(":")) {
-      this.fail(
-        `Channel name must include a namespace (e.g. "my-namespace:${flags.channel}"). ` +
-          `AI Transport requires mutable messages, which is enabled per-namespace via rules. ` +
-          `If you don't have a namespace, omit --channel and the demo will use "ai-demo:" by default.`,
-        flags,
-        "aiTransportDemo",
-      );
-    }
-
-    const channelName =
-      flags.channel ??
-      `ai-demo:streaming-${Math.random().toString(36).slice(2, 6)}`;
-    const clientId =
-      flags["client-id"] ?? `demo-${Math.random().toString(36).slice(2, 8)}`;
-
-    // In test mode, output a marker and return (Ink can't render in tests)
-    if (isTestMode()) {
-      this.log(
-        `AI Transport Streaming Demo (coming soon). ` +
-          `Role: ${role}, Channel: ${channelName}`,
-      );
-      return;
-    }
-
-    // Create Ably client
-    this.ablyClient = await this.createAblyRealtimeClient(flags);
-    if (!this.ablyClient) {
-      this.fail("Failed to create Ably client", flags, "aiTransportDemo");
-    }
-
-    const channel = this.ablyClient.channels.get(channelName);
-
-    // Create the orchestrator (startup is triggered by the App component
-    // after event listeners are attached, so no events are missed)
-    this.orchestrator = createOrchestrator({
-      channel,
-      feature: "streaming",
-      endpoint: flags.endpoint,
-      clientId,
-      onFatalError: () => {
-        // Close the Ably connection to stop the SDK retrying
-        if (this.ablyClient) {
-          this.ablyClient.close();
-          this.ablyClient = null;
-        }
-      },
-    });
-
-    // The AIT SDK encoder floods stderr/stdout with NACK errors and
-    // PromiseRejectionHandledWarnings when mutableMessages is not enabled.
-    // The SDK's logger captures console.log/warn at module load time in
-    // closures, so overriding console.* doesn't work. We must intercept
-    // at the process.stdout/stderr.write level.
-    const orchestratorRef = this.orchestrator;
-    let mutableErrorDetected = false;
-
-    // 1. Catch uncaught exceptions from the SDK's WebSocket handler
-    const unhandledHandler = (error: Error) => {
-      const msg = String(error);
-      if (msg.includes("93002") || msg.includes("mutableMessages")) {
-        if (!mutableErrorDetected) {
-          mutableErrorDetected = true;
-          orchestratorRef?.emit("mutableMessagesRequired");
-        }
-
-        return;
-      }
-
-      if (msg.includes("80017") || msg.includes("Connection closed")) {
-        return;
-      }
-
-      // Route rate limit and other SDK errors to the server log
-      // instead of dumping them to stderr
-      if (msg.includes("Rate limit") || msg.includes("rate limit")) {
-        orchestratorRef?.emit("serverLog", `⚠ Rate limit hit`);
-        return;
-      }
-
-      orchestratorRef?.emit(
-        "serverLog",
-        `⚠ ${msg.slice(0, 80)}`,
-      );
+    const host: DemoCommandHost = {
+      log: (msg) => this.log(msg),
+      fail: (msg, component) => this.fail(msg, flags, component),
+      createAblyRealtimeClient: () => this.createAblyRealtimeClient(flags),
     };
-
-    // 2. Intercept process.stdout.write and process.stderr.write to
-    //    suppress [AblySDK Error] NACK spam and PromiseRejectionHandledWarning.
-    //    This is the only reliable way since the SDK captures console.*
-    //    references at module load time.
-    const origStdoutWrite = process.stdout.write;
-    const origStderrWrite = process.stderr.write;
-    this.origStdoutWrite = origStdoutWrite;
-    this.origStderrWrite = origStderrWrite;
-    this.unhandledHandler = unhandledHandler;
-
-    const isSuppressable = (str: string): boolean =>
-      (mutableErrorDetected &&
-        (str.includes("93002") ||
-          str.includes("mutableMessages") ||
-          str.includes("onNack") ||
-          str.includes("80017") ||
-          str.includes("failQueuedMessages") ||
-          str.includes("PromiseRejectionHandledWarning") ||
-          str.includes("AblySDK Error"))) ||
-      str.includes("Rate limit") ||
-      str.includes("rate limit");
-
-    process.stdout.write = ((chunk: unknown, ...args: unknown[]) => {
-      if (typeof chunk === "string" && isSuppressable(chunk)) return true;
-      return origStdoutWrite.apply(process.stdout, [chunk, ...args] as never);
-    }) as typeof process.stdout.write;
-
-    process.stderr.write = ((chunk: unknown, ...args: unknown[]) => {
-      if (typeof chunk === "string" && isSuppressable(chunk)) return true;
-      return origStderrWrite.apply(process.stderr, [chunk, ...args] as never);
-    }) as typeof process.stderr.write;
-
-    process.on("uncaughtException", unhandledHandler);
-
-    // Bypass Ink's CI detection (CI_* env vars trigger is-in-ci)
-    const prevCi = process.env.CI;
-    process.env.CI = "0";
-
-    try {
-      const { render } = await import("ink");
-      const { App } = await import(
-        "../../../services/ai-transport-demo/ui/App.js"
-      );
-
-      const { waitUntilExit } = render(
-        React.createElement(App, {
-          role,
-          feature: "streaming",
-          channelName,
-          orchestrator: this.orchestrator,
-        }),
-      );
-
-      await waitUntilExit();
-    } finally {
-      // Only restore CI env here — stdout/stderr interceptors are restored
-      // in the class finally() after Ably client is fully closed
-      if (prevCi === undefined) {
-        delete process.env.CI;
-      } else {
-        process.env.CI = prevCi;
-      }
-    }
+    await runDemo(host, { feature: "streaming", flags }, this.handles);
   }
 
   async finally(error: Error | undefined): Promise<void> {
-    // Close orchestrator and Ably client while interceptors are still active
-    // so any SDK cleanup output is suppressed
-    if (this.orchestrator) {
-      await this.orchestrator.close();
-      this.orchestrator = null;
-    }
-
-    if (this.ablyClient) {
-      this.ablyClient.close();
-      this.ablyClient = null;
-    }
-
-    // Small delay to let any final SDK async cleanup complete while
-    // interceptors are still active
-    await new Promise((resolve) => setTimeout(resolve, 200));
-
-    // Now restore stdout/stderr and uncaughtException handler
-    if (this.origStdoutWrite) {
-      process.stdout.write = this.origStdoutWrite;
-      this.origStdoutWrite = null;
-    }
-
-    if (this.origStderrWrite) {
-      process.stderr.write = this.origStderrWrite;
-      this.origStderrWrite = null;
-    }
-
-    if (this.unhandledHandler) {
-      process.off("uncaughtException", this.unhandledHandler);
-      this.unhandledHandler = null;
-    }
-
+    await cleanupDemo(this.handles);
     await super.finally(error);
   }
 }
diff --git a/src/services/ai-transport-demo/lib/fake-llm.ts b/src/services/ai-transport-demo/lib/fake-llm.ts
index 8771012a0..dec70200a 100644
--- a/src/services/ai-transport-demo/lib/fake-llm.ts
+++ b/src/services/ai-transport-demo/lib/fake-llm.ts
@@ -11,6 +11,7 @@ import {
   shortStreamingResponses,
   longStreamingResponses,
 } from "./responses/streaming.js";
+import { bargeInResponses } from "./responses/barge-in.js";
 
 export interface FakeLLMOptions {
   /** Which demo feature is running (selects response bank). */
@@ -70,7 +71,8 @@ function getResponseBank(feature: string): string[] {
   switch (feature) {
     case "streaming":
       return streamingResponses;
-    // Future features will have their own banks
+    case "barge-in":
+      return bargeInResponses;
     default:
       return streamingResponses;
   }
@@ -80,6 +82,10 @@ function getShortResponseBank(feature: string): string[] {
   switch (feature) {
     case "streaming":
       return shortStreamingResponses;
+    // Barge-in intentionally has no "short" bank — the demo needs long
+    // responses so the user has time to interrupt mid-stream.
+    case "barge-in":
+      return bargeInResponses;
     default:
       return shortStreamingResponses;
   }
@@ -89,6 +95,8 @@ function getLongResponseBank(feature: string): string[] {
   switch (feature) {
     case "streaming":
       return longStreamingResponses;
+    case "barge-in":
+      return bargeInResponses;
     default:
       return longStreamingResponses;
   }
diff --git a/src/services/ai-transport-demo/lib/orchestrator.ts b/src/services/ai-transport-demo/lib/orchestrator.ts
index 871919893..d743bba4e 100644
--- a/src/services/ai-transport-demo/lib/orchestrator.ts
+++ b/src/services/ai-transport-demo/lib/orchestrator.ts
@@ -70,24 +70,30 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
   let activeTurnAbort: AbortController | null = null;
   let streaming = false;
   let activeClientTurnId: string | null = null;
+  const interruptedMessageIds = new Set<string>();
 
   function emitMessages(): void {
     if (!clientTransport) return;
     const msgs = clientTransport.getMessages();
-    // When a turn is active, mark the last assistant message as streaming
-    // so the UI can show the cursor indicator.
-    const withStreamingFlag: Array<DemoMessage & { streaming?: boolean }> =
-      msgs.map((m, i) => {
-        if (
-          activeClientTurnId &&
-          i === msgs.length - 1 &&
-          m.role === "assistant"
-        ) {
-          return { ...m, streaming: true };
-        }
-        return m;
-      });
-    emitter.emit("messages", withStreamingFlag);
+    // Mark the last assistant message as streaming when a turn is in flight
+    // (for the cursor indicator). Mark any message in `interruptedMessageIds`
+    // as interrupted so the UI shows a barge-in indicator.
+    const withFlags: Array<
+      DemoMessage & { streaming?: boolean; interrupted?: boolean }
+    > = msgs.map((m, i) => {
+      const interrupted = interruptedMessageIds.has(m.id);
+      const streaming =
+        !!activeClientTurnId &&
+        i === msgs.length - 1 &&
+        m.role === "assistant" &&
+        !interrupted;
+      return {
+        ...m,
+        ...(streaming ? { streaming: true } : {}),
+        ...(interrupted ? { interrupted: true } : {}),
+      };
+    });
+    emitter.emit("messages", withFlags);
   }
 
   // ── Server side ──
@@ -297,6 +303,36 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
       return;
     }
 
+    // Barge-in: if a turn is already in flight, cancel it before starting
+    // the new one. Capture the currently-streaming assistant message so
+    // the UI can mark it as interrupted once the cancel lands.
+    if (activeClientTurnId) {
+      const interruptingTurnId = activeClientTurnId;
+      const liveMsgs = clientTransport.getMessages();
+      const lastMsg = liveMsgs.at(-1);
+      if (lastMsg && lastMsg.role === "assistant") {
+        interruptedMessageIds.add(lastMsg.id);
+      }
+
+      emitter.emit(
+        "debugLog",
+        `Barging in — cancelling ${interruptingTurnId.slice(0, 8)}…`,
+      );
+      try {
+        await clientTransport.cancel({ own: true });
+      } catch (cancelError: unknown) {
+        emitter.emit(
+          "debugLog",
+          `Cancel failed (continuing anyway): ${String(cancelError)}`,
+        );
+      }
+
+      activeClientTurnId = null;
+      // Push the interrupted state to the UI immediately, before the new
+      // turn starts streaming, so the user sees the transition cleanly.
+      emitMessages();
+    }
+
     emitter.emit("debugLog", `Sending: "${text.slice(0, 40)}..."`);
 
     try {
diff --git a/src/services/ai-transport-demo/lib/responses/barge-in.ts b/src/services/ai-transport-demo/lib/responses/barge-in.ts
new file mode 100644
index 000000000..6939443a8
--- /dev/null
+++ b/src/services/ai-transport-demo/lib/responses/barge-in.ts
@@ -0,0 +1,20 @@
+/**
+ * Response bank for the barge-in demo.
+ *
+ * These responses are intentionally long-winded and self-aware about the
+ * barge-in behaviour — the point of the demo is for the user to interrupt
+ * mid-stream, so the agent invites them to try and explains what happens
+ * under the hood once they do.
+ */
+
+export const bargeInResponses: string[] = [
+  "Here is the thing about barge-in. Right now I am going to keep talking. I am going to keep generating tokens for a long time, and you can sit there and read along, or you can do what this demo actually exists to show you: interrupt me. Type a new message while I am mid-sentence and hit enter. Watch what happens. The response you are reading will stop immediately, get marked as interrupted in the UI, and your new message will start a fresh turn. No waiting for the first response to finish. No wasted tokens on content you no longer want. That is what barge-in means in a production AI application — the ability to change your mind and have the system respect that change instantly, the same way a human conversation lets you interrupt someone without being impolite.",
+
+  "Let me explain what barge-in actually costs you when you do not have it. In a plain HTTP streaming setup, the LLM keeps generating tokens until it hits its stop condition. If you change your mind mid-stream, your only options are to close the connection (which wastes whatever the model already generated and leaves your server in an awkward state) or to buffer the response and discard it client-side (which still costs you the tokens on the provider's bill). Neither is a clean story. The demo you are currently inside shows a different approach: the cancel signal flows through the Ably channel to the server, the server's AbortSignal fires, the LLM stream stops at the source, and the encoder publishes a final message marking this response as aborted. That final message includes the partial content so the UI has a complete record of what was said before the interruption. Try it — interrupt me right now. Type a new message. I will stop, you will see the interrupted marker, and the next turn will start without ceremony.",
+
+  "The pattern here is deliberately designed for real user behaviour. People change their minds. They start asking a question, realise halfway through that they should be asking a different question, and want to pivot. In a text chat with another human that is trivial — the other person just stops reading the old message and reads the new one. But with a streaming AI, every token costs money, every token takes time, and the naive implementation forces the user to wait for a response they no longer care about before sending the new one. Barge-in fixes that. You can interrupt me right now by typing and hitting enter. The cancel propagates through Ably, the server-side abort signal fires, my token generation stops, and the response gets marked with an aborted status that the client renders as interrupted. Your next message is a brand new turn, not a continuation of this one, so the LLM sees a clean conversation state. Try it.",
+
+  "Something important about this demo that is easy to miss: the interrupted response does not disappear. It stays in the conversation history with whatever content made it through before cancellation, marked with an interrupted indicator so it is clear to both the user and any downstream system that this response was cut short. That matters because some applications want to remember what was partially said — for audit, for context continuity, for debugging. The AIT protocol publishes an abort status on the final message of the stream, and the conversation tree holds onto everything up to that point. When you start a new turn by sending a new message, the server sees the full history including the interrupted response and can factor it into the next reply if it wants to. Go ahead and interrupt me now. Type a new message and hit enter. Watch the interrupted marker appear, then watch the new response stream in cleanly.",
+
+  "Think about the voice-assistant case. Someone says 'Hey, what is the weather in London', the assistant starts speaking, and halfway through they say 'Actually, make that Paris'. The assistant needs to stop talking immediately and switch. That is barge-in, and it is one of the hard problems in conversational AI because the full stack has to cooperate — the audio pipeline has to stop playing, the LLM has to stop generating, the session has to remember what happened. AI Transport gives you the session layer for this. The cancel signal flows on the same channel as the tokens, ordering is preserved, and the response tree records the interruption so the next turn has full context. Try it right now. Type something, anything, while I am still streaming. You will see this response stop and your new one take over.",
+];
diff --git a/src/services/ai-transport-demo/lib/run-demo.ts b/src/services/ai-transport-demo/lib/run-demo.ts
new file mode 100644
index 000000000..ac2f5ab90
--- /dev/null
+++ b/src/services/ai-transport-demo/lib/run-demo.ts
@@ -0,0 +1,256 @@
+/**
+ * Shared runner for the ai-transport demo commands.
+ *
+ * Each demo command (streaming, barge-in, cancel) delegates to runDemo()
+ * with its feature name. The runner handles Ably client creation, channel
+ * namespace validation, SDK log suppression, Ink rendering, and cleanup
+ * so the command files stay small and focused on feature metadata.
+ */
+
+import React from "react";
+import type * as Ably from "ably";
+
+import isTestMode from "../../../utils/test-mode.js";
+import { createOrchestrator } from "./orchestrator.js";
+import type { DemoOrchestrator } from "./orchestrator.js";
+
+export interface RunDemoOptions {
+  /** The feature name — picks the response bank and shows in the header. */
+  feature: string;
+  /** Parsed flags from the command. */
+  flags: {
+    role?: string;
+    channel?: string;
+    endpoint?: string;
+    "auth-endpoint"?: string;
+    "client-id"?: string;
+  } & Record<string, unknown>;
+}
+
+/**
+ * Runtime handles that must be cleaned up in the command's finally() block.
+ */
+export interface RunDemoHandles {
+  orchestrator: DemoOrchestrator | null;
+  ablyClient: Ably.Realtime | null;
+  origStdoutWrite: typeof process.stdout.write | null;
+  origStderrWrite: typeof process.stderr.write | null;
+  unhandledHandler: ((error: Error) => void) | null;
+}
+
+/**
+ * Minimal shape of the hosting command class. Using an interface rather
+ * than importing ControlBaseCommand keeps the dependency direction clean
+ * (services should not import from commands/). The typed flags object is
+ * opaque here — the command closes over it when wiring the callbacks.
+ */
+export interface DemoCommandHost {
+  log: (msg: string) => void;
+  fail: (msg: string, component: string) => never;
+  createAblyRealtimeClient: () => Promise<Ably.Realtime | null>;
+}
+
+/**
+ * Run a demo command end-to-end. The caller should hold onto the returned
+ * handles so it can tear them down in its own finally() hook.
+ */
+export async function runDemo(
+  command: DemoCommandHost,
+  options: RunDemoOptions,
+  handles: RunDemoHandles,
+): Promise<void> {
+  const { feature, flags } = options;
+
+  if (flags.endpoint && flags.role !== "client") {
+    command.fail(
+      "--endpoint can only be used with --role client",
+      "aiTransportDemo",
+    );
+  }
+
+  if (flags["auth-endpoint"] && flags.role !== "client") {
+    command.fail(
+      "--auth-endpoint can only be used with --role client",
+      "aiTransportDemo",
+    );
+  }
+
+  const role = (flags.role ?? "both") as "both" | "client" | "server";
+
+  // Channel must include a namespace (colon separator) because AI Transport
+  // requires mutable messages, which is configured per-namespace via rules.
+  if (flags.channel && !flags.channel.includes(":")) {
+    command.fail(
+      `Channel name must include a namespace (e.g. "my-namespace:${flags.channel}"). ` +
+        `AI Transport requires mutable messages, which is enabled per-namespace via rules. ` +
+        `If you don't have a namespace, omit --channel and the demo will use "ai-demo:" by default.`,
+      "aiTransportDemo",
+    );
+  }
+
+  const channelName =
+    flags.channel ??
+    `ai-demo:${feature}-${Math.random().toString(36).slice(2, 6)}`;
+  const clientId =
+    flags["client-id"] ?? `demo-${Math.random().toString(36).slice(2, 8)}`;
+
+  // In test mode, output a marker and return (Ink can't render in tests)
+  if (isTestMode()) {
+    command.log(
+      `AI Transport ${formatFeatureName(feature)} Demo (coming soon). ` +
+        `Role: ${role}, Channel: ${channelName}`,
+    );
+    return;
+  }
+
+  // Create Ably client
+  handles.ablyClient = await command.createAblyRealtimeClient();
+  if (!handles.ablyClient) {
+    command.fail("Failed to create Ably client", "aiTransportDemo");
+  }
+
+  const channel = handles.ablyClient.channels.get(channelName);
+
+  // Create the orchestrator (startup is triggered by the App component
+  // after event listeners are attached, so no events are missed)
+  handles.orchestrator = createOrchestrator({
+    channel,
+    feature,
+    endpoint: flags.endpoint,
+    clientId,
+    onFatalError: () => {
+      if (handles.ablyClient) {
+        handles.ablyClient.close();
+        handles.ablyClient = null;
+      }
+    },
+  });
+
+  // The AIT SDK encoder floods stderr/stdout with NACK errors when
+  // mutableMessages is not enabled. Its logger captures console.* at
+  // module load, so we must intercept at process.stdout/stderr.write.
+  const orchestratorRef = handles.orchestrator;
+  let mutableErrorDetected = false;
+
+  const unhandledHandler = (error: Error): void => {
+    const msg = String(error);
+    if (msg.includes("93002") || msg.includes("mutableMessages")) {
+      if (!mutableErrorDetected) {
+        mutableErrorDetected = true;
+        orchestratorRef?.emit("mutableMessagesRequired");
+      }
+
+      return;
+    }
+
+    if (msg.includes("80017") || msg.includes("Connection closed")) {
+      return;
+    }
+
+    if (msg.includes("Rate limit") || msg.includes("rate limit")) {
+      orchestratorRef?.emit("serverLog", `⚠ Rate limit hit`);
+      return;
+    }
+
+    orchestratorRef?.emit("serverLog", `⚠ ${msg.slice(0, 80)}`);
+  };
+
+  const origStdoutWrite = process.stdout.write;
+  const origStderrWrite = process.stderr.write;
+  handles.origStdoutWrite = origStdoutWrite;
+  handles.origStderrWrite = origStderrWrite;
+  handles.unhandledHandler = unhandledHandler;
+
+  const isSuppressable = (str: string): boolean =>
+    (mutableErrorDetected &&
+      (str.includes("93002") ||
+        str.includes("mutableMessages") ||
+        str.includes("onNack") ||
+        str.includes("80017") ||
+        str.includes("failQueuedMessages") ||
+        str.includes("PromiseRejectionHandledWarning") ||
+        str.includes("AblySDK Error"))) ||
+    str.includes("Rate limit") ||
+    str.includes("rate limit");
+
+  process.stdout.write = ((chunk: unknown, ...args: unknown[]) => {
+    if (typeof chunk === "string" && isSuppressable(chunk)) return true;
+    return origStdoutWrite.apply(process.stdout, [chunk, ...args] as never);
+  }) as typeof process.stdout.write;
+
+  process.stderr.write = ((chunk: unknown, ...args: unknown[]) => {
+    if (typeof chunk === "string" && isSuppressable(chunk)) return true;
+    return origStderrWrite.apply(process.stderr, [chunk, ...args] as never);
+  }) as typeof process.stderr.write;
+
+  process.on("uncaughtException", unhandledHandler);
+
+  // Bypass Ink's CI detection (CI_* env vars trigger is-in-ci)
+  const prevCi = process.env.CI;
+  process.env.CI = "0";
+
+  try {
+    const { render } = await import("ink");
+    const { App } = await import("../ui/App.js");
+
+    const { waitUntilExit } = render(
+      React.createElement(App, {
+        role,
+        feature,
+        channelName,
+        orchestrator: handles.orchestrator,
+      }),
+    );
+
+    await waitUntilExit();
+  } finally {
+    if (prevCi === undefined) {
+      delete process.env.CI;
+    } else {
+      process.env.CI = prevCi;
+    }
+  }
+}
+
+/**
+ * Tear down the runtime handles. Call from the command's finally() hook
+ * so any SDK cleanup output stays suppressed until the Ably client is
+ * fully closed.
+ */
+export async function cleanupDemo(handles: RunDemoHandles): Promise<void> {
+  if (handles.orchestrator) {
+    await handles.orchestrator.close();
+    handles.orchestrator = null;
+  }
+
+  if (handles.ablyClient) {
+    handles.ablyClient.close();
+    handles.ablyClient = null;
+  }
+
+  // Small delay to let any final SDK async cleanup complete while
+  // interceptors are still active
+  await new Promise((resolve) => setTimeout(resolve, 200));
+
+  if (handles.origStdoutWrite) {
+    process.stdout.write = handles.origStdoutWrite;
+    handles.origStdoutWrite = null;
+  }
+
+  if (handles.origStderrWrite) {
+    process.stderr.write = handles.origStderrWrite;
+    handles.origStderrWrite = null;
+  }
+
+  if (handles.unhandledHandler) {
+    process.off("uncaughtException", handles.unhandledHandler);
+    handles.unhandledHandler = null;
+  }
+}
+
+export function formatFeatureName(feature: string): string {
+  return feature
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
diff --git a/src/services/ai-transport-demo/ui/hooks/use-demo.ts b/src/services/ai-transport-demo/ui/hooks/use-demo.ts
index a1fa0e850..018365fc1 100644
--- a/src/services/ai-transport-demo/ui/hooks/use-demo.ts
+++ b/src/services/ai-transport-demo/ui/hooks/use-demo.ts
@@ -50,15 +50,20 @@ export function useDemo(orchestrator: DemoOrchestrator | null): UseDemoResult {
     };
 
     // The orchestrator emits the full message list from the AIT client
-    // transport. Progressive streaming updates include an optional `streaming`
-    // flag on the in-progress assistant message for the cursor indicator.
-    const onMessages = (msgs: Array<DemoMessage & { streaming?: boolean }>) => {
+    // transport. Streaming updates include a `streaming` flag on the
+    // in-progress assistant message (cursor indicator); barge-in marks
+    // the interrupted message with `interrupted` so the UI can show a
+    // visual cue that the response was cut short.
+    const onMessages = (
+      msgs: Array<DemoMessage & { streaming?: boolean; interrupted?: boolean }>,
+    ) => {
       setMessages(
         msgs.map((m) => ({
           id: m.id,
           role: m.role,
           content: m.content,
           streaming: m.streaming,
+          interrupted: m.interrupted,
         })),
       );
     };

From 24ba7e9019e02921eeb21bdae09fbb457ed3c8e1 Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Tue, 21 Apr 2026 23:56:58 +0200
Subject: [PATCH 16/17] fix(ai-transport): stop fake-LLM at the source on
 barge-in cancel

The barge-in demo published cancel on the client side and the SDK
aborted the server's turn, but fake-LLM kept pumping tokens: I was
passing my own locally-created AbortController.signal into the
generator, which the SDK has no way to reach. The result was two
turns appearing to stream in parallel on the server log after a
barge-in (the newer one plus the supposedly-cancelled first one).

Use turn.abortSignal (exposed as a getter by the AIT SDK's Turn)
directly. When the server transport receives a matching cancel
event on the channel, it fires that signal, which our fake-LLM
already respects. The duplicate activeTurnAbort state is now
unnecessary and has been removed. cancelActiveTurn() likewise
just publishes clientTransport.cancel({own: true}) and lets the
signal flow back.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../ai-transport-demo/lib/orchestrator.ts     | 26 +++++++------------
 1 file changed, 10 insertions(+), 16 deletions(-)

diff --git a/src/services/ai-transport-demo/lib/orchestrator.ts b/src/services/ai-transport-demo/lib/orchestrator.ts
index d743bba4e..e8151028a 100644
--- a/src/services/ai-transport-demo/lib/orchestrator.ts
+++ b/src/services/ai-transport-demo/lib/orchestrator.ts
@@ -67,7 +67,6 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
   let serverTransport: ServerTransport<FakeLLMEvent, DemoMessage> | null = null;
   let clientTransport: ClientTransport<FakeLLMEvent, DemoMessage> | null = null;
   let serverEndpoint: string | null = explicitEndpoint ?? null;
-  let activeTurnAbort: AbortController | null = null;
   let streaming = false;
   let activeClientTurnId: string | null = null;
   const interruptedMessageIds = new Set<string>();
@@ -130,8 +129,6 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
       body.messages?.[0]?.message?.content ?? "(empty message)";
     const turnId = body.turnId;
 
-    const abortController = new AbortController();
-    activeTurnAbort = abortController;
     streaming = true;
 
     const shortTurnId = turnId.slice(0, 8);
@@ -164,12 +161,16 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
       }
 
       // Stream fake LLM response through the encoder, counting tokens so
-      // we can surface periodic progress updates on the server log.
+      // we can surface periodic progress updates on the server log. The
+      // turn's abortSignal fires when the SDK receives a matching cancel
+      // event on the channel — wiring it straight into fake-llm stops
+      // token generation at the source on barge-in, rather than leaving
+      // the generator pumping into a dead pipe.
       let tokenCount = 0;
       const llmStream = createFakeLLMStream({
         feature,
         userMessage,
-        signal: abortController.signal,
+        signal: turn.abortSignal,
       });
       const progressStream = new TransformStream<FakeLLMEvent, FakeLLMEvent>({
         transform(event, controller) {
@@ -239,7 +240,6 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
       );
     } finally {
       streaming = false;
-      activeTurnAbort = null;
       emitter.emit("serverStatus", null);
     }
   }
@@ -368,24 +368,18 @@ export function createOrchestrator(options: OrchestratorOptions): DemoOrchestrat
   };
 
   emitter.cancelActiveTurn = async () => {
-    if (activeTurnAbort) {
-      activeTurnAbort.abort();
-      emitter.emit("debugLog", "Cancel signal sent (server-side)");
-    }
-
+    // Publishing the cancel from the client side is enough — the server
+    // subscribes to cancel events on the channel, aborts the turn, and
+    // fake-llm stops via the turn.abortSignal it was handed.
     if (clientTransport) {
       await clientTransport.cancel({ own: true });
-      emitter.emit("debugLog", "Cancel signal sent (client-side)");
+      emitter.emit("debugLog", "Cancel signal sent");
     }
   };
 
   emitter.isStreaming = () => streaming;
 
   emitter.close = async () => {
-    if (activeTurnAbort) {
-      activeTurnAbort.abort();
-    }
-
     if (clientTransport) {
       try {
         await clientTransport.close();

From 4227b19d9a43abcce3750b24c138c8e4fd0c52aa Mon Sep 17 00:00:00 2001
From: Matthew O'Riordan <matthew.oriordan@gmail.com>
Date: Wed, 22 Apr 2026 00:03:40 +0200
Subject: [PATCH 17/17] fix(ai-transport): align demo clientId with Ably
 connection for cancel matching
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Barge-in cancels were silently no-ops: the Ably connection's clientId
defaults to 'ably-cli-XYZ' (set by ControlBaseCommand.setClientId), but
the orchestrator's clientId was a separate 'demo-XYZ' fallback. When
the client published cancel({own: true}), the server transport's filter
compared the cancel message's publisher clientId (the connection
clientId) against the turn's registered clientId (the demo clientId)
and found no matches — so no turns were aborted, the turn's abortSignal
never fired, fake-LLM kept generating, and streamResponse never
returned. The server log showed both turns' lifecycle events but
turn:end never appeared for the first turn.

Prefer the Ably connection's clientId when constructing the demo
clientId. Fall back to --client-id flag or the random demo-XYZ only
when the connection has no clientId set (e.g. `--client-id none`).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/services/ai-transport-demo/lib/run-demo.ts | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/src/services/ai-transport-demo/lib/run-demo.ts b/src/services/ai-transport-demo/lib/run-demo.ts
index ac2f5ab90..2f6a1de56 100644
--- a/src/services/ai-transport-demo/lib/run-demo.ts
+++ b/src/services/ai-transport-demo/lib/run-demo.ts
@@ -91,8 +91,6 @@ export async function runDemo(
   const channelName =
     flags.channel ??
     `ai-demo:${feature}-${Math.random().toString(36).slice(2, 6)}`;
-  const clientId =
-    flags["client-id"] ?? `demo-${Math.random().toString(36).slice(2, 8)}`;
 
   // In test mode, output a marker and return (Ink can't render in tests)
   if (isTestMode()) {
@@ -109,6 +107,17 @@ export async function runDemo(
     command.fail("Failed to create Ably client", "aiTransportDemo");
   }
 
+  // CRITICAL: the demo's clientId must match the Ably connection's clientId,
+  // otherwise the server transport's cancel({own: true}) filter cannot match
+  // turns. The filter compares the cancel publisher's connection clientId
+  // against the clientId the turn was registered with. If they differ —
+  // e.g. Ably connection uses `ably-cli-XYZ` (base command default) while
+  // the demo uses `demo-XYZ` — no turns match and cancel is silently a no-op.
+  const clientId =
+    handles.ablyClient.auth.clientId ??
+    flags["client-id"] ??
+    `demo-${Math.random().toString(36).slice(2, 8)}`;
+
   const channel = handles.ablyClient.channels.get(channelName);
 
   // Create the orchestrator (startup is triggered by the App component