Skip to content

feat(session-environments): copy a remote session's skills into its workspace - #34302

Open
kyleseaman wants to merge 2 commits into
mainfrom
feat/remote-session-skills
Open

kyleseaman wants to merge 2 commits into
mainfrom
feat/remote-session-skills

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: In a remote session, the skills its agent can use are in the workspace too, so python3 <skill dir>/scripts/x.py runs there as it does locally.

A remote session's agent reads its skills on the gateway (the skills index, skill_search, KAS's own skill tool), but every command it runs goes to the workspace. A skill's scripts/, references/ and assets never reach that machine: an agent in a Coder session reported it could read the kirocrew-prepare-pr instructions but could not run preflight.py, push_guard.py, diff_signals.py, local_review.py or pr_status.py. src/kiro_crew/remote_session/ and src/kiro_crew/coder/ have no skill handling on main.

Why it matters

Any skill that ships a script is half-usable in a remote session: the agent follows instructions it cannot carry out, then improvises around the missing script or stops. The PR loop itself is one of these skills.

Not a goal

  • The workspace's Python version (a Coder dev template is being built separately). This PR only makes an old interpreter visible.
  • The gh proxy for GitHub API calls from the workspace (a sibling PR).
  • Refreshing the copy mid-turn when a skill is edited; it is refreshed at every start.
  • Copying project skills: they live in the repository the workspace checks out.

What changed (motivation → approach → change)

At every runtime start of a remote session (new, resumed, workspace or engine restart), before the engine starts, the gateway copies the skills that session's agent may see into its workspace, read-only, and every skill path the agent is shown names that copy.

  • Which skills (an allowlist): what a KAS start of that session's spec loads (acp/kas_skill_scope.loaded_skill_files, shared with refused_skill_copies; a checkout's spec cannot widen it), and only skills whose resolved folder sits strictly inside Crew's own skill folders: the Crew skills dir, ~/.kiro/skills, or an app's <app>/skills/<name>. A linked allowed folder is refused. A skill mapped from elsewhere still loads but is not copied, and is named with the reason.
  • What is copied: each skill folder's regular files, walked by descriptor (pinned_fs). The folder and SKILL.md identity judged at selection are what is read; nothing is resolved again. A skill is dropped whole, and named, if it holds host state, a path the sensitive-path fence or is_unsafe_prompt_path refuses, a recognisable credential (content or name), or a config file with a labelled password. Left out per file: links, hidden files, nested skills, credential file names, files over 1 MiB; 32 MiB in total.
  • How: one command over the session's existing shell (coder ssh), bytes on stdin like the worker files. No new port, no credential. A new guest script, skills_install.py, writes ~/.kirocrew-worker/skills/<digest>/<skill key>/ and renames it into place. Unchanged sets are reused and shared.
  • What the agent sees: a [SKILLS] line every turn naming the copy, rewritten paths in the skills index, and a skill_search read that names the skill's folder in the workspace (or says it was not copied).
  • Old Python: the guest reports its python3 version and any copied .py that will not compile. The [SKILLS] line and the card name an interpreter older than the gateway's and the count of copied scripts that do not compile there.
  • Transparency and the switch: the environment chip's card gets a Skills row (count, path, left-out files, the workspace's python3 when older, and, as an error notice with the agent hand-off, how many copied scripts do not compile on it). Settings > Session Environments gets Copy skills to the workspace (session_environments.copy_skills, default on). Off, nothing is copied and the agent is told.

Session Environments stay behind KIROCREW_DEV_MODE.

Where: remote_session/skills_copy.py and skills_install.py (new); the scope read in agent_sdk/kas_skill_view.py (new, listed in the admission-path ratchet as a non-start reader) and the shared classifier in acp/kas_skill_scope.py (KAS start behaviour unchanged; a parity test runs both callers over one fixture set); the start hook in providers/acp_runtime_start.py; context in context_assembly/inclusion.py, session_start.py and turn.py; the read route in dashboard/handlers/prompts_skill_catalog.py and mcp_tools/skills.py; the card's data in dashboard/handlers/session_environments.py; the key in config/sections_session.py, config/session_environments.py, dashboard/handlers/core_config_*.py, change_card_catalog_kinds.py (on widens) and the regenerated config-baseline.json and src/kiro_crew/docs registries; UI in website/src/components/EnvironmentHealthCard.tsx, website/src/pages/settings/SessionEnvironmentsCard.tsx, website/src/api/client.ts, strings in all website/src/i18n catalogs, tests in website/src/test.

Backwards compatibility

Compatible: copy_skills is a new optional key that defaults on; sessions without a remote workspace are unchanged.

Removes nothing: the diff adds a config key, a guest file, context lines and a UI row; no key, path or reader is taken away.

Tests

  • test/test_remote_session_skills_copy.py: the repro (the real kirocrew-prepare-pr folder copied through a guest shell, push_guard.py --help exits 0 there, pr_status imports), each refusal (symlink out, a folder swapped for a link mid-walk, hard link out, a FIFO, a credential in a binary file or base64-encoded, a name the guest refuses, SKILL.md link, hidden/credential name/credential content, file over the cap, nested skill, total cap, unsafe key, guest path escape, guest size bound, guest reports that do not name this copy), the scope (a mapped agent gets only its skill; a checkout spec of the same name cannot widen it; an inheriting custom agent gets ~/.kiro/skills; a crewmate's worker gets its crewmate's merged scope; a whole-catalog agent also gets the KAS tree; a catalog still building is waited for, never taken as complete, and a read taken before it finished is read again), a folder left by a killed install not blocking the next one, ended sessions' records evicted before a live one's, reuse with no transfer, an edited skill (new copy, old one intact), two sessions on one workspace, a workspace that lost its copy, the switch off, a failed copy, an old interpreter (python3.7), the [SKILLS] line, the index rewrite, and the skill_search read route.
  • The allowlist and host secrets: a fake home with a secret in every host-state location; a credential store linked to a mapped folder; an endorsed-config root; an app's top level and config/ beside skills/; an app skills linked out; a linked skills folder; the opened root checked on its descriptor; config files with a password (UTF-16/32, backup suffixes); a credential in a file or folder name; prose and code that only mention a password still copy. On this host's catalog, 111 of 112 skills copy; 1 holds a config password.
  • Each refusal was removed alone and its test turned red.
  • test_remote_git_governance.py: the start path calls the copy with the session key, the template agent and the launch's shell, and a start cancelled during the copy closes the workspace relay (providers/acp_runtime_start.py).
  • test_session_environment_handlers.py: the health card reports the copy and the switch-off state.
  • Config tests: copy_skills validation, lenient load, the leaf write, and a whole-section save that omits a hand-edited value keeps it off.
  • Vitest: the chip card's Skills row (including the count of scripts that do not compile, red without the card change) and the Settings switch.
  • Determinism: 20 runs at -n0, 10 at -n 4 --dist loadgroup beside test_remote_session_launch.py and test_session_environment_handlers.py, and a shuffled order (seed 26073, 53 passed), all green.

Proof: not provable -- other: new feature with no prior behavior to revert to; refusal tests were mutation-checked instead.

Manual verification

Not run against a live Coder workspace; the guest side is exercised end to end through a temporary-HOME shell running the same commands coder ssh would.

Screenshots / video

Settings: Copy skills to the workspace

Environment card: skills copied, older Python, a skill outside Crew's folders and two holding a config password named

Environment card: copying switched off

Environment card: the Skills row says the copy failed, with the agent hand-off

Related Issues

No issue: tracking issues are opened only on the owner's request.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (providers.md Skills in the workspace, config.md)
  • No secrets, credentials, or internal references in the diff

@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners November 10, 2026 03:16
@kyleseaman
kyleseaman requested a review from CrysisDeu November 10, 2026 03:16
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 10, 2026
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 32dd0c88dc4b567082cbf0b12f4a673f28f0b255 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: remote sessions only run on KAS (check_remote_workspace_supported), so taking the copy's scope from KAS is right, and the copy is best effort, has a time limit and can be switched off.

Notes

  • copy_for_session runs inline before the engine starts, under COPY_TIMEOUT_SECONDS = 90.0, so a slow coder ssh can add up to 90s to every start or resume. Starting the engine at the same time and posting [SKILLS] from the first turn after the copy finishes would remove that wait.

[DESIGN-REVIEWED] 32dd0c8

Description read

[DESCRIPTION-READ] c2cf2418577087e9e69d1147348d7a37cda62bff4b5cbda709d6857f484d158f

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 32dd0c88dc4b567082cbf0b12f4a673f28f0b255 — 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 does not.

First-Principles-Verdict: PASS

Copying skills into the workspace answers a reported defect (a Coder agent could not run preflight.py/push_guard.py), and the repro test shows it. The safety layers stacked under the allowlist are heavier than that harm needs.

Notes

  • Item 7 — duplicate of src/kiro_crew/security/redaction_structured/table.py (labelled.secret): _labelled_secret builds its own _SECRET_LABELS/_CONFIG_PAIR/_SPLIT_PAIR table even though _holds_credential already runs scan(), which applies that row. Its docstring says "Upgrade to a shared label detector once security offers one", but that detector already exists. Subtraction: delete _labelled_secret and its regexes, and rely on scan() hits.
  • Item 8 — oversized: _holds_host_state (rule (b)) is labelled "defence in depth below the allowlist". Rule (a) already limits skill roots to Crew skill folders, and the PR names no root that passes (a) but encloses host state. Subtraction: delete _holds_host_state and _host_homes, and keep the allowlist (a). Clears when: the mechanism is removed, or a human amends the Goal.

What this change ships

Inventory (10 items) — 8 justified

Intent: let a remote session's agent run its skills' scripts in the workspace, as it can locally. This is a FIX.

  1. At each remote runtime start, the agent's in-scope Crew skills are copied read-only into the workspace — justified
  2. Settings switch "Copy skills to the workspace" (copy_skills, default on, dev mode only) — justified
  3. A [SKILLS] context line every turn names the copy — justified
  4. Skill paths in the skills index point at the workspace copy — justified
  5. A skill_search read names the skill's folder in the workspace, or says it was not copied — justified
  6. The environment chip's card gets a Skills row (count, path, left-out files) — justified
  7. A skill holding a config password is dropped by a new label scanner — duplicate of security/redaction_structured/table.py
  8. A skill whose root encloses host state is refused, beneath the allowlist — oversized
  9. An older workspace python3 and the count of copied scripts that do not compile there are shown to the agent and on the card — justified
  10. The KAS skill classifier is shared with the copy (loaded_skill_files, digest-bound verdicts), and a new guest installer ships — justified

[FIRST-PRINCIPLES-REVIEWED] 32dd0c8

Description read

[DESCRIPTION-READ] ab86184039bc81007fa3bd19524bf058fe94a935df81d7dcb4c8cbf511d9430e

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 32dd0c88dc4b567082cbf0b12f4a673f28f0b255 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks. The four screenshots cover the new Settings switch and the Skills row's copied, off and failed states, and the blind reader read each one correctly.

Notes

  • skillsFailed: "retried when this chat next starts" left the reader asking "Do I have to close it and reopen it?" Name what triggers the retry, e.g. "Skills weren't copied. Crew tries again the next time this workspace starts."
  • skillsIncompatible shows only a count ("…don't compile on python3 3.10.12: 2"), and the reader said "It doesn't say which two." Send the script names from the gateway and list them by folder name, the way skillsOutside and skillsSecret already do.
  • skillsOff: "Not copied (off in Settings)" gives a reason but no way to act on it. The reader wanted it to link to the setting. Make "Settings" a link to Settings > Session Environments.

[UX-REVIEWED] 32dd0c8

Description read

[DESCRIPTION-READ] 15fd4d48cd7be33b0ee37ce1cf05e9f1cf3320c64fe63e0e0b4b4c9392c17bee

That sha256 names everything this verdict read: the PR description, plus the 7 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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — 🔴 changes requested (blocking)

Reviewed 32dd0c88dc4b567082cbf0b12f4a673f28f0b255 — this comment is updated in place on each push.

BLOCKING: the YAML block-scalar scan in the skill copy gets quadratically slower as a skill's config file grows. One 1 MiB config file in a skill, which can come from a third party, pushes every remote session start past the 90-second copy deadline. The copy then fails, and the worker thread keeps the CPU busy for minutes afterwards.

BLOCKING — src/kiro_crew/remote_session/skills_copy.py:387
rest = text[header_end:].split("\n")[1:]
Trigger: A skill in the session's scope holds a .yaml file of up to MAX_FILE_BYTES (1 MiB) made of repeated a: | lines, about 200k block-scalar headers. Skills installed from a registry or an app are external content. The call path is copy_for_session → asyncio.to_thread(plan_copy) → _skill_files → _config_file(name) and _labelled_secret(data) → _config_values. _CONFIG_PAIR matches every a: |, and _BLOCK_SCALAR accepts |. So _block_value runs once per header, and each run copies and splits the whole rest of the file, even though the loop stops on the very next line. It also runs before the key is checked against _SECRET_LABELS.
Outcome: That is roughly 10^11 bytes of slicing and about 2·10^10 string objects, which takes minutes of CPU. wait_for(copy(), COPY_TIMEOUT_SECONDS) fires and the session is recorded as FAILED. The to_thread worker can't be cancelled, so it keeps holding the GIL and slows the gateway loop. Every later start of any session with that skill in scope does the same again, and the abandoned threads pile up.
Anchor: defect
Fix: Walk the lines forward from header_end with text.find("\n", pos) and stop at the first non-blank line that is no deeper than the key's indent, instead of re-splitting the rest of the text. Or only compute the block value when the normalised key is in _SECRET_LABELS.

[BLOCK-MERGE] 32dd0c8
[OPUS-REVIEWED] 32dd0c8

Verdict parsed from the review's SHA-scoped output markers for commit 32dd0c88dc4b567082cbf0b12f4a673f28f0b255.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 32dd0c88dc4b567082cbf0b12f4a673f28f0b255 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 32dd0c88dc4b567082cbf0b12f4a673f28f0b255 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 32dd0c8

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 32dd0c88dc4b567082cbf0b12f4a673f28f0b255 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 10, 2026
@kyleseaman
kyleseaman force-pushed the feat/remote-session-skills branch from ef3b140 to b7d51dd Compare November 10, 2026 04:46
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 10, 2026
@kyleseaman
kyleseaman force-pushed the feat/remote-session-skills branch from b7d51dd to 1edceb6 Compare November 10, 2026 05:39
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge 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 Nov 10, 2026
@kyleseaman
kyleseaman force-pushed the feat/remote-session-skills branch from 1edceb6 to e18b6e5 Compare November 10, 2026 06:51
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 10, 2026
@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 Nov 10, 2026
@kyleseaman
kyleseaman force-pushed the feat/remote-session-skills branch from e71e64e to 4875448 Compare November 11, 2026 01:47
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 11, 2026
@kyleseaman
kyleseaman force-pushed the feat/remote-session-skills branch from 4875448 to 0c57060 Compare November 11, 2026 04:36
@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 Nov 11, 2026
@kyleseaman
kyleseaman force-pushed the feat/remote-session-skills branch from 0c57060 to 2da9b8c Compare November 11, 2026 11:55
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention labels Nov 11, 2026
@kyleseaman
kyleseaman force-pushed the feat/remote-session-skills branch 4 times, most recently from 6f5be1b to 85158ca Compare November 11, 2026 14:54
@github-actions github-actions Bot added 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: checking Automated validation is still running labels Nov 11, 2026
@kyleseaman
kyleseaman force-pushed the feat/remote-session-skills branch from 85158ca to 3724e96 Compare November 11, 2026 17:33
kyleseaman and others added 2 commits November 17, 2026 23:38
The config label scan read only a value on the key's own line, so a YAML
block scalar (password: |-), a JSON value after a line break and a TOML
triple-quoted string were seen as empty and the password was copied to the
remote workspace. Each is now decoded before the existing value check, which
keeps its placeholder and empty-value exemptions.
@iamwhatever

Copy link
Copy Markdown
Contributor

Stale-PR cleanup note. I rebased this onto main and fixed the GPT security finding (multiline secret values) in 32dd0c8. Opus now flags a new problem in that same fix: _block_value re-splits the rest of the file for every block-scalar header, so a 1 MiB YAML of a: | lines is quadratic. By the cleanup's one-fix-round rule I am stopping here. Suggested fix for @kyleseaman or a maintainer, in _config_values: only decode a block scalar when the key is secret-labelled (re.sub(r"[-_.]", "", match.group(1).lower()) in _SECRET_LABELS), and in _block_value walk forward with text.find("\n", pos) and stop at the first non-blank line no deeper than the key, instead of text[header_end:].split("\n").

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants