Repository navigation
feat: add Coder remote session environments - #19833
Conversation
02b0803 to
49006ee
Compare
49006ee to
d6281e9
Compare
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. Everything new sits behind the existing What this change shipsInventory (9 items) — 8 justifiedIntent: let a developer run a chat's files, builds, tests and shells on a Coder workspace while the engine stays on the gateway — ADDITION.
[FIRST-PRINCIPLES-REVIEWED] f50cedd Description read[DESCRIPTION-READ] f0845201e5bf42e19a428511c52dc075cd26a1c295d849faa33b6090f96c379c That sha256 names the PR description this verdict read. Recompute it with |
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: |
d6281e9 to
3d6c5da
Compare
3d6c5da to
aff2e76
Compare
UX Review (Opus 5.5) — ⏭️ skippedRevision |
|
needs-a-decision (span=2662e365059c)
|
|
rebutted (span=9535134ecbb9)
|
|
rebutted (span=2696352b428d)
|
|
fixed (span=ced83f35919b)
|
|
fixed (span=7a426fc1f7b6)
|
|
fixed (span=8f2fde28a6b9)
|
|
HOLD (policy: permission, auth and kill/delete paths) at b805599. This PR is reserved for a human maintainer. It changes what the permission gate admits: workspace tools are mapped onto built-in identities in permission_requests.py#L908-L927, and For the human reviewer:
I did not read every file of the 13k-line diff. The launch, worker-lifecycle, wire/relay and workspace-tool modules need a full human read. — crew-pr-reviewer (r119) |
Let a chat run its workspace on a Coder workspace while the agent engine stays on the gateway. Adds the Coder provider and worker transport, per-session files and terminal access, retention, a global default environment, and the Settings card and composer chip. Remote sessions unmount local-only tools, skip the gateway spawn memory floor for subagents, name the guest directory in [PROJECT], and scope [RESOURCES] to the gateway machine, saying the remote workspace is not measured. Other providers (Fargate, Fly.io Sprites, boxd, Kiro Cloud), the environment health card and the ready pool follow in stacked PRs.
|
GPT 6.1 disposition for 8e37a5c F1 ( |
|
HOLD at f50cedd: permission, transport-token and kill/delete paths, reserved for a human maintainer. This PR changes what the permission gate admits. Workspace tools are read as the built-ins they replace in permission_requests.py L908-L927, and For the human reviewer:
I did not read every file of the 13k-line diff. The launch, worker-lifecycle, wire/relay and workspace-tool modules need a full human read. No tests were run locally. — crew-pr-reviewer (r122) |
Problem / Motivation
Goal: let a chat run its files, builds, tests and shells on a Coder workspace while the agent engine stays on the gateway.
Today every session works on the gateway machine, so heavy work competes with every other session on that host, and one session cannot get a clean or larger machine without a second gateway.
Why it matters
Per-session isolation and headroom on the Coder deployment a team already runs, without moving memory, crons, subagents or chat history off the gateway.
Not a goal
browse_session,write_session_fileandremote_terminal_argvincoder/session_browse.py, plus the guest'slist/readops and--writemode), start progress (report_start_stage/start_progress) and thesession_environments.default_profilesetting. They ship with part B, where their callers are.docs/request-for-change/rfc-remote-work-recovery.md, its own PR).What changed (motivation → approach → change)
This is the backend half. A session bound to a Coder profile runs its files, builds, tests and shells in that workspace; the engine, memory, approvals, crons and subagents stay on the gateway, and no model credential reaches the workspace. Part B adds the controls that bind a chat; on its own this PR has no way to bind one.
Developer flag. Everything here is reachable only on a gateway started with
KIROCREW_DEV_MODE=1, the repository's developer flag. Off (the default),SessionEnvironmentChoices.resolveanswers "this machine" for every session, runtime start never prepares a workspace, and the Coder retention sweeper and shutdown stop never start, so every session runs exactly as on main (test_session_environments_developer_flag).src/kiro_crew/session_environment.py,src/kiro_crew/remote_sessionsrc/kiro_crew/codercoder sshtransport with output caps, ownership registry, launch, the archive-time unsaved-work read, retention, start-up. Lifecycle calls and everycoder ssh(install, worker, unsaved-work read) authenticate the same way: the CLI's stored login, with no inheritedCODER_*overridesrc/kiro_crew/providers,src/kiro_crew/acpacp/runtime_remote_workspace.py, bound byAcpRuntimelike main's otherruntime_*ownerssrc/kiro_crew/context_assembly,src/kiro_crew/resource_status.py[PROJECT]names the guest directory;[RESOURCES]says the workspace is not measuredsrc/kiro_crew/subagent.py,src/kiro_crew/subagent_parts,src/kiro_crew/subagent_manager,src/kiro_crew/session_allocation_parts/get_or_create.py,src/kiro_crew/session_parts/policy.pyMemoryWait.remote), price from@remote; the pool recordsbypass_remote_environment. A parent's placement entry (remember_remote_workspace) belongs to its runtime and leaves when that runtime ends, so the bounded table never evicts a live parentsrc/kiro_crew/mcp_core.py,src/kiro_crew/mcp_tools/artifacts.py,src/kiro_crew/computer_usetask_runand alocal_dirdeploy) are unmounted and refused in bandsrc/kiro_crew/acp/_dispatch_parts/permission_requests.py,src/kiro_crew/acp/session_handle_permissions.py,src/kiro_crew/platform/governance.pyrun_commandreaches the gate as a shell call titled with its command, writes asedit, reads asread, so the shell deny floor, commands policy, path scopes and a deny on the built-in apply unchanged; only a runtime that attached the workspace gets the mapping, and a relative path argument is judged at the guest workdir, where the guest resolves it; a Tool Search deferred call ({"tool_id": "workspace::<tool>", "arguments": {...}}) is judged by the inner arguments the guest receives, and only whentool_idnames the trusted call, so any other envelope is refused as an unreadable identity; a grant of@workspacenever skips the gatesrc/kiro_crew/dashboard/file_api,src/kiro_crew/dashboard/chat_api/slot_lifecycle.pysrc/kiro_crew/config,config-baseline.json,src/kiro_crew/constants.pysession_environmentssection and baselinesrc/kiro_crew/slackRemote sessions need the KAS agent backend, the default; any other backend is refused before a workspace starts. A bound session never falls back to the gateway. If the choices file cannot be read, only sessions that were bound are refused (each has a marker under
coder/bound/); every other session runs here. A bound session whose row, or the whole file, is gone keeps its marker and is refused too; a row and its marker are only ever removed together. Kiro Crew stops a workspace on archive (deleting it after a fixed 7 days) and, withstop_on_shutdownon, at a graceful shutdown; otherwise Coder's own--stop-after 60mapplies. Off is for an operator who restarts the gateway while working, so their dev boxes keep running. Details, the template contract and the disconnect table are indocs/system-specs/modules/providers.md. Test gates:test/test_spawn_audit.pyallowlists each spawn; the guest runs each command under coreutilstimeout, so the kill ratchet is unchanged. Riders:.github/black-baseline.txtdrops the now black-cleantest/test_resource_status.py;scripts/check_harness_parity.pydrops theACP_BACKENDS_MEMBER_CAPABILITIES [claude]allowlist entry that main's live capture (#21753) now proves;test/test_config_schema.pyresolves field types withtyping.get_type_hintsso a section defined insections_session.pyis found.Backwards compatibility
Compatible: with the developer flag off (the default) nothing here is reachable, and
session_environmentsis a new optional section.Removes nothing for a local session. For a session bound to a workspace only, these refuse in band and are unmounted from its agents:
src/kiro_crew/mcp_core.py:_call_tool_innerforset_project,file_send,browser,pod_up,pod_down,task_run,workflow_run,workflow_rerun_subtree(session_environment.py:LOCAL_ONLY_CORE_TOOLS), andsrc/kiro_crew/computer_use/tools.py:_dispatchfor the wholekirocrew-computerserver, andsrc/kiro_crew/mcp_cron.py:_call_toolfor the wholekirocrew-cronserver (a cron job's command, script or agent session runs on the gateway machine). A local-only server the active agent declares in its ownmcpServersblock is dropped from that block too, so it is neither mounted nor awaited by the managed-server readiness barrier. An allowlist spelled in KAS's own tool ids maps each id to the one workspace tool that does the same (read_file,list_directory,file_search,grep_search,str_replace,execute_pwsh/run_command;fs_appendanddelete_fileget none rather than a wider one). AnexcludedToolsentry spelled as a KAS id with its own workspace tool excludes just that tool (read_fileleaveslist_directory);fs_appendanddelete_filestill exclude the whole write family. A grantedtool_searchloader stays mounted, since deferral was enabled from that grant at the handshake.Behaviour change for a remote session: because
run_commandarrives as a shell call, a native-shell "Always allow" for a command also covers that command in the workspace, the same as on this machine; the gate's deny tiers still run first. An allow-mode governance profile must also permit the replaced built-in (execute_bash,fs_write,fs_read), so it can only refuse more.Windows gateways: governance normalizes a path with the gateway's own
os.path, and a guest path is POSIX, so on Windows a filesystem rule could not bind a workspace tool's target. A Windows gateway therefore refuses to attach a remote workspace at all (REMOTE_NEEDS_POSIX_GATEWAY, checked incheck_remote_workspace_supportedbefore any guest compute); the session is asked to run on This machine. Remote placement is supported on macOS and Linux gateways only.Directive replay: the gateway re-runs a directive tool (
set_project) on its event loop to derive what the call asks for. For a local-only tool,api_session_directivelooks the session's placement up in a thread first (asyncio.to_thread(session_runs_remotely, ...)) and hands the answer to the replay throughsession_environment.known_placement, keyed to that session, so the remote-workspace guard never reads the choices store on the loop.Unconfirmed worker stops: a guest worker is recorded per chat binding (
coder/remote_worker.py,_UNCONFIRMED_STOPS) when its relay starts closing or its stop fails, and cleared only by a confirmed stop. A worker a live relay still owns is never recorded, so a subagent sharing its parent's binding never stops the parent's workers. Before a replacement engine attaches the workspace,workspace_serverretries each recorded stop and refuses (EARLIER_WORKER_RUNNING) while any remain; that also covers a relay close that outlives its 60 s wait. Workers an earlier gateway process left are reaped by signalling all of them and then waiting for each to exit; a reap that cannot confirm an exit refuses the start and is retried on the next one. On the guest, the first SIGTERM starts retirement and later ones are ignored, so a second TERM cannot interrupt a running command's process-group cleanup. A stop that times out keeps the worker's record (only a confirmed exit removes it), so the next confirmation finds the worker again instead of reading it as gone. A connection that ends (its link failed or closed) records its worker before any cleanup is awaited, and the relay keeps tracking it until its stop is confirmed, so a reset during that cleanup still stops and confirms it.Retention stops: shutdown and archive stop a workspace, and the retention sweep deletes one, only when its current Coder UUID matches the nonempty UUID recorded for that reservation (
_is_recorded_workspace), so a reservation whose provisioning failed never touches another workspace that later took its name. With the developer flag off, archive retention and the sweep run no Coder command at all, so a binding left from a dev-flag run is neither stopped nor scheduled for deletion.Choice rows: only a remote choice writes a row, so a row this build cannot read (wrong type or provider, missing or invalid profile) refuses the session instead of reading as local.
Workspace tools: a
/workdir admits every absolute path;globmatches path segments (*and?stay within one segment,**/spans zero or more), and a pattern with no/matches the file name at any depth.read_filepaging counts a line longer than one bounded read once, sooffsetlands on the requested line.This PR touches no Sensitive Change Review path (
.github/scripts/sensitive_change_review.pySENSITIVE_GLOBS).Tests
test_session_environments_developer_flag(flag off is local-only; a corrupt file refuses only bound sessions),test_remote_session_local_only_tools(every parity case enters throughbuild_permission_event; one revert-fail case per mapped tool; the builder is the only permission-event source),test_session_environments_start_gate,test_coder_*,test_remote_session*,test_remote_relay_token_privacy,test_remote_command_lifetime,test_coder_retention,test_coder_shutdown_budget, gate tests. Each new test fails on the code before it.Manual verification
Coder exec streaming probed live. Per Kyle's ruling the feature ships behind the developer flag and is tested live on a real Coder deployment before it is turned on: start, shell, file save, archive-stop, shutdown-stop. That run has not happened yet.
Screenshots / video
N/A: this PR changes no UI. The UI is part B, #22238.
Related Issues
Part of #10433 (no closing keyword: a stack closes it). Stack: this PR → #22238 UI → #21259 health → #21256 git → #21257 Sprites/boxd → #21258 Fargate → #21260 Kiro Cloud.
Checklist