dsh-a11y-announcer

Accessibility plugin for the DeepSeek Harness web UI. Announces tool calls as soon as they appear and finished assistant messages through an aria-live region. NVDA/JAWS/VoiceOver read the live region automatically, without moving the user's focus.

Behavior

• Tool calls are announced shortly after they appear ("Tool: <name + content>"), once their text is briefly stable — NOT when they finish (the start is the interesting moment). A short debounce (TOOL_SETTLE_MS=400ms) avoids reading the very first streaming fragment (e.g. a half token like "ulti" from "multi-...").
• The last finished assistant message is announced with its full text over the live region (not while streaming).
• Only the visible answer text is read; the agent's internal reasoning ("Think" block) is excluded so streamed reasoning fragments are not read aloud.
• Deduplication via data-chat-anchor-key: each element is announced only once; re-renders do not trigger a new announcement.
• Assistant settle is detected via the data-streaming attribute (dsh removes it once streaming finishes), so only complete text is announced.
• No replay: nodes already present when loading an old session are not walked through, only new events from now on.

Deep-diving announcement

• While the dsh "Deep diving..." status (agent working) is active, "Deep diving..." is announced every 5 seconds over the live region for as long as the state persists (first announcement after 5s, then every 5s).
• Detection by content: a role="status" element whose text contains "Deep diving". IMPORTANT: dsh may additionally render an EMPTY role="status" element; therefore match on text content, not on the first role=status.
• Fallback: in addition to the MutationObserver, a 1s polling loop (for missed mutations).

How it works

• Client plugin, discovered via dsh.client metadata (platform: web) and activated as its own bundle (dsh.bundle.patch = cordis.patch.yml with - insert) in the web profile.
• lib/index.js = plain host loader entry (apply/inject), NO window.__ModuleLoader__ wrapper (server-side, otherwise "window is not defined" and the plugin is not activated).
• lib/client.js = browser bundle (ModuleLoader wrapper). Uses a MutationObserver on the [data-slot="conversation.session"] container and selects targets via data-chat-flow-kind / data-chat-anchor-key.
• Assistant settle detection via the data-streaming attribute: dsh renders the assistant markdown root with data-streaming while it streams and REMOVES it once the full text is settled. The plugin observes attribute changes (attributes + attributeFilter: ["data-streaming"]) and only announces when the node is no longer streaming — so it never reads partial output.
• Tool calls are announced after a short debounce (TOOL_SETTLE_MS=400ms) once their text is briefly stable, without waiting for completion.
• Text extraction: clones the node and REMOVES the agent's internal reasoning ("Think" block, data-variant="think") before reading textContent. This keeps the hidden, streamed reasoning fragments from being read aloud — only the visible answer text is announced. It also strips known model-artifact lines (a bare "ulti" the LLM occasionally appends). For tool calls, textContent also captures collapsed/hidden content (which innerText would omit).
• Announcement: a hidden (but assistive-visible) div with aria-live="polite" + role="status"; textContent is set when settled. No element.focus() (moves the user's focus unnecessarily and did not reliably read elements).

Installation

• Package: this repository (e.g. cloned to /opt/dsh/plugins/dsh-a11y-announcer/).
• Add as a file dependency in /opt/dsh/package.json and /mnt/ssd/dsh/profiles/web/package.json.
• Add as a bundle in dsh.profile.bundles (profiles/web/package.json).
• After changes to lib/client.js: restart dsh web (no bundle build needed, the file is served directly).

Files

• lib/client.js — browser bundle (MutationObserver + aria-live announcement)
• lib/index.js — host loader entry (empty)
• cordis.patch.yml — - insert of the loader entry
• package.json — dsh.client + dsh.bundle + exports["./client"]

Tests

Logic verified in jsdom (see development test cases):

• A tool call is announced shortly after appearing ("Tool: ") with its full text, without waiting for completion; streaming fragments (e.g. "ulti" from "multi-...") are not announced thanks to the short debounce.
• A finished assistant is only announced after text stability (900ms) with the full text, not while streaming.
• The live region has aria-live="polite".
• Deduplication via data-chat-anchor-key works.