dsh-review-float
A frame-wide floating PR / review status bar for DeepSeek Harness (dsh).
dsh plugin --profile ctweb add @calltelemetry/dsh-review-float
Published to npm under the @calltelemetry scope, so it installs by version. No
git credential is required to consume it.
Listing the package in dsh.profile.bundles is the entire mount, because it
ships its own cordis.patch.yml (dsh.bundle.patch):
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@calltelemetry/dsh-review-float"]
No hand-edited profile patch is ever required — a - id: review-float row would
duplicate the loader entry and crash boot. In the Call Telemetry workspace this
mount is owned by DSH_THIRD_PARTY_PLUGIN_PINS in scripts/ct-meta/sync.py,
which renders the pin and installs it in one change (ADR 0656). Restart the
profile afterwards.
What it does
It registers one additive entry into the shell.overlay list slot — the
seat the layout package documents as "a badge, a toast stack or a status pill
… the layer itself is click-through — entries opt back into pointer events."
| State | Surface |
|---|
| Bar | Always-on pill above the composer: N running · M need you, then per-PR chips |
| Docked pane | Click a chip → 460px panel with exact head SHA, verdict, CI, progress, findings |
| Exploded board | Click Board → four columns: Running / Ready to merge / Needs you / Queued |
The live bar over a real session
Live, not mocked: 14 real open PRs with the Review Yeti verdict read from each
head's check run. docs/shots/ also has the docked pane and the exploded board;
docs/prototype.html is the standalone design prototype.
Development
npm install # TypeScript only; no bundler required
npm run build # tsc -> src/ transpile -> module-loader bundle in lib/
npm run check # exits 1 if the committed lib/ has drifted from src/
src/ is the source of truth. lib/ is committed on purpose: a link: or
git install consumes the built bundle directly, and dsh-client-modules requires
lib/client.js to exist before launch. npm run check is what keeps that
trustworthy.
Layout
src/client.ts browser half — the bar, pane, and board
src/index.ts host half — empty apply, so the package owns a Loader row
src/types/platform.d.ts ambient `react` (a PLATFORM_MODULES baseline module)
src/types/harness.d.ts ambient client context (slots + effect)
scripts/build.mjs real build: tsc transpile + module-loader envelope
cordis.patch.yml dsh.bundle.patch — the self-mounting loader row
No bundler. tsc transpiles src/ and scripts/build.mjs wraps the output
in the window.__ModuleLoader__.load({id, factory}) envelope that every shipped
@deepseek-ai/dsh-client-ui-* package uses (they use tsdown for the same job).
The plugin requires only react, which the shell provides from its frozen
PLATFORM_MODULES baseline — so there is no second React copy and no
dsh.client.external entry.
Design constraints honoured
- Additive, not a takeover.
shell.overlay is a list slot; the entry carries
a plugin-owned id (review-float), never a core row id.
- Click-through. The root stays
pointer-events: none; only the bar, the
pane and the board opt back in, so the app underneath is never blocked.
- Theme-native. Every colour is a
--dsw-alias-* token with a literal
fallback, so it follows light/dark automatically.
- Read-only viewer. It renders review status and never dispatches review
work, opens a second reviewer, or posts to GitHub. The detail pane carries a
visible
policy note saying so, and it deliberately does not compete with the
official Review Yeti action.
Data sources
The bar is fed by the host half, which serves one read-only snapshot on the
shared /api channel (/api/review-float.snapshot). The browser half polls it
every 20s through connection.rpc. The browser never holds a credential and
never talks to GitHub directly.
Two independent sources, deliberately:
| Source | Supplies | Required? |
|---|
| GitHub GraphQL | PR identity, exact head, CI ratio, and the Review Yeti verdict | yes |
| Review Yeti MCP | The live phase of in-flight reviews, and per-finding severity (P0/P1/P2) for the detail pane | optional |
Where live progress actually comes from
get_review_status reads review_runs.stage from Postgres and returns a live
phase — queued, evaluating_personas, arbitration, completed. In-flight
rows are enriched from it, so the bar shows real state while a review is running
(observed live: #5149queued, #3414queued).
This is deliberately not an event stream. The bot's LiveStreamBus is a
process-local singleton fed only by the worker execution path, and review workers
run as separate pods, so no SSE route can deliver their progress across a process
boundary. The phase above is durable Postgres state, which is why it works
without any event plane.
The query is bounded: running rows only (typically 1–6, not the full list),
fanned out in parallel. If the MCP is unreachable the row keeps the phase parsed
from the check-run summary rather than losing the field.
The Review Yeti verdict is a GitHub check run named Review Yeti on the
exact head, so verdict and CI arrive in one call — no extra dependency. That is
why the surface still renders fully when the MCP token is absent: rows simply
carry no finding severities, and the snapshot says so.
| Env | Effect |
|---|
CT_AGENT_GH_TOKEN / GH_TOKEN / GITHUB_TOKEN | GitHub credential, most explicit first |
| (none set) | falls back to gh auth token — the operator's existing login |
REVIEW_YETI_MCP_AUTH_TOKEN | overrides the Doppler-resolved finding-severity token; never required |
An absent GitHub credential renders review feed unavailable with the reason,
never fabricated rows. An org with zero open PRs renders no open PRs — a
distinct state from an unreachable feed.
No token setup required
REVIEW_YETI_MCP_AUTH_TOKEN is a first-class entry in ct-meta's MCP catalog
(ct-meta/mcp-servers.json), whose canonical source is the Doppler project
review-yeti / config prd. Agents get it through that catalog; this plugin
resolves it directly from the same source, so nothing has to be exported.
Order: an explicit REVIEW_YETI_MCP_AUTH_TOKEN in the environment (a caller
override), then doppler secrets get … --project review-yeti --config prd.
Memoised on success only, so a doppler login performed after the page opened
starts working without a restart.
If neither resolves, the bar still renders every verdict and CI ratio (those
come from the GitHub check run); only finding severities go away, and the detail
pane names both sources it tried rather than showing an empty list.
Verified
Built and checked against dsh@0.1.5-rc.2 / cordis@4.0.2 / Node 24.21.0 / tsc 5.
-
Live phase verified end-to-end: with no credential in the environment, the
bar rendered #5149queued, #706queued, #3416queued, #3414queued and
#786queued while those reviews were running, matching get_review_status.
-
Published artifact verified: 0.1.2 was extracted from the registry and a
clean unauthenticated consumer install was confirmed to carry the live-phase
code — the check is a symbol grep, not a version string.
-
dsh-plugin-check (strict): 19/20 pass, 0 checks failed. The single
non-pass is not-in-hub, an external catalog-intake check that a private
repository cannot satisfy.
-
Live data verified against GitHub truth: cisco-cdr#5144 reads
BLOCKED where its Review Yeti check is fail; ct-meta#3384 reads
SHIP where it is pass. 14 open PRs across the org render with real head
SHAs and CI ratios.
-
Booted a full ctweb clone: bundle served HTTP 200, plugin self-mounted
from dsh.profile.bundles with no manual patch row.
-
Rendered in a real browser (headless Chrome over CDP, DOM assertions not
screenshots): bar mounted, 14 chips, lead 3 running · 2 need you; clicking a
chip opened the pane with the real head SHA (cisco-cdr#5144 → b9e6cc6);
Board opened all four columns. Zero console errors.
-
Load: snapshot steady at ~2.5-3s over 5 sequential calls; 5 concurrent
calls did not serialize destructively (3.4-3.9s each). A 30-poll soak run
back-to-back returned 200 on every call with zero RSS growth, and GitHub's
GraphQL limit was still 5000/5000 afterwards — one call per poll is ~180/hour
against a 5000/hour ceiling, so a single tab has ~28x headroom.
-
Degradation is honest: with the MCP token absent, sources.yeti reads
false and the findings endpoint returns
finding detail off — set REVIEW_YETI_MCP_AUTH_TOKEN rather than an empty
list. With it present, ct-release#1718 and ct-infrastructure#657 both
returned real ["P2"] severities.
-
