296 lines
18 KiB
Markdown
296 lines
18 KiB
Markdown
---
|
|
spec: docs/specs/tasks/system-design/attach-workspace-sources.md
|
|
created: 2026-07-22
|
|
status: completed
|
|
---
|
|
|
|
# Implementation Plan: Attach Workspace Sources
|
|
|
|
## Overview
|
|
|
|
Add a durable task-level source attachment contract above the current worktree-only branch flow,
|
|
then teach host and remote runtimes to materialize the same source set. Reuse the task-create
|
|
repository controls inside a dedicated responsive Files-panel picker, publish live source/root
|
|
updates through the existing task/session data flow, and finish with desktop, mobile, Docker, and
|
|
SSH coverage. The plan preserves `task_repositories` for Git behavior and introduces a separate
|
|
folder attachment relation, as required by
|
|
[ADR-2026-07-22-runtime-mutable-task-workspace-sources](../../decisions/2026-07-22-runtime-mutable-task-workspace-sources.md).
|
|
The active UX delta extracts the task-create source-mode presentation into a controlled shared
|
|
selector, presents **Local** and **Remote** modes inside Add sources, and combines **Add sources**
|
|
with **Open workspace folder** in one Files-toolbar action menu without changing the durable source
|
|
union or materialization contract.
|
|
|
|
---
|
|
|
|
## Backend
|
|
|
|
### Persistence and source projection
|
|
|
|
- Add `TaskWorkspaceFolder` to `apps/backend/internal/task/models/models.go` with task ownership,
|
|
canonical host path, collision-safe display name, global source position, and timestamps.
|
|
- Add `task_workspace_folders` to both the base schema and replayable migrations in
|
|
`apps/backend/internal/task/repository/sqlite/base_schema.go` and `base_migrations.go`; enforce
|
|
task/path and task/display-name uniqueness, cascade deletion, and task/position lookup indexes.
|
|
- Extend `apps/backend/internal/task/repository/interface.go` and add a focused SQLite repository
|
|
file for folder CRUD plus a transactional batch that creates repository/folder attachments and a
|
|
compensating batch that removes only rows created by the failed operation.
|
|
- Extend `Task`, `TaskDTO`, `pkg/api/v1.Task`, boot/snapshot queries, and `task.updated` serialization
|
|
with `workspace_folders`. Build a combined ordered source projection without changing existing
|
|
repository DTOs or Git consumers.
|
|
- Allocate positions under the existing per-task mutation lock using the maximum across repository
|
|
and folder rows. Reject runtime-name collisions across both tables after applying the same
|
|
directory-name sanitizer used for multi-repository worktrees.
|
|
|
|
### Attachment service
|
|
|
|
- Add `apps/backend/internal/task/service/service_workspace_sources.go` with
|
|
`AttachWorkspaceSources(ctx, request)` and typed repository/folder input/result shapes.
|
|
- Validate the whole batch before writes: task exists and is repository-backed; workspace ownership;
|
|
exactly one repository locator; provider-neutral URL and identity consistency; canonical explicit
|
|
local Git paths; canonical arbitrary directories; branches; duplicates; display-name collisions;
|
|
and idle session/turn state.
|
|
- Resolve or create repository entities through the existing `ResolveRepositoryRef` path so local
|
|
trust and remote credential rules stay authoritative. Track newly created repository entities for
|
|
rollback without deleting pre-existing workspace repositories.
|
|
- Persist the batch, call the runtime materializer synchronously, and compensate database plus owned
|
|
filesystem/runtime entries on failure with a detached bounded context. Publish `task.updated` only
|
|
after both persistence and materialization succeed.
|
|
- Refactor `AddBranchToTask` into a compatibility adapter over a one-item repository-source request;
|
|
retain its existing auto-branch naming, duplicate, and slug-collision behavior.
|
|
|
|
### HTTP, WebSocket, and MCP contracts
|
|
|
|
- Register `POST /api/v1/tasks/:id/workspace-sources` in
|
|
`apps/backend/internal/task/handlers/task_handlers.go`; define the discriminated source request in
|
|
`task_http_handlers.go`, map typed service errors to `400`/`404`/`409`/`422`, and return the durable
|
|
source projection, effective workspace path, and affected sessions.
|
|
- Add `workspace.sources.updated` / `session.workspace_sources_updated` event constants and gateway
|
|
routing in `internal/events/types.go`, `pkg/websocket/actions.go`, and
|
|
`internal/gateway/websocket/task_notifications.go`. Emit only after agentctl has adopted the root.
|
|
- Register `add_workspace_sources_kandev` in `internal/mcp/server/server.go` and its backend handler
|
|
in `internal/mcp/handlers/handlers.go`; default `task_id` to the current task and accept the same
|
|
batch union as HTTP. Keep `add_branch_to_task_kandev` externally compatible while routing it
|
|
through the generalized service.
|
|
|
|
### Host materialization
|
|
|
|
- Replace the narrow `BranchMaterializer` hook in `internal/task/service/service.go` with a
|
|
`WorkspaceSourceMaterializer` batch interface, retaining a thin compatibility adapter for tests
|
|
and existing call sites.
|
|
- Refactor `internal/backendapp/branch_materializer.go` into host source materialization that reuses
|
|
`worktree.Manager` for repository branches and creates a Kandev-owned task root for mixed local
|
|
sources. Link live local sources into that root with platform-native directory links (Unix
|
|
symlinks, Windows directory junctions), while validating the canonical target before and after
|
|
link creation.
|
|
- Never copy, move, delete, or write marker files into user-owned local sources. Rollback and task
|
|
cleanup remove only Kandev-owned worktrees, links, and task roots.
|
|
- Extend lifecycle workspace rebinding so an idle Local execution can restart/rebind at the mixed
|
|
source root without losing its task conversation; Worktree executions keep their existing live
|
|
sibling materialization path. Persist the promoted `task_environments.workspace_path` for future
|
|
sessions and resets.
|
|
- Generalize agentctl rescan from repository-only reconciliation to workspace-source reconciliation:
|
|
update the workdir, rebuild repository trackers for Git entries, refresh file-tree scope for plain
|
|
folders, and fail the attachment if the running agentctl cannot adopt the new root.
|
|
|
|
### Container and remote materialization
|
|
|
|
- Add authenticated agentctl endpoints and client methods for validated repository clone/checkout
|
|
materialization under the current workspace root.
|
|
- Route local Docker, SSH, and Sprites attachments through their live `AgentExecution` agentctl
|
|
client. Reuse existing executor credential resolution for repository clones; do not persist or log
|
|
tokens or credentialed URLs.
|
|
- Reject folder inputs for Docker, SSH, Sprites, and remote Docker during service capability
|
|
validation, before persistence or executor filesystem access. The frontend uses the same executor
|
|
capability to omit the folder source kind.
|
|
- Make subsequent launch/reset preparation derive every repository from the durable source
|
|
projection. Remove the task-create frontend guard that forces multi-repository work to Worktree
|
|
only after the corresponding runtime launch paths support repository projection.
|
|
- Add the same materializer capability to the remote-Docker interface and tests; the executor remains
|
|
unavailable until its existing `CreateInstance` implementation is completed.
|
|
|
|
---
|
|
|
|
## Frontend
|
|
|
|
### Shared source picker
|
|
|
|
- Extract reusable repository selection leaves from
|
|
`task-create-dialog-workspace-repo-chips.tsx`, `task-create-dialog-remote-repo-chip.tsx`,
|
|
`task-create-dialog-remote-repo-chips.tsx`, and `folder-picker.tsx` into
|
|
`components/workspace-source-picker/` without changing the task-create dialog behavior.
|
|
- Keep `task-create-dialog-source-mode.tsx` scoped to task creation. Add sources does not reuse its
|
|
segmented mode switch: it presents one **Add repository** menu whose choices append workspace,
|
|
local-Git, or remote rows without changing the visibility of configured rows.
|
|
- Add typed mixed rows (`repository`, `remote_repository`, `folder`) and a
|
|
`useWorkspaceSourcePickerState` hook. **Workspace repository** reuses the combined
|
|
saved/discovered repository selector; **Local Git repository** exposes the local path affordance;
|
|
**Remote repository** reuses provider-backed and pasted-URL controls. **Add folder** remains
|
|
adjacent when supported. Appending rows never removes configured rows, so one submission can mix
|
|
source kinds on Local/Worktree. Executor capability removes the folder affordance on
|
|
container/remote tasks.
|
|
- Decouple reusable remote-row presentation from create-task-only `DialogFormState`; keep branch,
|
|
provider metadata, discovery, validation, and payload conversion owned by the consuming dialog.
|
|
- Add `attachTaskWorkspaceSources` to `lib/api/domains/kanban-api.ts`, source types to
|
|
`lib/types/http.ts` and the kanban slice, and unit-tested payload/error normalization.
|
|
- Once backend runtime support lands, delete the non-Worktree multi-repository disable resolver and
|
|
auto-switch effect in `task-create-dialog-computed.ts` and
|
|
`task-create-dialog-multi-repo-guard.ts`; keep the no-repository Worktree restriction.
|
|
|
|
### Files panel surface and live state
|
|
|
|
- Replace the separate **Add sources** and **Open workspace folder** toolbar controls with one
|
|
labeled/icon **Workspace actions** trigger in `file-browser-toolbar.tsx`, threaded through
|
|
`file-browser.tsx`, `files-panel.tsx`, `task-files-panel.tsx`, and their hooks. Its dropdown menu
|
|
contains both actions. Keep the trigger enabled whenever opening the workspace folder is valid;
|
|
disable only the **Add sources** row for archived/non-repository tasks, active turns/tool calls,
|
|
or loading source state, and render the reason as visible menu copy.
|
|
- Build `components/task/add-workspace-sources/` around the shared picker. Desktop uses a Dialog;
|
|
phone uses a full-height Drawer with fixed header/footer, `min-h-0` internal scrolling,
|
|
`100dvh` sizing, safe-area bottom padding, and a single submit action. Preserve keyboard focus,
|
|
Enter behavior, dismissal, pending state, per-source errors, retryable batch contents, and rows
|
|
configured from every repository or folder kind.
|
|
- Coordinate Radix menu close autofocus before opening the controlled Dialog/Drawer so dismissal
|
|
returns focus to the workspace-actions trigger. On phones, use the existing responsive
|
|
`DropdownMenu` bottom-sheet treatment rather than introducing a second action-menu drawer.
|
|
- Subscribe to `task.updated` for repository/folder state and
|
|
`session.workspace_sources_updated` for the adopted workspace root. Update the kanban/session
|
|
slices, reset the file-tree cache for affected environment/session IDs, and let existing
|
|
repository/worktree handlers refresh Changes and editor pickers.
|
|
- Keep the new phone entry point visible and touch-usable (at least 44px active dimension) without
|
|
hiding any source kind supported by the task's executor. The closest shipped mobile exemplar is
|
|
`components/task/mobile/mobile-picker-sheet.tsx`; reuse its focused picker hierarchy while using a
|
|
full-height surface because mixed rows, branch search, validation, and batch errors can be deep.
|
|
|
|
### Mobile design contract
|
|
|
|
- **Desktop outcome:** one compact labeled/icon Files-toolbar trigger opens a dropdown with **Add
|
|
sources** and **Open workspace folder**. Selecting Add sources opens the multi-row dialog and
|
|
refreshes the workspace tree after one atomic submission.
|
|
- **Mobile entry point:** the same workspace-actions trigger is visible in the Files toolbar with an
|
|
actual 44px touch target. The shared responsive DropdownMenu becomes a short inset bottom-sheet
|
|
action menu; it does not depend on hover, context click, or desktop Dockview chrome.
|
|
- **Hierarchy and primary action:** the action menu chooses between workspace actions. The Add
|
|
sources surface then exposes one **Add repository** control and, when supported, **Add folder**.
|
|
Repository location is a temporary menu choice; configured rows and validation own the single
|
|
scroll body. Cancel and **Add to workspace** stay fixed in the footer, with submit as the sole
|
|
primary action and disabled until a row exists.
|
|
- **Presentation rationale:** the two workspace actions are a short temporary choice, so they fit
|
|
the shared inset menu. Source attachment can contain several searchable, branch-aware rows, so it
|
|
continues into a full-height Drawer rather than stacking the full form inside that menu.
|
|
- **Shared versus responsive:** source state, validation, payload construction, picker leaves, and
|
|
API calls are shared. Add sources owns its tab-free source-kind menu. Only Dialog/Drawer
|
|
composition, responsive menu treatment, and toolbar hitbox treatment differ.
|
|
- **Geometry:** one internal vertical scroll owner, dynamic viewport height, safe-area clearance,
|
|
44px phone triggers/menu rows, contained repository popovers/drawers, and no document horizontal
|
|
overflow.
|
|
|
|
---
|
|
|
|
## Tests
|
|
|
|
- **What:** folder persistence, canonical uniqueness, cross-table display-name/position allocation,
|
|
cascade deletion, and SQLite/Postgres replay safety.
|
|
**File:** `internal/task/repository/*workspace_source*_test.go` and
|
|
`internal/task/repository/sqlite/*workspace_folder*_test.go`.
|
|
**How:** real database tests, including migration replay.
|
|
- **What:** valid mixed batches, repository resolution, idle gate, duplicate/cross-workspace/path
|
|
failures, partial materialization rollback, client cancellation, and legacy add-branch parity.
|
|
**File:** `internal/task/service/service_workspace_sources_test.go` and existing branch tests.
|
|
**How:** table-driven service tests with real SQLite plus fake materializer failure injection.
|
|
- **What:** HTTP status mapping, MCP current-task defaulting and batch forwarding, event truthfulness,
|
|
and compatibility tool behavior.
|
|
**File:** task handler, MCP handler/server, gateway, and service event tests beside the source.
|
|
**How:** HTTP/WS integration tests and MCP captured-payload tests.
|
|
- **What:** host root promotion, link safety, Windows/Unix path behavior, idle restart/rebind,
|
|
agentctl source rescan, rollback, and relaunch reconstruction.
|
|
**File:** `internal/backendapp/workspace_source_materializer_test.go`, lifecycle tests, and agentctl
|
|
process/API tests.
|
|
**How:** temporary Git repositories/folders plus fake lifecycle clients; platform-specific tests
|
|
where link semantics differ.
|
|
- **What:** Docker/SSH/Sprites repository clone transport, unsupported-folder rejection, credential
|
|
redaction, cancellation, cleanup, and reset reconstruction.
|
|
**File:** lifecycle executor tests and agentctl workspace-source API tests.
|
|
**How:** table-driven unit/integration tests with fake agentctl plus existing container harnesses.
|
|
- **What:** mixed picker state, payload construction, duplicate errors, disabled busy state,
|
|
task/session event merges, and file-tree cache reset.
|
|
**File:** focused `*.test.ts(x)` files beside the new picker, API helper, toolbar, and WS handlers.
|
|
**How:** Vitest and Testing Library.
|
|
- **What:** task creation keeps its existing mode presentation while Add sources renders no
|
|
Local/Remote tabs, appends mixed rows from one repository menu, and provides 44px mobile choices.
|
|
**File:** `task-create-dialog-repo-chips.test.tsx`,
|
|
`add-workspace-sources-dialog.test.tsx`, and a focused shared-mode component test.
|
|
**How:** Testing Library controlled-state and responsive-geometry assertions.
|
|
- **What:** one workspace-actions trigger exposes both actions, keeps Open workspace folder enabled
|
|
when Add sources is disabled, shows the disabled reason, and hands focus to/from the source
|
|
surface.
|
|
**File:** a focused test beside `file-browser-toolbar.tsx`.
|
|
**How:** Testing Library menu interaction and callback assertions.
|
|
|
|
## E2E Tests
|
|
|
|
- **Scenario:** GIVEN an idle one-repository worktree task, WHEN a desktop user adds a second local
|
|
repository and a plain folder through **Workspace actions → Add sources**, THEN both
|
|
top-level entries appear and only the repository appears in Changes.
|
|
**File:** `apps/web/e2e/tests/task/add-workspace-sources.spec.ts`.
|
|
**What to verify:** both menu actions, open-folder request routing, the tab-free repository-kind
|
|
menu, mixed-row preservation, dialog flow, atomic success, Files refresh,
|
|
repository-aware UI, and persistence after reload.
|
|
- **Scenario:** GIVEN the Files tab on a Pixel 5 viewport, WHEN the user opens the full-height source
|
|
picker through the workspace-actions bottom-sheet menu and attaches two source kinds through the
|
|
responsive repository menu, THEN the same task value is delivered without horizontal overflow.
|
|
**File:** `apps/web/e2e/tests/task/mobile-add-workspace-sources.spec.ts`.
|
|
**What to verify:** 44px trigger/menu rows, both actions, open-folder request routing,
|
|
internal scroll, fixed safe-area footer, submit outcome, dismissal/focus return, and document
|
|
containment.
|
|
- **Scenario:** GIVEN a Docker task, WHEN a remote repository is attached, THEN it is readable inside
|
|
the running container; the folder source kind is absent and a forged folder request is rejected.
|
|
**File:** `apps/web/e2e/tests/docker/add-workspace-sources.spec.ts`.
|
|
**What to verify:** live agentctl repository materialization, capability gating, rollback, and
|
|
reset/relaunch.
|
|
- **Scenario:** GIVEN an SSH task, WHEN a repository source is attached, THEN it appears in the
|
|
remote task directory and survives backend reconnect.
|
|
**File:** `apps/web/e2e/tests/ssh/add-workspace-sources.spec.ts`.
|
|
**What to verify:** remote placement, rescan, persistence, and cleanup ownership.
|
|
|
|
---
|
|
|
|
## Implementation Waves
|
|
|
|
Wave 1:
|
|
|
|
- [x] [Task 01: Durable source contracts](task-01-durable-source-contracts.md)
|
|
|
|
Wave 2:
|
|
|
|
- [x] [Task 02: Attachment service](task-02-attachment-service.md)
|
|
|
|
Wave 3 (parallel):
|
|
|
|
- [x] [Task 03: Protocol surfaces](task-03-protocol-surfaces.md)
|
|
- [x] [Task 04: Host materialization](task-04-host-materialization.md)
|
|
- [x] [Task 06: Shared source picker](task-06-shared-source-picker.md)
|
|
|
|
Wave 4 (parallel after dependencies):
|
|
|
|
- [x] [Task 05: Remote materialization](task-05-remote-materialization.md)
|
|
- [x] [Task 07: Files panel surface](task-07-files-panel-surface.md)
|
|
|
|
Wave 5 (parallel):
|
|
|
|
- [x] [Task 08: End-to-end coverage](task-08-end-to-end-coverage.md)
|
|
- [x] [Task 09: Public documentation](task-09-public-documentation.md)
|
|
|
|
Wave 6:
|
|
|
|
- [x] [Task 10: Final verification](task-10-final-verification.md)
|
|
|
|
Wave 7 (parallel UX delta):
|
|
|
|
- [x] [Task 11: Shared Local and Remote selector](task-11-shared-local-remote-selector.md)
|
|
- [x] [Task 12: Unified Files workspace actions](task-12-unified-files-workspace-actions.md)
|
|
|
|
Wave 8 (parallel after Tasks 11 and 12):
|
|
|
|
- [x] [Task 13: UX delta end-to-end coverage](task-13-ux-delta-e2e.md)
|
|
- [x] [Task 14: UX terminology documentation](task-14-ux-terminology-documentation.md)
|