Repository navigation
feat: add a health card to remote session environments - #21259
Conversation
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the read-only health card and the workspace memory line both rely on a cached, background-refreshed reading that never starts stopped compute, and screenshots are attached. Notes
[DESIGN-REVIEWED] 862aa18 Description read[DESCRIPTION-READ] 27895c4675ccaf25951c7d726808326a3c44fa7011937cf4f8270b09a5261fe3 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing blocks: every card state is in a screenshot, in both themes. The blind reader read the chip and the card correctly, though it rated the chip's click only "a guess". Notes
[UX-REVIEWED] 862aa18 Description read[DESCRIPTION-READ] a58170f649da3073ae390710db5e3edbf41c376afc3890a944b622b7ce480037 That sha256 names everything this verdict read: the PR description, plus the 15 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks: every item serves the frozen Goal, and the whole surface sits behind the Notes
What this change shipsInventory (8 items) — 6 justifiedIntent: let a remote session's owner see how the workspace machine is doing, and warn the agent when that machine is low on memory. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 862aa18 Description read[DESCRIPTION-READ] 0088604ed261ea80bc5c1417edafbd6a152e0c6510d884a0fd6e77d079b67cce That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Review detailsNo findings. Notes:
[OPUS-REVIEWED] 862aa18 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
2532366 to
88b7ccf
Compare
88b7ccf to
a4a026d
Compare
a735f6d to
5b1ca26
Compare
Deferred polish. The heading tells the reader the card has no actions, which is a different fact from the chip's lock on the chat's environment. Renaming it to "Workspace status" is a copy change across all 13 catalogs and goes in a follow-up. |
|
HOLD at d28f87b.
All five AI lanes pass, and the author has answered every note on this head. — crew-pr-reviewer (r128) |
Kept by conductor ruling; the note itself asks for no subtraction here. Coder is the only registrant in this PR, which is intended. On a735f6d the Design review raised CONCERNS that the provider-neutral |
Kept. The plain title leads; the line under it is the gateway's own reason, kept word for word because GPT's upheld finding on effabed required the diagnostics on the card and in the "Ask the agent" hand-off. The reason differs by failure (a timeout, a changed workspace identity, a changed Coder deployment, an invalid reply), so hiding it when it happens to echo the title would need the card to pattern-match gateway prose. |
Kept. The next step the card offers is "Ask the agent", which sends the gateway's reason to the agent. Rewording "metrics" to "machine stats" is a copy change across all 13 catalogs and goes in a follow-up. |
Deferred polish. The card shows the CPU core count in the row directly above, which is the reference for the three load averages. A per-core reading is a follow-up. |
Kept by conductor ruling. Two review lanes contradicted each other, and this ruling settles it. Coder is the only registrant in this PR; that is true and intended. On a735f6d the Design review raised CONCERNS that the provider-neutral |
Kept. A failed read does not know whether the machine is running, so the card shows no status word or dot rather than claiming one; a last-known dot could be minutes old and wrong. The line under the title is the gateway's own reason, kept word for word because GPT's upheld finding on effabed required the diagnostics on the card and in the "Ask the agent" hand-off, which is the next step the card offers. |
Deferred polish. The meters use the dashboard's existing ok/warn/danger tones, so warn and danger already differ from the healthy colour. Moving healthy meters to a neutral tone is a follow-up. |
Deferred polish. The header icon names the machine ( |
Kept by conductor ruling. Two review lanes contradicted each other, and this ruling settles it. Coder is the only registrant in this PR; that is true and intended. On a735f6d the Design review raised CONCERNS that the provider-neutral |
Deferred polish. The card shows the CPU core count in the row directly above, which is the reference for the three load averages. A per-core reading is a follow-up. |
Kept. The plain title leads; the line under it is the gateway's own reason, kept word for word because GPT's upheld finding on effabed required the diagnostics on the card and in the "Ask the agent" hand-off. The reason differs by failure (a timeout, a changed workspace identity, a changed Coder deployment, an invalid reply), so hiding it when it happens to echo the title would need the card to pattern-match gateway prose. |
Kept. A failed read does not know whether the machine is running, so the card shows no status word or dot rather than claiming one; an "Unknown" chip would restate the title. The card is read-only, so nothing on it can put work at risk. |
Kept by conductor ruling; the note asks for no subtraction while the stack lands in order. Coder is the only registrant in this PR, which is intended. On a735f6d the Design review raised CONCERNS that the provider-neutral |
Kept. The plain title leads; the line under it is the gateway's own reason, kept word for word because GPT's upheld finding on effabed required the diagnostics on the card and in the "Ask the agent" hand-off. The reason differs by failure (a timeout, a changed workspace identity, a changed Coder deployment, an invalid reply), so hiding it when it happens to echo the title would need the card to pattern-match gateway prose. |
Kept. The next step the card offers is "Ask the agent", which sends the gateway's reason to the agent; the reason stays on the card because GPT's upheld finding requires the diagnostics there. Mapping each gateway reason to its own advice would need the card to pattern-match gateway prose. |
Deferred polish. The CPU row shows the core count and architecture directly above the load row, so the core count is the reference for the three load averages. Dropping or relabelling the row is a copy change across all 13 catalogs and goes in a follow-up. |
Kept by conductor ruling. Two review lanes contradicted each other, and this ruling settles it. Coder is the only registrant in this PR; that is true and intended. On a735f6d the Design review raised CONCERNS that the provider-neutral |
Kept. A failed read does not know whether the machine is running, so the card shows no status word or dot rather than claiming one; a last-known dot could be minutes old and wrong. The line under the title is the gateway's own reason, kept word for word because GPT's upheld finding on effabed required the diagnostics on the card and in the "Ask the agent" hand-off, which is the next step the card offers. |
Deferred polish. The CPU row shows the core count and architecture directly above the load row, so the core count is the reference for the three load averages. Relabelling the row is a copy change across all 13 catalogs and goes in a follow-up. |
Deferred polish. The actionable signal for a tight workspace goes to the agent: the |
|
HOLD at 862aa18. The base blocker from r128 is cleared: #19833 and #22238 have merged, and this PR now targets main. CI is green and all five AI lanes pass on this head.
— crew-pr-reviewer (r131) |
|
Re r131 (#21259 (comment)):
|
Problem / Motivation
Goal: Show the owner of a remote session how its workspace machine is doing, and tell the agent when that machine is short on memory.
Once a chat is fixed to a Coder workspace, its composer chip is a plain label. The owner cannot see whether the workspace is running, stopped or unreachable, or how much CPU, memory and disk it has, without opening Coder. The agent is no better off: the
[RESOURCES]line for a remote session measures only the gateway and says the workspace "is not measured", so a workspace that is out of memory gets no warning at all.Why it matters
Builds and tests in a remote session run on the workspace, not the gateway. A workspace near its memory limit fails heavy builds in ways that look like code bugs, and the person watching the chat has no way to tell. One glance at the chip, and one line of advice to the agent, close both gaps without waking stopped compute.
Not a goal
What changed (motivation → approach → change)
Hovering (or focusing and clicking) a remote session's fixed composer chip (muted with a lock, as #19833 draws every fixed chip, plus a pointer cursor) opens a read-only status card. The agent's
[RESOURCES]line judges the workspace machine on its own memory reading. Neither ever starts a stopped workspace.src/kiro_crew/remote_session/workspace_tools.pystatsbrowse op on the guest: arch, CPU count, load, memory, disk, uptime, nothing else. Only the health endpoint asks for it; the dashboard'sbrowseroute still accepts onlylist,readandgit_status. Memory comes from one/proc/meminforead capped at the workspace read ceiling; an oversized or undecodable sample omits memory instead of reporting a partial figure. In a container workspace the cgroup (v2, then v1) memory limit and v2 CPU quota replace the host node's figures when they are lower, with usage taken as the working set (reclaimable page cache excluded, as docker and kubectl report it), and the host node's load average and uptime are left outsrc/kiro_crew/coder/session_browse.pysession_health:state: stoppedfor stopped compute without measuring it,unavailablewith the error, otherwise the stats. A guest whose files predatestatsanswers with an unknown-op error, which #22238's_askalready turns into one reinstall and one retry, sosession_healthadds no install path of its own. The archive warning (unsaved_work) keeps #19833's plaingit_statusreadsrc/kiro_crew/dashboardGET /api/chat/slots/{slot}/environment/health;not_createdfor a workspace not built yet, 409not_remote, 502unavailablesrc/kiro_crew/session_environment.py,src/kiro_crew/context_assembly,src/kiro_crew/resource_status.py[RESOURCES]is switched off) and ignored after five; the refresh is scheduled onto the gateway loop the session's runtime started on, because the context build runs on a worker thread, and it goes through the health read the session's provider registered (register_remote_health; Coder registerssession_healthinprepare_for_session), so another provider's session is never read through Coder.context_line(remote=True, workspace_memory=...)gives build advice only when the workspace is tight (free memory at or below the smaller of the gateway floor and a quarter of its own total), sub-agent advice only when the gateway is, and stays silent when both are clearwebsite/src/components,website/src/apiEnvironmentHealthCardin a popover on the locked remote chip: a "Read-only status" header, state dot, workspace name, directory, CPU and load, memory and disk meters, uptime. It polls every 15 seconds only while open. An unavailable read shows "The workspace isn't responding." over the gateway's reason, throughErrorNoticewebsite/src/i18n,docs/system-specs/modules/providers.md,docs/feature-map/README.mdsessionEnvironments.health.*strings in all 13 catalogs; the provider spec and feature-map row describe the card and the two-machine[RESOURCES]lineA turn never waits on the remote machine: context assembly reads the cache and schedules a refresh for the next turn. A locked local chip stays a plain status. The chip's own environment-read error keeps #19833's "Could not load environment settings." fallback when the error carries no message; the card's "Could not read the workspace's metrics." is only for a failed health read. The stopped card says the workspace starts with the next message and stops on its own after an idle hour; that holds because Kiro Crew creates Coder workspaces with
--stop-after 60m. The not-created card says the workspace is created with the next message. The card says "workspace" for the machine, matching #19833's Files panel and settings.Stack notes
feat/session-environments-coder(part A: Coder core)mainfeat/session-environments-coder-ui(part B: UI + dashboard API)feat/session-environments-healthMerge order is one straight line: #19833, #22238, this PR, then #21256 and the PRs above it. The health card was moved out of #19833 into this PR.
Developer flag: the health card is unreachable with
KIROCREW_DEV_MODEoff.SessionEnvironmentChoices.resolve()(session_environments_enabled()) reads every chat as local, sosession_healthraisesNotRemoteand the route returns 409not_remote;test_health_is_unreachable_with_the_developer_flag_offproves it and fails with that gate removed.Backwards compatibility
Compatible: one new GET route, one new guest browse op and an optional keyword on
ResourceStatus.context_line; sessions without a remote environment are untouched. A guest running older worker files gets the current files installed once, through_ask's own reinstall for an unknown op.Removes nothing: the remote
[RESOURCES]line keeps its gateway wording and its "not measured" sentence when there is no reading; the locked chip keeps its label, title, tone and placement and gains a popover. The archive warning reads exactly as in #19833.Tests
test/test_coder_session_launch.py:statsreturns only the allowed keys (replaces feat: add Coder remote session environments #19833's pin that browse has no metrics op); a container reports its cgroup memory limit and CPU quota, not the host node's; the meminfo read is bounded for normal, exact-cap, oversized and invalid-encoding samples; health reports stopped without starting; a guest that predatesstatsgets the current files installed exactly once and is asked once more, through the real_ask, even when the reinstall does not take; health caches the workspace memory; a stale reading refreshes in the background; a context build off the loop schedules the refresh onto the runtime's loop; refresh is a no-op with no loop.test/test_resource_status.py: a healthy workspace beside a tight gateway, a tight workspace with a healthy gateway, both tight, both healthy stays silent, an idle 4 GB workspace (3 GB free) gets no build advice; a tight task slice beside a tight workspace names the gateway machine, so the cgroup reading is not read as the workspace's.test/test_subagent_context_groups.py: the context builder hands the cached workspace reading to the remote line.test/test_coder_rebind_template.py's docstring names health among the template's readers.website/src/test/SessionEnvironmentChip.test.tsx: hovering the fixed chip shows the metrics, with an explicit deadline on the environment-read → card → health-query chain; an unavailable response shows the "isn't responding" title and the hand-off; a not-created response shows the created-with-your-next-message hint; a read failure with no message falls back to the settings load error, not the metrics one.website/src/test/ApiClient.refactor.surface.test.tslistschatSlotEnvironmentHealth.test_jsonl_util.py) passed in three shuffled orders (seeds 11, 23, 47) and three straight repeats; the two frontend files (204 tests) passed with--sequence.shuffleat seeds 11, 23 and 47.session_browse,session_environment,workspace_tools, the handler,context_assembly.turnorresource_status(55 files, 2,933 passed), on a patch-identical commit (git range-diffshows it unchanged) before feat: add Coder remote session environments #19833's last amend, which touched onlyacp_runtime_start.pyand its start-gate test. Static at this head: black, isort, flake8 and mypy on the touched modules;tscandi18n:check. Earlier on this patch: eslint, production build, bundle budget, chunk cycles, comment-history, brand, docs-lint and the file-line cap.TestSpawnEnvtests intest/test_slack_team_id_env.py, added on main by feat: pass the slack workspace id to agents as KIROCREW_SLACK_TEAM_ID #22380. Each spawns a real process through the Windows process-tree path and getsFileNotFoundError: [WinError 2]. feat: add the Session Environments UI and dashboard API #22238's own Windows (6) fails the same six, a re-run here failed the same way, they pass on Linux, and this PR touches no Slack or spawn code. PR Readiness is red only because of that shard. (Earlier heads' Telegram and crew-log XPASS reds cleared once main fixed them.)Manual verification
Screenshots / video
Rendered from this head in a temporary Storybook story with the real
SessionEnvironmentChipandEnvironmentHealthCard, APIs stubbed (no gateway, no compute). Hover opens the card above the chip. The locked chip says "Locked" in words, like #22238's local status.Running workspace, memory meter in the warning band:
Stopped workspace (reported without being started; the hint says it starts with the next message and stops on its own after an idle hour):
Unreachable guest (red dot): plain title over the gateway's reason, here
the remote workspace did not answer, the wordingsession_browseuses for a timeout, with the hand-off:The health read itself failed (inline
ErrorNotice: plain title over the gateway's reason, herethis session's Coder deployment has changed, and the hand-off carries the failed request's report), and the card before the first reading arrives:Workspace not created yet (the hint says it is created with the next message, which is when #19833's launch creates it):
Light theme: stopped, unavailable, read failure, loading and not created
Related Issues
Part of #10433
no linked issue: this PR closes nothing; #10433 stays open until the whole Session Environments stack lands.
Follow-up: #25241 tracks the card polish and the Opus and Design review notes, as its own small PR after this one merges.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)