py-ib-controller 0.0.0__py3-none-any.whl

ibcontroller/data/ibcontroller.toml.example

@@ -0,0 +1,178 @@
+# ibcontroller configuration file -- flat, no [section] headers.
+#
+# Precedence (highest to lowest):
+#   1. Environment variables (override everything)
+#   2. This config file
+#   3. Built-in defaults
+#
+# Credentials are environment-variable-only and must never appear in this file --
+# ibcontroller.config.load_config() refuses to start if it finds one here. They use a
+# single pair regardless of trading_mode below (the mode says which account to
+# authenticate as; it does not select different credential variables):
+#   IBC_USERID     / IBC_PASSWORD
+# Each also accepts a _FILE-suffixed variant (e.g. IBC_PASSWORD_FILE=/run/secrets/pass)
+# that reads the value from a file instead -- Docker/Compose secrets, not the env var itself.
+#
+# A .env file also works, via `ibcontroller run --dotenv <path>` -- it only fills in
+# environment variables that aren't already set (python-dotenv, override=False), so it's a
+# convenience for populating the environment layer above, not a fourth layer of its own.
+#
+# This file is copied here by `ibcontroller init` (or automatically by `ibcontroller run`
+# the first time it's missing) with every key commented out below -- as shipped, it
+# changes nothing versus built-in defaults. Only IBC_USERID/IBC_PASSWORD
+# are actually required to run -- everything else here has a safe default or is
+# auto-detected from the real install.
+#
+# IMPORTANT: this schema is closed. Every key here must already be a real field in
+# ibcontroller/config.py -- an unknown key is rejected at startup (a clean error
+# message + non-zero exit, not silently ignored, not a crash-with-traceback). You
+# cannot add a new TWS/Gateway-settings toggle by just adding a key here; that
+# always needs a config.py code change first (a new Config field), plus adding it
+# to settings.py's own allow-list if it's meant to drive a declarative setting via
+# "value_from_config" -- see ibkr_settings.toml.example.
+
+# Socket/instance name (env: IBC_INSTANCE). Optional: when unset,
+# defaults to "{program}-{trading_mode}" (e.g. "gateway-paper").
+# instance = "dev"
+
+# "gateway" or "tws" (env: IBC_PROGRAM)
+# Default "gateway"
+# program = "gateway"
+
+# Installed TWS/Gateway version, e.g. "10.50" (env: IBC_TWS_VERSION). Omit this
+# key (the default) to auto-detect it from tws_path -- if more than one version is
+# installed, the greatest is picked (optionally narrowed by tws_channel below); set this
+# explicitly to pin one instead.
+# tws_version = "10.50"
+
+# Which update channel to prefer when auto-detecting tws_version -- "stable" or "latest"
+# (env: IBC_TWS_CHANNEL), as labeled by the install itself
+# (.install4j/i4jparams.conf). Ignored when tws_version is set explicitly.
+# Default "stable"
+# tws_channel = "stable"
+
+# Override the install path launcher.py would otherwise infer (env: IBC_TWS_PATH)
+# tws_path = "~/Jts"
+# tws_path = ""
+
+# Where TWS/Gateway itself stores its settings, deliberately NOT the same as tws_path
+# (the install location). None defaults, {instance}={program}-{trading_mode}
+# ie, ~/Jts/gateway-live
+# tws_settings_path =
+
+# TWS/Gateway is "live" or "paper" -- defaults to "paper" (the safe, non-monetary mode)
+# when unset (env: IBC_TRADING_MODE)
+# Default "paper"
+# trading_mode = "paper"
+
+# Which ibkr_settings.toml to apply at startup (settings.py's own
+# apply_settings_from_file) -- see ibkr_settings.toml.example. Omit this key (the
+# default) to apply nothing declaratively.
+# (env: IBC_SETTINGS_FILE)
+# settings_file = "~/.config/ibkr_settings.toml"
+
+# Where ibcontroller's own log and trace files live (env: IBC_LOG_DIR).
+# Optional: when unset, defaults to the platformdirs user-log dir (or
+# $IBC_APP_DIR/log in docker mode). Every instance's files (log, trace,
+# gateway stdout) land flat in this one directory.
+# log_dir = "~/.local/share/ibcontroller"
+# log_dir = ""
+
+# Where ibcontroller's own log and Gateway/TWS's own console output go: "std"
+# (console only) or "file" (only, under log_dir) -- exclusive, not both. Doesn't
+# affect the wire trace above, which stays file-only regardless of this setting.
+# (env: IBC_LOG_SINK)
+# Default "std"
+# log_sink = "std"
+
+# Diagnostics -- off by default. When enabled, logs a component structure dump
+# (the same primitive settings.py/recognisers.py use to find controls) for each
+# matching window event, to ibcontroller-{instance}.log at INFO. Built-in
+# replacement for poking the agent socket directly with socat/nc.
+# diagnostic_scope: which windows qualify -- "known" (recognised by a built-in or
+# declarative recogniser), "unknown", or "all" (env: IBC_DIAGNOSTIC_SCOPE)
+# Default "known"
+# diagnostic_scope = "known"
+# diagnostic_when: which events trigger a dump -- "open", "openclose", or "never"
+# (off) (env: IBC_DIAGNOSTIC_WHEN)
+# Default "never"
+# diagnostic_when = "open"
+
+# IBC: ReadOnlyLogin -- TWS only (IBC disables it on Gateway); NOT YET WIRED to any real
+# behavior in ibcontroller (loaded, but nothing acts on it yet -- see TODO.md).
+# Default false
+# read_only_login = false
+
+# IBC: ReadOnlyApi -- true/false sets it
+# (env: IBC_READ_ONLY_API)
+# Default "false"
+# read_only_api = false
+
+# IBC: ExistingSessionDetectedAction -- how ibcontroller itself reacts to Gateway's
+# "existing session detected" dialog: manual/primary/primaryoverride/secondary
+# (env: IBC_EXISTING_SESSION_ACTION)
+# Default "manual"
+# existing_session_action = "manual"
+
+# IBC: AcceptIncomingConnectionAction -- how ibcontroller reacts to TWS/Gateway's
+# "Accept incoming connection" dialog, shown when an API client connects.
+# If set to 'accept', ibcontroller automatically accepts incoming API connection
+# dialogs. If set to 'reject', ibcontroller automatically rejects incoming API
+# connection dialogs. If set to 'manual', the user must decide whether to accept
+# or reject incoming API connection dialogs. The default is 'manual'.
+# (env: IBC_ACCEPT_INCOMING_CONNECTIONS)
+# accept_incoming_connections = "manual"
+
+# --- Login/2FA timeout and retry settings -- ibcontroller's own policy, not written to
+# --- Gateway/TWS itself (though mfa_timeout mirrors IBKR's
+# --- real external 2FA window).
+# IBC: LoginDialogDisplayTimeout, default 60
+# login_dialog_display_timeout = 60.0
+# IBC: SecondFactorAuthenticationTimeout, default 180
+# mfa_timeout = 180.0
+# IBC: ReloginAfterSecondFactorAuthenticationTimeout, default false
+# relogin_after_mfa_timeout = false
+# IBC: SecondFactorAuthenticationExitInterval, default 60
+# mfa_exit_interval = 60.0
+
+# IBC: AutoRestartTime -- same name, same "hh:mm AM/PM" format (e.g. "08:00 AM"), a
+# single space between the two parts. Drives settings.py's "auto_restart_time" action
+# (see ibkr_settings.toml.example) -- omit this key (the default) to leave Gateway's
+# existing Auto Restart setting unchanged (env: IBC_AUTO_RESTART_TIME)
+# Default None - not set
+# auto_restart_time = "08:00 AM"
+
+# IBC: AutoLogoffTime -- same "hh:mm AM/PM" format, same Lock and Exit control as
+# auto_restart_time above (a shared radio-button pair: "Auto restart"/"Auto logoff").
+# If you set BOTH keys, auto_restart_time wins (builtin_settings.toml applies it
+# last, matching IBC's own precedence) -- set only one of the two in practice.
+# Omit this key (the default) to leave the existing setting unchanged
+# (env: IBC_AUTO_LOGOFF_TIME)
+# Default None - not set
+# auto_logoff_time = "08:00 AM"
+
+# --- Applies to TWS and Gateway alike (ported from IBC's IbcTws.java, the shared
+# --- base class both programs use). Both are ibcontroller's own scheduled actions,
+# --- not GUI settings written to TWS/Gateway -- see control_loop.py. If both are
+# --- set, whichever occurs first wins.
+# IBC: ColdRestartTime -- "HH:MM", 24-hour, local time. Every Sunday at this time,
+# ibcontroller closes the instance tidily and relaunches with a full fresh login
+# (via ibcontroller's own launch_instance, not IBC's native-launcher File > Restart),
+# forcing the weekly reauth IBKR requires around Sunday 01:00 US/Eastern token
+# invalidation (env: IBC_COLD_RESTART_TIME)
+# Default None - not set
+# cold_restart_time = "07:05"
+
+# IBC: ClosedownAt -- "HH:MM" (every day) or "<Weekday> HH:MM" (one day a week,
+# Weekday a full English name, Monday..Sunday). At this time, ibcontroller closes
+# the instance tidily with no relaunch -- you're responsible for restarting it
+# yourself (env: IBC_CLOSEDOWN_AT)
+# Default None - not set
+# closedown_at = "22:00"
+# closedown_at = "Friday 22:00"
+
+# JVM heap for TWS/Gateway at launch, e.g. "1024m"/"4g". Overrides the -Xmx
+# line in the installed .vmoptions file (ibgateway.vmoptions/tws.vmoptions);
+# bare size, no -Xmx prefix (env: IBC_JAVA_HEAP_SIZE)
+# Default None - leave the installed file's value untouched
+# java_heap_size = "2g"

ibcontroller/data/ibkr_settings.toml.example

@@ -0,0 +1,135 @@
+# Example ibkr_settings.toml -- declarative Gateway/TWS Global Configuration settings,
+# applied once at instance startup by settings.py's apply_settings_from_file, layered
+# on top of the bundled built-in entries (data/builtin_settings.toml -- read_only_api/
+# auto_restart_time, applied from ibcontroller.toml/env alone, no file needed).
+#
+#
+# --- Overriding a built-in entry ------------------------------------------------------
+# If a future TWS/Gateway release moves a built-in control (a different tree_path or
+# label), add an entry here with the SAME value_from_config as the built-in you're
+# replacing -- settings.py's merge rule matches on that field and uses your entry
+# instead of the bundled one, rather than applying both. Example (commented out --
+# read_only_api's real navigation hasn't actually changed; this just shows the shape):
+#
+# [[settings]]
+# tree_path = "API/Settings/Read-Only"    # a hypothetical new location
+# action = "toggle"
+# label = "Read-Only API Access"          # a hypothetical new label
+# value_from_config = "read_only_api"     # same key as the built-in -- this replaces it
+#
+# Each [[settings]] entry:
+#   tree_path         -- Global Configuration's own JTree path, e.g. "API/Settings"
+#   action             -- "toggle" (a checkbox/radio), "type_text", "type_text_near_label"
+#                          (a field with no accessible name, found by position -- see
+#                          field_index below), or "auto_restart_time" (a composite
+#                          action, see its own section below -- takes no label/label_ref
+#                          at all).
+#   label / label_ref   -- the widget's accessible label, either literal ("label") or a
+#                          name resolved through labels.json's settings.controls map
+#                          ("label_ref") -- use label_ref for anything already named
+#                          there (version-proofed against IBKR renaming it), label for
+#                          anything not worth naming yet. Not used by "auto_restart_time".
+#   value / value_from_config -- the wanted value, either literal ("value") or an
+#                          attribute name looked up on the already-loaded Config at
+#                          apply time ("value_from_config") -- this is how
+#                          Config.read_only_api flows down to the real Gateway
+#                          setting without a second, redundant declaration. A value
+#                          that resolves to None (either source) skips the entry
+#                          entirely -- "leave unchanged", matching IBC's own "" ==
+#                          leave-unchanged semantics.
+#
+#                          IMPORTANT: value_from_config only works for the fixed,
+#                          closed set of Config fields settings.py already knows about
+#                          (today: read_only_api, auto_restart_time) -- the override
+#                          case above is the only reason to use it here. Config's own
+#                          schema is closed (an unknown key in ibcontroller.toml itself
+#                          fails at startup -- see ibcontroller.toml.example), so
+#                          value_from_config can never be pointed at a new, made-up
+#                          field just by editing this file. Naming anything else here
+#                          logs a warning at load time and is silently skipped forever
+#                          at apply time -- never fatal, but never applies either. For
+#                          any setting that isn't one of the two above (like the
+#                          api_precautions_* entries below), use a literal "value".
+#   field_index         -- only used by "type_text_near_label"; which text field (by
+#                          position, 0-based) within the container below the matched
+#                          label. Defaults to 0.
+#
+# Known gap, not urgent (2026-09-06): some Global Configuration screens use dropdown
+# (JComboBox) controls -- not supported by any action here yet. Nothing declared below
+# needs one; revisit if a real deployment does.
+
+# --- API precautions (API/Precautions) ------------------------------------------------
+# Live-checked against a real paper Gateway 10.50 account, 2026-09-06 -- NOT identical
+# to IBC's own ConfigureApiPrecautionsTask.java list (see labels.py's own docstring for
+# the full finding). Two real corrections from that live check:
+#   - api_precautions_bypass_us_stocks_market_data_in_shares is NOT a real control on
+#     this account/build at all (raises ElementNotFoundError if declared) -- dropped
+#     here. Likely account/market-data-entitlement gated, not a stale label; a
+#     different account could plausibly have it.
+#   - api_precautions_bypass_route_marketable_to_bbo exists on the real panel but isn't
+#     in IBC's own list -- added below, set to false (disabled) by default per the
+#     user's own instruction, everything else enabled.
+# All 8 entries below are live-confirmed: each one actually landed (selected=True/False
+# read back via a real dump) before Apply was clicked to commit them.
+
+# [[settings]]
+# tree_path = "API/Precautions"
+# action = "toggle"
+# label_ref = "api_precautions_bypass_us_stocks_market_data_in_shares"
+# value = true
+# Commented out, not dropped from labels.json: confirmed live 2026-09-06 that this
+# control does not exist on this paper account/Gateway 10.50 build at all.
+
+[[settings]]
+tree_path = "API/Precautions"
+action = "toggle"
+label_ref = "api_precautions_bypass_order_precautions"
+value = true
+
+[[settings]]
+tree_path = "API/Precautions"
+action = "toggle"
+label_ref = "api_precautions_bypass_bond_warning"
+value = true
+
+[[settings]]
+tree_path = "API/Precautions"
+action = "toggle"
+label_ref = "api_precautions_bypass_negative_yield_to_worst"
+value = true
+
+[[settings]]
+tree_path = "API/Precautions"
+action = "toggle"
+label_ref = "api_precautions_bypass_called_bond_warning"
+value = true
+
+[[settings]]
+tree_path = "API/Precautions"
+action = "toggle"
+label_ref = "api_precautions_bypass_same_action_pair_trade"
+value = true
+
+[[settings]]
+tree_path = "API/Precautions"
+action = "toggle"
+label_ref = "api_precautions_bypass_price_based_volatility"
+value = true
+
+[[settings]]
+tree_path = "API/Precautions"
+action = "toggle"
+label_ref = "api_precautions_bypass_redirect_order_warning"
+value = true
+
+[[settings]]
+tree_path = "API/Precautions"
+action = "toggle"
+label_ref = "api_precautions_bypass_no_overfill_protection"
+value = true
+
+[[settings]]
+tree_path = "API/Precautions"
+action = "toggle"
+label_ref = "api_precautions_bypass_route_marketable_to_bbo"
+value = false

ibcontroller/data/labels.json

@@ -0,0 +1,81 @@
+{
+  "login": {
+    "gateway_titles": ["IBKR Gateway", "IB Gateway", "Interactive Brokers Gateway"],
+    "tws_titles": ["New Login", "Login"],
+    "login_buttons": ["Log In", "Paper Log In", "Login"],
+    "api_type_ib_api": "IB API",
+    "api_type_fix": "FIX CTCI",
+    "trading_mode_live": "Live Trading",
+    "trading_mode_paper": "Paper Trading",
+    "username_field": "Username",
+    "password_field": "Password",
+    "starting_application_title": "Starting application...",
+    "tws_main_window_menu_item": "File/Lock Application"
+  },
+  "mfa": {
+    "title": "Second Factor Authentication"
+  },
+  "existing_session": {
+    "title": "Existing session detected",
+    "continue_buttons": ["OK", "Continue Login", "Reconnect This Session"],
+    "cancel_buttons": ["Cancel", "Exit Application"]
+  },
+  "accept_incoming_connection": {
+    "title": "Accept incoming connection",
+    "accept_buttons": ["OK", "Yes"],
+    "reject_buttons": ["No"]
+  },
+  "login_failed": {
+    "title": "Login failed",
+    "dismiss_button": "OK"
+  },
+  "dismiss_rules": [
+    {
+      "name": "non_brokerage_account",
+      "match_text": "This is not a brokerage account",
+      "click": "I understand and accept"
+    },
+    {
+      "name": "auto_restart_confirmation",
+      "match_text": "trading platform restart automatically",
+      "click": "OK"
+    }
+  ],
+  "too_many_failed_login_attempts": {
+    "message_prefix": "Too many failed login attempts",
+    "dismiss_button": "OK"
+  },
+  "shutdown": {
+    "gateway_menu_path": "File/Close",
+    "tws_menu_path": "File/Exit"
+  },
+  "settings": {
+    "gateway_menu_path": "Configure/Settings",
+    "tws_menu_path": "File/Global Configuration...",
+    "tws_menu_path_classic": "Edit/Global Configuration...",
+    "dialog_title_marker": "Configuration",
+    "apply_button": "Apply",
+    "cancel_button": "Cancel",
+    "ok_button": "OK",
+    "splash_title_marker": "Starting application...",
+    "controls": {
+      "read_only_api": "Read-Only API",
+      "api_precautions_bypass_order_precautions": "Bypass Order Precautions for API Orders",
+      "api_precautions_bypass_bond_warning": "Bypass Bond warning for API Orders.",
+      "api_precautions_bypass_negative_yield_to_worst": "Bypass negative yield to worst confirmation for API Orders.",
+      "api_precautions_bypass_called_bond_warning": "Bypass Called Bond warning for API Orders",
+      "api_precautions_bypass_same_action_pair_trade": "Bypass \"same action pair trade\" warning for API orders.",
+      "api_precautions_bypass_price_based_volatility": "Bypass price-based volatility risk warning for API Orders.",
+      "api_precautions_bypass_us_stocks_market_data_in_shares": "Bypass US Stocks market data in shares warning for API Orders",
+      "api_precautions_bypass_redirect_order_warning": "Bypass Redirect Order warning for Stock API Orders",
+      "api_precautions_bypass_no_overfill_protection": "Bypass No Overfill Protection precaution for destinations where implied natively.",
+      "api_precautions_bypass_route_marketable_to_bbo": "Bypass Route Marketable to BBO warning for API orders.",
+      "auto_logoff_time_label": "Set Auto Log Off Time (HH:MM)",
+      "auto_restart_time_label": "Set Auto Restart Time (HH:MM)",
+      "auto_logoff_radio": "Auto logoff",
+      "auto_restart_radio": "Auto restart",
+      "am_radio": "AM",
+      "pm_radio": "PM"
+    }
+  }
+}

ibcontroller/data/labels.json.example

@@ -0,0 +1,44 @@
+{
+  "_readme": [
+    "Example override for {config_dir}/labels.json -- ibcontroller init/run copy this",
+    "file as labels.json.example, NOT as labels.json: labels.load_labels() applies",
+    "{config_dir}/labels.json unconditionally the moment it exists, so activating an",
+    "override is a deliberate rename, never automatic.",
+    "",
+    "labels.py's own _deep_merge overrides one field at a time -- you only need to name",
+    "the label that actually changed, not repeat every sibling field or every other",
+    "domain untouched. This file is trimmed down to two illustrative examples, not a",
+    "full copy of the bundled data/labels.json:",
+    "",
+    "  - login.gateway_titles: shows how to add a title variant IBKR renamed/localized",
+    "    (the override REPLACES the whole list, so include every title you still want,",
+    "    not just the new one).",
+    "  - dismiss_rules: this one is a list, not a nested object, so an override replaces",
+    "    the whole list rather than merging entry by entry -- copy the bundled entries",
+    "    here (as done below) before adding your own, or you'll lose the built-in ones.",
+    "",
+    "Remove this _readme key before using the file for real -- it is not a real Labels",
+    "field and is harmless where cattrs ignores unknown keys, but it's not meant to ship.",
+    "See labels.py's own module docstring and DismissRule's docstring for the full",
+    "mechanism."
+  ],
+  "login": {
+    "gateway_titles": [
+      "IBKR Gateway",
+      "IB Gateway",
+      "Interactive Brokers Gateway"
+    ]
+  },
+  "dismiss_rules": [
+    {
+      "name": "non_brokerage_account",
+      "match_text": "This is not a brokerage account",
+      "click": "I understand and accept"
+    },
+    {
+      "name": "auto_restart_confirmation",
+      "match_text": "trading platform restart automatically",
+      "click": "OK"
+    }
+  ]
+}

ibcontroller/diagnostics.py

@@ -0,0 +1,119 @@
+"""Built-in replacement for poking the agent socket by hand (`socat`/`nc`)
+during layer-by-layer development: `watch_for_diagnostics` runs for the
+agent's whole lifetime, dumping component structure for windows matching
+`Config.diagnostic_scope`/`diagnostic_when` and handing the formatted text
+to a `Sink`.
+
+Deliberately split into capture (`format_dump`, built on the existing
+`actions.dump`), trigger (`watch_for_diagnostics`, modeled directly on
+`recognisers.watch_for_unprompted_windows`), and sink (a plain callable) --
+the log sink below (`log_sink`) is the only one shipped now, but an
+interactive `diagnose` CLI or a control-API handler can pass a different
+sink later without touching capture or trigger logic.
+
+Off by default (`Config.diagnostic_when` defaults to `NEVER`)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable
+
+from ibcontroller.actions import dump
+from ibcontroller.agent_client import Component, WindowEvent, WindowGoneError
+from ibcontroller.config import DiagnosticScope, DiagnosticWhen
+from ibcontroller.dispatch import Dispatcher
+from ibcontroller.recognisers import RecognizerRegistry
+
+logger = logging.getLogger(__name__)
+
+Sink = Callable[[WindowEvent, str], None]
+"""Receives the triggering event and the formatted dump text (or a
+one-line fallback, see `watch_for_diagnostics`). `log_sink` is the only
+implementation shipped now."""
+
+
+def log_sink(event: WindowEvent, text: str) -> None:
+    logger.info("diagnostic dump (%s):\n%s", event.kind, text)
+
+
+def format_dump(event: WindowEvent, components: list[Component]) -> str:
+    """One line per component: class, name/accessible_name/text (when
+    present -- `dump` already omits `text` for credential fields, nothing
+    extra to redact here), enabled/visible."""
+    lines = [
+        f"{event.kind} {event.window.class_} {event.window.title!r} "
+        f"window_id={event.window.window_id}"
+    ]
+    for component in components:
+        parts = [component.class_]
+        if component.name:
+            parts.append(f"name={component.name!r}")
+        if component.accessible_name:
+            parts.append(f"accessible_name={component.accessible_name!r}")
+        if component.text:
+            parts.append(f"text={component.text!r}")
+        parts.append(f"enabled={component.enabled}")
+        parts.append(f"visible={component.visible}")
+        lines.append("  " + " ".join(parts))
+    return "\n".join(lines)
+
+
+async def watch_for_diagnostics(
+    registry: RecognizerRegistry,
+    dispatcher: Dispatcher,
+    scope: DiagnosticScope,
+    when: DiagnosticWhen,
+    sink: Sink = log_sink,
+) -> None:
+    """Runs for the agent's whole lifetime (meant to be started via
+    `asyncio.ensure_future`, like `watch_for_unprompted_windows`; never
+    returns on its own). A no-op if `when` is `NEVER`, so scheduling this
+    unconditionally is safe.
+
+    `scope` is checked against `registry.recognises()` -- the same
+    recognisers `watch_for_unprompted_windows` dispatches through, not a
+    separate classification. A `window_closed` event can't be dumped (the
+    window is already gone by the time this task reacts to the push over
+    the socket -- no in-process synchronous hook the way IBC's own
+    same-JVM listener has); `sink` still gets called, with a one-line
+    fallback noting the window's identity instead of its structure."""
+    if when is DiagnosticWhen.NEVER:
+        return
+
+    wanted_kinds = (
+        {"window_opened"}
+        if when is DiagnosticWhen.OPEN
+        else {"window_opened", "window_closed"}
+    )
+
+    queue: asyncio.Queue[WindowEvent] = asyncio.Queue()
+
+    def on_event(event: WindowEvent) -> None:
+        if event.kind in wanted_kinds:
+            queue.put_nowait(event)
+
+    dispatcher.window_events.connect(on_event)
+    try:
+        while True:
+            event = await queue.get()
+            try:
+                components = await dump(
+                    dispatcher,
+                    window=event.window.title,
+                    window_id=event.window.window_id,
+                )
+            except WindowGoneError:
+                sink(
+                    event,
+                    f"{event.kind} {event.window.class_} {event.window.title!r} "
+                    "(window already gone, no structure)",
+                )
+                continue
+            if scope is not DiagnosticScope.ALL:
+                known = registry.recognises(event, components)
+                if (scope is DiagnosticScope.KNOWN) != known:
+                    continue
+            sink(event, format_dump(event, components))
+    finally:
+        dispatcher.window_events.disconnect(on_event)