Skip to content

feat(dashboard): open remote files in a local editor via ssh links - #11345

Closed
helenastafford wants to merge 2 commits into
mainfrom
feat/remote-editor-links
Closed

helenastafford wants to merge 2 commits into
mainfrom
feat/remote-editor-links

Conversation

@helenastafford

@helenastafford helenastafford commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

When the KiroCrew gateway runs on a remote/headless host (cloud desktop, EC2) and you use the dashboard from a laptop, the file-path menus have no working "open in an editor" action. Open with default app and Reveal are correctly gated on direct_local — they shell out on the gateway host, which has no desktop here — and the Electron Open in editor bridge targets the laptop's filesystem, where the file does not exist. So every file-open affordance dead-ends at Copy path, and editing a file the agent cannot write (trust-root config like config.json, .env) means a manual SSH session.

Why it matters

The remote-gateway-on-a-cloud-desktop topology is common, and it is exactly where you most need to jump into an editor for the files the agent and the read-only Files app cannot touch. Today that is a context switch to a terminal every time.

What changed (motivation → approach → change)

VS Code-family editors accept a remote authority in their URL scheme, so a link like vscode://vscode-remote/ssh-remote+<host><path> launches the user's local editor, which connects over the user's own SSH credentials and opens the remote file with full edit authority. That is the right approach because KiroCrew grants nothing new — no write endpoint on the page or the agent; the write rides SSH, entirely outside KiroCrew's trust boundary.

The only missing piece is that the browser cannot know the user's SSH authority for the gateway host, so this adds two opt-in dashboard settings and one menu row:

  • dashboard.remote_editor.editor — an enum ("" off · vscode · kiro · cursor · windsurf), not a free string: the value is interpolated into a clickable custom-scheme URL, so an open string would let a config write mint a link to any registered protocol handler.
  • dashboard.remote_editor.host — charset-restricted to ^[A-Za-z0-9._@+-]*$ so it cannot inject path/query/authority structure into the generated URL.

Both keys ride the existing dashboard.terminal.* nested-sub-key pattern (schema flatten + _EDITABLE_CONFIG write gate). The /api/dashboard/branding payload carries remote_editor {editor, host} next to direct_local, and clamps both: an unknown editor or a non-charset-clean host becomes "" before it reaches the client, so a hand-edited config that slipped past the load-time schema can never produce a link. FilePathMenu (and the shared MarkdownPanel/FileViewer overflow menus that reuse its hooks) grow one Open in row, gated on !directLocal && editor !== "" && host !== "". Directories are allowed — a vscode-remote authority opens a directory as a remote workspace. A Remote editor card in Settings → Display (next to Terminal) sets the two keys.

Before → After, the file-path menu on a remote session:

Menu row Before After
Open with default app 🟥 hidden (remote) 🟥 hidden (remote)
Reveal in file manager 🟥 hidden (remote) 🟥 hidden (remote)
Open in <editor> 🟥 absent 🟩 shown when configured
Copy path 🟦 only real option 🟦 unchanged

🟩 added · 🟥 unavailable · 🟦 unchanged — a remote user now has a way into an editor instead of only "Copy path".

Tests

  • Backend (test/test_config_patch.py::TestRemoteEditor): editor enum accepts each valid value and "", rejects unknowns; host accepts valid authorities/aliases, rejects URL-structural characters (/ : ? #, whitespace) and over-length; the two sub-keys nest without clobbering each other.
  • Backend (test/test_config_schema.py): both keys flatten into first-class schema entries; the enum and host pattern/maxLength are present; the dict stays open.
  • Backend (test/test_dashboard_branding.py): branding is {"":""} by default, forwards a configured pair, and clamps an unknown editor and a dirty host to "" (keeping a valid editor when only the host is dirty).
  • Frontend (src/test/FilePathMenu.test.tsx): the row shows only on a remote session with editor+host set, is hidden when local / editor unset / host unset, is shown for a directory, and routes the exact vscode-remote URL through window.location on select. Plus remoteEditorUrl unit tests for URL shape, per-editor scheme, path percent-encoding, and null cases.

Manual verification

Verified the backend end-to-end against a temp config (load round-trip + branding clamp) and the frontend row/URL via the vitest suite above. Live click-through in a real remote session is covered by the unit-level URL assertion; N/A beyond that.

Screenshots / video

All frames are reproducible from the committed harnesses: node scripts/capture-remote-editor-settings.mjs (built SPA + shared stub) and node scripts/run-capture-with-vite.mjs scripts/capture-remote-editor-menu.mjs 6812 (isolated entry mounting the real MarkdownRenderer + FilePathMenu inside the real BrandingProvider, transport-stubbed as a remote session). Each harness asserts content and applied theme before shooting.

Settings → Display → Remote editor card — off (default), configured, light parity:

01-remote-editor-card-off-dark

02-remote-editor-card-set-dark

03-remote-editor-card-set-light

"Open in ‹editor›" menu row on a remote session — file chip with VS Code, a DIRECTORY chip with Kiro (the row is deliberately not file-gated: a directory opens as a remote workspace), light parity:

file-menu-vscode-dark

dir-menu-kiro-dark

file-menu-vscode-light

Live click-through result: verified on a real deployment — from a macOS client, code --remote ssh-remote+<cloud-desktop-fqdn> <path> (the exact command shape the menu row's vscode://vscode-remote/ssh-remote+<host><path> URL triggers) opened the remote gateway host's config file in local VS Code over the user's own SSH session and edits saved back to the remote host.

Related Issues

Fixes #11338

Related: #9411 (remote path-chip actions fail silently)

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

i18n notes

The new settings.display.remoteEditor.* keys are translated across all 11 locales. The i18n:check passthrough report's pre-existing untranslated-script counts (ru 110, zh-CN 116) predate this PR and are untouched by it.

@helenastafford
helenastafford requested review from a team and iamwhatever September 16, 2026 17:38
@helenastafford

Copy link
Copy Markdown
Contributor Author

Intent: Give a remote/headless-gateway session a way to open a file in the user's local editor over their own SSH creds, via an opt-in <scheme>://vscode-remote/ssh-remote+<host><path> link, so file-path menus no longer dead-end at "Copy path".
Not a goal: Adding any new write surface to the page or the agent (the edit rides SSH), supporting non-VS-Code-family editors, or opening files on a local (direct_local) gateway.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 16, 2026
@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

Design-level review of 5e98b662d9285ed8725c029a367d9455ba2813f6 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

Description promises cursor and windsurf editor support, but every enum in the diff ships only vscode and kiro.

Watch

  • Phantom description: the PR says the editor enum is "" · vscode · kiro · cursor · windsurf, but sections.py, _REMOTE_EDITOR_IDS, REMOTE_EDITORS, and the Settings select all carry only ["", "vscode", "kiro"] (only the eslint i18n allowlist names Cursor/Windsurf). A Cursor user following the description finds no option, and a hand-written "cursor" in config.json is silently clamped to off by the branding endpoint — the feature just vanishes with no error.
    Clears when: the description drops cursor/windsurf, or the two ids are added to the shared enum/allowlist with a scheme entry each.
  • The clickable handoff was verified by proxy: the description confirms code --remote ssh-remote+<host> <path> works, but the actual path — menu row → window.location.href = vscode://vscode-remote/... → browser scheme prompt → editor — was never clicked ("N/A beyond that"), and CI cannot exercise it. If the URL shape or the scheme prompt misbehaves, the feature's sole purpose dead-ends silently. Reversible (off by default), hence not a blocker.
    Clears when: one click of the menu row in a real remote session opens the remote file in the local editor.

[DESIGN-REVIEWED] 5e98b66

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — 🟡 CONCERNS

UX-level review of 5e98b662d9285ed8725c029a367d9455ba2813f6 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

Configuring an editor with the SSH host empty is a silent no-op — the menu row never appears and nothing in Settings says why.

Watch

  • The row renders only when !directLocal && editor && host (useRemoteEditorOpen), but the card never marks the host as required: a user who saves "VS Code" and skips the empty SSH host box gets no row and no cue. Moderate first-setup frequency, feature-looks-broken impact, persists until diagnosed. Smallest fix: an inline hint under the card when editor ≠ Off and host is empty ("Enter an SSH host to enable the menu row").
  • "Open in Kiro" collides with the app name: the blind reader said "I cannot tell whether 'Open in Kiro' opens something inside this app or launches a separate program." Mitigated because the row only exists after the user picked Kiro themselves in Settings — low frequency, worth a human sanity check rather than a change.

Suggestions

  • remote_editor_host_desc: the reader "would not know what to type" from "Hostname or ~/.ssh/config alias the gateway runs on." — append the anchor a shell user already has, e.g. "the name you'd use with ssh <host>".
  • remote_editor_editor_desc: "over your own SSH session" and "The link opens over your own SSH credentials." restate each other — drop the third sentence.

[UX-REVIEWED] 5e98b66

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 5e98b662d9285ed8725c029a367d9455ba2813f6 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The description ships a four-editor enum (vscode · kiro · cursor · windsurf); the code ships two — and the lint exemption whitelists the two phantom brands.

Not justified as shipped

  • Item 9 — zero consumers: the eslint exemption ^(?:VS Code|Kiro|Cursor|Windsurf)$ claims its brands render from "FilePathMenu.tsx REMOTE_EDITORS", but grep of that file for cursor|windsurf finds 0 matches; the shipped enum is ["", "vscode", "kiro"], contradicting the description's """ off · vscode · kiro · cursor · windsurf".
    Subtraction: shrink the regex to ^(?:VS Code|Kiro)$ in website/eslint.i18n.config.js.
    Clears when: the two alternatives are deleted, or those editors actually ship in REMOTE_EDITORS.
  • Item 10 — one consumer, generalized: run-capture-with-vite.mjs takes any <capture.mjs> <port>, but grep run-capture-with-vite across the repo finds only the file itself; the 584 existing capture harnesses run against a manually started vite (the pattern this PR's own menu harness documents in its usage comment).
    Subtraction: delete website/scripts/run-capture-with-vite.mjs and run the capture the way every sibling harness does.
    Clears when: a second capture harness invokes it, or the file is deleted.

What this change ships

Inventory (10 items) — 8 justified

Intent: let someone using the dashboard against a remote/headless gateway open a file in their local editor over their own SSH session — an ADDITION.

  1. File-path context menu gains "Open in ‹editor›" on remote sessions when configured — justified
  2. The same row appears in the chat panel's file overflow menu — justified
  3. The same row appears in the Files app viewer's overflow menu — justified
  4. New Settings → Display "Remote editor" card (editor picker + SSH host field); later cards shift down one slot — justified
  5. Two new config keys dashboard.remote_editor.{editor,host}, default off — justified
  6. /api/dashboard/branding response carries a server-clamped remote_editor pair — justified
  7. Both settings are findable from the command palette / settings search — justified
  8. Directory chips get the row too (opens as a remote workspace) — justified
  9. Lint config whitelists Cursor and Windsurf brand strings — zero consumers, and the description claims an enum the diff does not ship
  10. New generic run-a-capture-under-vite script — one consumer, generalized

[FIRST-PRINCIPLES-REVIEWED] 5e98b66

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 5e98b662d9285ed8725c029a367d9455ba2813f6 and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- website/src/components/FilePathMenu.tsx:183 -- REMOTE_EDITORS omits the promised Cursor and Windsurf options -> Fix: add both IDs to the changed allowlists and settings options.
[GPT-REVIEWED] 5e98b66

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 5e98b662d9285ed8725c029a367d9455ba2813f6: <one-sentence reason>

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 17, 2026
@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 5e98b662d9285ed8725c029a367d9455ba2813f6 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5e98b66

Verdict parsed from the review's SHA-scoped output markers for commit 5e98b662d9285ed8725c029a367d9455ba2813f6.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 5e98b662d9285ed8725c029a367d9455ba2813f6: <one-sentence reason>

@helenastafford
helenastafford force-pushed the feat/remote-editor-links branch from 8cf6bc9 to 69d5cdf Compare September 17, 2026 00:47
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 17, 2026
@helenastafford
helenastafford force-pushed the feat/remote-editor-links branch from 69d5cdf to 6442f42 Compare September 17, 2026 00:54
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 17, 2026
…inks (#11338)

Adds dashboard.remote_editor.editor (vscode/kiro, empty = off) and a
charset-clamped dashboard.remote_editor.host setting, exposed through the
branding payload beside direct_local. FilePathMenu, MarkdownPanel, and
FileViewer gain an "Open in <editor>" row gated on !directLocal && editor
&& host, building vscode-remote ssh-remote+<host><absolute path> links so
edits ride the user's own SSH credentials. Absolute-path guard rejects
relative paths that could graft onto the SSH authority. Settings > Display
gains a Remote editor card; i18n across all locales.

Closes #11338
@helenastafford
helenastafford force-pushed the feat/remote-editor-links branch from 6442f42 to cef86a0 Compare September 18, 2026 22:43
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 18, 2026
…nu row

Two committed harnesses so reviewers can reproduce the PR's evidence frames:

- capture-remote-editor-settings.mjs drives the REAL built SPA against the
  shared stub and shoots the Settings > Display "Remote editor" card in its
  off, configured, and light-parity states, asserting the applied data-theme
  matches each frame's name.
- capture/remote-editor-menu.{html,tsx} + capture-remote-editor-menu.mjs mount
  the real MarkdownRenderer + FilePathMenu inside the REAL BrandingProvider
  with only the transport stubbed (direct_local false, editor + host set), so
  the "Open in <editor>" row's gate is exercised rather than bypassed. Frames
  assert the row's presence per menu, including a DIRECTORY chip (the row is
  deliberately not file-gated: a directory opens as a remote workspace).
- run-capture-with-vite.mjs runs an entry-based harness against a temporary
  vite dev server, owning the child's lifecycle in-process.
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 18, 2026
@NicholasRBowers NicholasRBowers added needs-pr-triage PR scanner: awaiting automated triage drive-to-green PR claimed by drive-to-green pipeline and removed needs-pr-triage PR scanner: awaiting automated triage labels Sep 22, 2026
@NicholasRBowers

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca]: This PR has been inactive for 7+ days with failing CI. I've assessed the blockers and they appear resolvable — I'll push fixes directly to this branch as a co-author.

Assessment: No lane blocks this — GPT 5.6 and Opus 4.8 both pass with a single advisory finding between them, and 77 checks are green. Four things to settle, all mechanical or answerable:

  1. The one failing test is this PR's own Bengali string. Frontend Tests (2) is 1 failed of 8475: src/i18n/style/bnStyle.test.ts requires the reader be addressed as তুমি, never আপনি, and the new pages.settings.displayPanel.remote_editor_editor_desc in bn.json opens "আপনার নিজের SSH সেশনের…". Reword it to the তুমি register. Coverage Gate and Frontend Coverage Merge fail downstream of that shard, not on their own.
  2. Cursor and Windsurf are promised but not shipped — GPT's advisory finding, Design's Watch a02e5f2d2fc0 and First Principles item 9 are all the same gap: REMOTE_EDITORS is {vscode, kiro}, while the description and the new eslint brand allowlist ^(?:VS Code|Kiro|Cursor|Windsurf)$ name four. I'll take the smaller complete fix the FP item offers — drop the two unshipped names from the allowlist and the description — rather than adding editor support this PR didn't build.
  3. Conflict is wide but shallow: 18 files, of which 13 are locale-file insertion collisions, two are generated (settings-registry.generated.json, settingsRegistry.gen.ts — regenerated, not hand-merged), plus one hunk each in docs/feature-map/README.md and DisplayPanel.tsx.
  4. The remaining lane items get dispositions or small edits: the two UX copy suggestions, the "host not marked required so the row silently never renders" Watch, and FP item 10's zero-consumer run-capture-with-vite.mjs.

One I can't close myself: Design's Watch 9d6734b4df4b wants one real click of the menu row in a live remote session, and this host has no remote gateway with a local editor and browser scheme handler. That lane is advisory (CONCERNS), so I'll answer it with an evidence-backed disposition rather than claiming a verification I didn't perform — if you have run it end to end, say so on the thread and it closes properly.

If you'd prefer I don't touch this PR, add the pr-no-autofix label.

@jcjaskula-aws jcjaskula-aws left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this. It matches a setup I use daily: a headless gateway, with the dashboard opened from a laptop over an ssh -L forward. I've worked on something quite similar locally (opening transcript path chips in the attached Kiro IDE from the file-path menu), and ran into the two issues below along the way, see the inline comments.

The branch is now conflicting and has had no commits since 09-18. If it helps, I'm happy to take this PR over: rebase it and address these two points. Just say so.

// Remote gateways only; a local (or origin-unknown) session uses the OS
// open/reveal rows instead. `!remoteEditor` guards a branding value that has
// not loaded yet or a partial test stub that omits the field.
if (directLocal || !remoteEditor) return null

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With a browser that reaches the gateway through an SSH port forward, this hides the row in exactly the topology #11338 targets. The request arrives on loopback, so direct_local is true even though the gateway host has no desktop, and useRemoteEditorOpen returns null.

The same thing affects the issue's premise that Open with default app / Reveal "degrade to Copy path" on remote sessions. Through a tunnel they don't degrade: they render, and clicking them falls back to a clipboard copy, because nothing checks whether the host has a launcher.

What fixed both for me was gating on whether the host can actually launch something (a stat of the binary the launcher would spawn: xdg-open / open / explorer.exe, never spawning it to find out) instead of on locality.

*/
export function remoteEditorUrl(editor: string, host: string, absPath: string): string | null {
const entry = REMOTE_EDITORS[editor]
if (!entry || !host || !absPath || !absPath.startsWith('/')) return null

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Transcript chips often carry ~/… or repo-relative paths. Those currently lose the row without any feedback.

Expanding ~ and anchoring relative paths to the session's project directory worked well for me, provided the sensitive-path screen runs again on the resolved form. For example, .ssh/id_rsa passes the screen as written and only matches once it's anchored.

Copy link
Copy Markdown
Contributor

PR triage (2026-10-05): REBASE + merge discussion. No close, no request-changes.

@jcjaskula-aws

Copy link
Copy Markdown
Contributor

@helenastafford are you still planning to work on this one? It's now quite far behind main (see the 10-05 triage above), and it's a feature I'd like to see land.

If you're short on bandwidth, I'm happy to take it over: rebase onto current main keeping your commits and authorship, then address the open items from the triage and my review above. Just let me know either way, and if I don't hear back in a week or so I'll open a follow-up PR that builds on your branch and credits you.

@helenastafford

Copy link
Copy Markdown
Contributor Author

Superseded by #19557. That PR is this change rebased onto current main, with two redesigns: the row is no longer hidden on direct-local sessions (an ssh -L forward reads as direct-local, as @jcjaskula-aws and the triage pointed out), and Remote editor is now its own pane in the split Display settings. I couldn't push here because this PR's head branch lives in kirodotdev/KiroCrew and my account now has only read access, so the new PR comes from my fork.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 12, 2026
@mbriones98 mbriones98 removed the drive-to-green PR claimed by drive-to-green pipeline label Oct 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Open remote files in a local editor (vscode://kiro:// ssh-remote links) from file-path menus

5 participants