feat(toolkit-lib): `withListeners` API for IoHost by sai-ray · Pull Request #1708 · aws/aws-cdk-cli

sai-ray · 2026-07-07T14:03:14Z

The CLI's CliIoHost has a listener mechanism that's private and welded to that one class. Programmatic toolkit-lib users have no way to observe or reshape what flows through their IoHost short of writing a whole custom host.

This PR extracts that engine into a shared ListenerRegistry and adds a public withListeners(host) wrapper, so listeners can be attached to any IIoHost:

 const host = withListeners(new NonInteractiveIoHost());
 host.on('CDK_TOOLKIT_I2901', (m) => { count += (m.data as StackDetailsPayload).stacks.length; });  // observe
 host.on((m) => m.level === 'warn', (m) => { warnings++; });                                        // or by predicate
 const toolkit = new Toolkit({ ioHost: host });

A listener can observe a message (on/once), rewrite its text (rewrite/rewriteOnce), suppress it, or answer a prompt (respond/respondOnce), and each registration returns a disposer. CliIoHost is refactored to delegate to the same ListenerRegistry, so there's one implementation of matching/ordering/rewriting/request-answering instead of two.

The additions users interact with:

withListeners(host) and its return type IoHostWithListeners.
IMessageMatcher and IRequestMatcher pass one to key a listener by message and get a typed msg.data.
MessagePredicate for matching on anything other than a single code.
RespondOptions for respond/respondOnce.
MessageListenerResult, MessageListenerResultOrPromise

Listeners are keyed on a message code string (IoMessageCode, e.g. 'CDK_TOOLKIT_I2901'), a MessagePredicate or a IMessageMatcher. With a code or predicate msg.data is unknown and you cast it to the interface documented in the message registry. With a matcher, msg.data is typed.

Because CliIoHost now shares the extracted engine, one thing changes on the CLI path, intended: a once listener is removed before it is awaited, so concurrent emissions (e.g. parallel stacks) can no longer double-fire it.

Checklist

This change contains a major version upgrade for a dependency and I confirm all breaking changes are addressed
- Release notes for the new version:

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

codecov-commenter · 2026-07-07T15:05:31Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.41%. Comparing base (9bf08e5) to head (ae73a7d).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1708      +/-   ##
==========================================
- Coverage   89.59%   89.41%   -0.18%     
==========================================
  Files          77       77              
  Lines       11758    11552     -206     
  Branches     1651     1624      -27     
==========================================
- Hits        10534    10329     -205     
  Misses       1195     1195              
+ Partials       29       28       -1

Flag	Coverage Δ
suite.unit	`89.41% <100.00%> (-0.18%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-07-07T17:18:52Z

Total lines changed 1101 is greater than 1000. Please consider breaking this PR down.

mrgrain · 2026-07-08T11:39:55Z

+ */
+export type MessageSelector<T> =
+  | IoMessageMaker<T>
+  | IoRequestMaker<T, any>


These are not public types, nor should they be. We can accept string here (a single code) or a new MessageMatcher class (via IMessageMatcher). We can make the MessageMakers implement that interface so we can keep passing them in.

Went with the string option. The public selector is now IoMessageCode (a single code) or a (msg) => boolean predicate, so it no longer references the maker types. I tried the IMessageMatcher route first but dropped it. To keep the typed maker path it wanted, IO would have to be public, and exporting IO pulls the maker internal types back onto the public surface through the same forgotten export cascade with api extractor. With IO private there's also no way for an external caller to obtain an IMessageMatcher. CliIoHost keeps passing makers internally through the private registry unchanged.

yes there is, the CLI is a privileged caller that can use private exports from toolkit-lib.

In either case I don't understand why it's not possible. Can you share the IMessageMatcher interface you attempted?

Sorry, my earlier statement was off. I got there by trying to give public users a typed msg.data without a cast, and I talked myself into thinking that needed IO to be public. It doesn't. A public matcher interface is fine on its own, and only exporting IO itself would leak the maker types. Here's the interface, it's on the branch:

export interface IMessageMatcher<T> { is(msg: IoMessage<unknown>): msg is IoMessage<T>; } export interface IRequestMatcher<T, U> extends IMessageMatcher<T> { is(msg: IoMessage<unknown>): msg is IoRequest<T, U>; }

The makers implement it so internally the CLI keeps passing them and gets typed data and the maker types stay private.

But the typing goal I was chasing doesn't actually resolve. Internally the CLI can use the matcher because it has the makers. A public user has no matcher to pass, since IO and the makers are private. To get one they'd either need us to export IO, or hand-write the matcher:

host.on({ is: (m): m is IoMessage<StackDetailsPayload> => m.code === 'CDK_TOOLKIT_I2901' }, (m) => m.data.stacks);

But that m is IoMessage<StackDetailsPayload> doesn't give much over just casting on the code path:

host.on('CDK_TOOLKIT_I2901', (m) => (m.data as StackDetailsPayload).stacks);

So the typed matcher only seems to pay off for the CLI. For public users it's a similar cast. Given that, does it earn a place on the public surface, or should the matcher be internal and leave the public API as IoMessageCode | MessagePredicate?

mrgrain · 2026-07-10T13:44:12Z

+ */
+export type MessageSelector<T> =
+  | IoMessageMaker<T>
+  | IoRequestMaker<T, any>


yes there is, the CLI is a privileged caller that can use private exports from toolkit-lib.

In either case I don't understand why it's not possible. Can you share the IMessageMatcher interface you attempted?

mrgrain · 2026-07-10T13:45:21Z

+   * ```
+   */
+  rewrite(
+    code: IoMessageCode,


why no predicate?

added. missed it earlier.

mrgrain · 2026-07-10T13:46:36Z

+   * const dispose = host.respond('CDK_TOOLKIT_I7010', true);
+   * ```
+   */
+  respond(code: IoMessageCode, value: unknown, suppressQuestion?: boolean): () => void;


I know is copied from what we currently have, but for a public API we need to think more careful about the design. If we ever want to add an other option this gets messy. We can preemptively put suppressQuestion in a property bag (options).

Updated. It's a RespondOptions object now, so we can add more options later without changing the signature.

mrgrain · 2026-07-10T13:46:55Z

+export function withListeners(host: IIoHost): IoHostWithListeners {
+  return new ListeningIoHost(host);
+}


Not sure I love this, but I guess it doesn't hurt either. 🤷🏻

mrgrain · 2026-07-10T13:48:16Z

+ * codes are listed in the message registry:
+ * https://docs.aws.amazon.com/cdk/api/toolkit-lib/message-registry/
+ */
+export interface IoHostWithListeners extends IIoHost {


do we need to extend the IIoHost interface? Or is IoEmitter a separate independent interface?

I held off IoEmitter because I wasn't sure of the benefit over the wrapper for our cases. The one place it would help is reusing one emitter across many hosts. If that is a expected case, then this would be small addition.

mrgrain · 2026-07-10T13:49:32Z

+ * const toolkit = new Toolkit({ ioHost: host });
+ * ```
+ */
+export function withListeners(host: IIoHost): IoHostWithListeners {


We have this, we can at least make this a generic type so that the inner host keeps its higher fidelity.

I dug into this and I'm not sure I found the right answer, so I'd value your read.

The generic form that keeps the host's full type is withListeners<T>(host: T): T & IoHostWithListeners. My worry is that the wrapper only implements notify, requestResponse, and the listener methods, so I think that type would promise the host's other members while they'd actually be undefined at runtime.

I tried two ways to make it honest and neither quite felt right:

A Proxy forwarding unknown members to the inner host. Reads seem fine, and a set trap would probably cover writes, but when I wrapped a host that already has a registry (like CliIoHost) I ended up with two registries both firing on notify, and I couldn't find a trap that resolved it cleanly.

Adding the listener methods straight onto the host and handing it back. That one is genuinely the host, but it changes the object that was passed in, and since the CLI host is a shared singleton I think that would affect everyone.

So for now I've gone back to returning IoHostWithListeners. It still extends IIoHost, which is all the toolkit consumes, and the caller still holds their own typed reference to the host they passed in, so it seems like they don't really lose it. If there's an approach you had in mind that avoids these I'd really appreciate the guidance. I couldn't reason one that holds up.

Exactly, I think a proxy is the right solution here!

mrgrain · 2026-07-10T13:51:03Z

+  public on<T>(
+    selector: IoMessageMaker<T> | IoRequestMaker<T, any> | ((msg: IoMessage<any>) => msg is IoMessage<T>),
+    listener: (msg: IoMessage<T>) => MessageListenerResultOrPromise,
+  ): () => void;
+  public on(
+    predicate: (msg: IoMessage<any>) => boolean,
+    listener: (msg: IoMessage<unknown>) => MessageListenerResultOrPromise,
+  ): () => void;
+  public on(selector: MessageSelector<any>, listener: MessageListenerFn): () => void {


since this is a private class, it feels strange to have so many different signatures. But I guess thats because we couldn't make IIoMessageMatcher yet.

yes, and now the selector went from two maker arms plus a predicate down to a matcher or a predicate.

But we now have IIoMessageMatcher!

mrgrain

Also some changes have been made on main that solve dispose much nicer. We should include them here.

mrgrain · 2026-08-25T13:48:37Z

+ * codes are listed in the message registry:
+ * https://docs.aws.amazon.com/cdk/api/toolkit-lib/message-registry/
+ */
+export interface IoHostWithListeners extends IIoHost {


Technically this needs to be IIoHostWithListeners but like I've said, I don't see why we need a combined interface. IoEmitter might still be the better name even if we extend.

mrgrain · 2026-08-25T13:49:53Z

+
+/**
+ * A message matcher
+ *
+ * Decides whether a message matches a listener, narrowing its payload type `T`.
+ */
+export interface IMessageMatcher<T> {
+  is(msg: IoMessage<unknown>): msg is IoMessage<T>;
+}
+
+/**
+ * A request matcher.
+ *
+ * Carries the response type `U` so an answer can be typed.
+ */
+export interface IRequestMatcher<T, U> extends IMessageMatcher<T> {
+  is(msg: IoMessage<unknown>): msg is IoRequest<T, U>;
+}


Do these Matchers need to be generic? What functionality are we gaining?

mrgrain · 2026-08-25T13:51:52Z

+  on<T>(
+    matcher: IMessageMatcher<T>,
+    listener: (msg: IoMessage<T>) => MessageListenerResultOrPromise,
+  ): () => void;
+  on(
+    selector: IoMessageCode | MessagePredicate,
+    listener: (msg: IoMessage<unknown>) => MessageListenerResultOrPromise,


So we allow 3 different types here. Can we limit this? MessagePredicate and IMessageMatcher seem to be the same thing. Even IoMessageCode we can get rid of if we provide a code matcher.

mrgrain · 2026-08-25T13:55:38Z

+  // The shared listener engine. Registration and message transformation live
+  // here; this host does its own I/O (writing, prompting, telemetry, observers)
+  // around `registry.apply`. See `on`/`once`/`rewrite`/`respond`.
+  private readonly registry = new ListenerRegistry();


What is this registry? If we need it, this tells you that our wrapping pattern doesn't work as designed.

mrgrain · 2026-08-25T13:56:52Z

Please check which types need exporting from here. Also maybe some are duplicated with public types, not sure.

mrgrain · 2026-08-25T13:57:15Z

+  public on<T>(
+    selector: IoMessageMaker<T> | IoRequestMaker<T, any> | ((msg: IoMessage<any>) => msg is IoMessage<T>),
+    listener: (msg: IoMessage<T>) => MessageListenerResultOrPromise,
+  ): () => void;
+  public on(
+    predicate: (msg: IoMessage<any>) => boolean,
+    listener: (msg: IoMessage<unknown>) => MessageListenerResultOrPromise,
+  ): () => void;
+  public on(selector: MessageSelector<any>, listener: MessageListenerFn): () => void {


But we now have IIoMessageMatcher!

mrgrain · 2026-08-25T13:57:49Z

+   * Remove every listener registered via `on`/`once`/`rewrite`/`respond`,
+   * keeping the host's internal listeners so the host keeps working afterwards.
+   */
+  public removeUserListeners(): void {


To be fair, I'd rather get rid of the internal concept completely...

chore: midwork

74815a5

sai-ray temporarily deployed to automation July 7, 2026 14:03 — with GitHub Actions Inactive

aws-cdk-automation requested a review from a team July 7, 2026 14:03

sai-ray temporarily deployed to no-approval July 7, 2026 14:03 — with GitHub Actions Inactive

github-actions Bot added the p2 label Jul 7, 2026

sai-ray changed the title ~~feat(toolkit-lib): public withListeners API for IoHost~~ feat(toolkit-lib): public withListeners API for IoHost Jul 7, 2026

aws-cdk-automation enabled auto-merge July 7, 2026 14:03

sai-ray changed the title ~~feat(toolkit-lib): public withListeners API for IoHost~~ feat(toolkit-lib): withListeners API for IoHost Jul 7, 2026

sai-ray temporarily deployed to run-tests July 7, 2026 14:07 — with GitHub Actions Inactive

sai-ray temporarily deployed to run-tests July 7, 2026 14:58 — with GitHub Actions Inactive

sai-ray added the pr/exempt-size-check Skips PR size check label Jul 7, 2026

chore: keep AbsentData off public API

bca9162

sai-ray temporarily deployed to no-approval July 7, 2026 18:25 — with GitHub Actions Inactive

sai-ray temporarily deployed to run-tests July 7, 2026 18:27 — with GitHub Actions Inactive

mrgrain requested changes Jul 8, 2026

View reviewed changes

sai-ray added 2 commits July 9, 2026 01:12

chore: midwork

f9e68aa

Merge branch 'main' into sai/iohost-public-listener-api

e9a6c1b

mrgrain requested changes Jul 10, 2026

View reviewed changes

sai-ray added 12 commits July 10, 2026 16:58

chore: midwork

b9195c5

chore: midwork

48b3b31

chore: midwork

13bcf0a

chore: midwork

674b076

chore: midwork

cac287d

chore: midwork

6196861

chore: midwork

7917b0a

chore: midwork

51c0d77

chore: midwork

2e8248c

chore: midwork

ae73a7d

Merge branch 'main' into sai/iohost-public-listener-api

a686a1a

Merge branch 'main' into sai/iohost-public-listener-api

b4177e6

mrgrain requested changes Aug 25, 2026

View reviewed changes

Uh oh!

Conversation

sai-ray commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

codecov-commenter commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jul 7, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrgrain left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sai-ray commented Jul 7, 2026 •

edited

Loading

codecov-commenter commented Jul 7, 2026 •

edited

Loading