dsh-workspace-combiner

A Cordis dual-face plugin for DSH (DeepSeek Harness) that turns a set of repositories into a coordinated multi-workspace joint development context.

The plugin registers a Workspace Combiner tab in the left sidebar. Each workspace bundles a primary directory (the "workspace anchor" — where docs and non-code assets live) plus an ordered list of code-project directories (for example a backend repo and a frontend repo). When you start a new session, the plugin injects the absolute paths of all active directories into the system prompt and syncs the writable ones into the @chaoset/sandbox-extra-roots whitelist.

To keep that injected context from exploding, the plugin applies a four-layer context-control model:

1. Directory layer — per-directory access (readwrite / readonly / disabled), primary anchoring, drag ordering.
2. Config layer — anchor / single workspace mode plus optional group tags.
3. Load-mode layer — full / summary / tree controlling how much file detail is injected.
4. Command layer — @-command dynamic scope.

Layers 1-4 ship today; see Changelog.

---

Features

• Workspaces — create / rename / delete / switch named workspaces; each owns a primary directory plus ordered code-project directories with per-directory access.
• New-workspace wizard — pick a name + base path; the host creates the primary folder and a scan detects Java / Vue / React / Python / Go projects for multi-select.
• Three ways to add a directory — select from native DSH workspaces, open the host directory picker, or paste an absolute path.
• Directory tri-state access — readwrite (sandbox-writable), readonly (visible but not writable), disabled (excluded from the prompt). The primary directory is always readwrite.
• Workspace mode — anchor (primary = docs anchor) vs single (primary = core business code).
• Directory grouping — optional group tags (docs / backend / frontend / reference / other) rendered as sub-headers.
• Snapshots — save / restore / delete a workspace's directory configuration; restore re-syncs the sandbox immediately.
• File index + load modes — gitignore-aware bounded file-tree scan with an mtime cache; a per-workspace load mode controls injected detail.
• Context monitor — a panel card with per-directory file counts and an estimated token budget, so you can tune the load mode and watch context shrink.
• @-command dynamic scope — a prompt section teaches the model to resolve @-prefixed tokens as explicitly referenced paths across all workspace roots (@dir/, @file, @"path with spaces"), pulling files into scope on demand.
• Sandbox sync — read-write directories are pushed into sandbox-extra-roots extraWritableRoots (hot reload with a file-write fallback); the bottom legend shows how many directories are actually in the allowlist.
• Git status per directory — each row shows its branch, amber with *N when there are uncommitted or untracked changes, grey when clean, plus ↑N when ahead of the upstream. Directories that are not repositories show nothing.
• Directory notes — attach a free-form note to any directory, edited inline; it travels with the directory configuration.
• Project-directory annotations — the primary row is badged Docs only and the others Code, so the anchor-vs-source distinction is visible at a glance (hover for an explanation).
• Live injected-prompt preview — expand a read-only block that renders exactly what will be injected for the current configuration, and copy it.
• Context budget — an editable per-workspace token budget with a donut summary, 2x2 stat cards, and a per-directory column chart; the panel warns past 80% and past 100%.
• Fixed-height panel with local scrolling — the panel fills the sidebar and only its lists scroll, so the header and the New-session button never leave the screen.
• Resizable split — drag the divider between project directories and the context budget (default 6:4); the ratio is remembered.
• Keyboard — Cmd/Ctrl+N new session, Cmd/Ctrl+K command palette, Esc to close; the palette covers switching workspaces, adding directories, refreshing stats and changing modes.

---

Architecture

dsh-workspace-combiner/
├── package.json            # dsh field: bundle.patch + client.inject
├── cordis.patch.yml        # registration patch
├── tsconfig.json           # typecheck
├── tsdown.config.ts        # dual-entry build: host + client
└── src/
    ├── invariant.ts        # shared constants (plugin id / API paths / prompt order)
    ├── core/types.ts       # shared types (WorkspaceRef / Workspace / StoreShape / ...)
    ├── prompt.ts           # multi-workspace prompt + file-index rendering
    ├── store.ts            # host persistence (~/.dsh/dsh-workspace-combiner.json)
    ├── sandbox-sync.ts     # sandbox-extra-roots writable-root sync
    ├── routes.ts           # /api/dsh-workspace-combiner routes (loopback-only)
    ├── host/
    │   ├── index.ts        # host entry: prompt section + session/created + routes
    │   ├── projectDetector.ts # scan a directory for project type
    │   ├── fileIndex.ts    # gitignore-aware bounded file-tree scanner + mtime cache
    │   ├── gitStatus.ts    # branch / dirty / untracked / ahead per directory
    │   └── contextStats.ts # token estimator + per-directory context stats
    └── client/
        ├── index.ts        # client entry: sidebar icon + main-column panel
        ├── types.ts        # client-local mirrored types
        ├── locales.ts      # zh/en dictionary + tt() helper
        ├── api.ts          # client -> host fetch API
        └── panel/
            ├── WorkspaceCombinerPanel.tsx # panel body + icon
            ├── controller.ts              # state management
            ├── NewWorkspaceWizard.tsx     # create-workspace wizard
            ├── typeBadge.tsx              # project-type badge
            ├── naming.ts                  # name sanitize / dedupe
            └── styles.ts                  # injected <style> (theme-aware)

Data flow

[client panel] --POST /api/.../...--> [host store]
                                        │
                        session/created (top-level new session)
                                        ▼
                   selectionBySession: sessionId -> { directories, mode, loadMode, fileTrees }
                                        ▼
              systemPrompt.section(text fn renders per session)
                                        ▼
       injects "# Multi-workspace joint development mode active" + directory list + file index

On directory changes the host also calls sandbox-extra-roots sandboxExtraRootsConfig.set({ extraWritableRoots }) for hot reload; if the remote is unavailable it falls back to an atomic write of ~/.dsh/plugins/sandbox-extra-roots/config.json.

---

Install (local directory)

Prerequisite: DSH is installed and the dependency plugin is present.

# 0) dependency plugin (required)
dsh plugin --profile desktop add @chaoset/sandbox-extra-roots

# 1) build lib/ (host + client)
cd /path/to/dsh-workspace-combiner
pnpm install
pnpm build

# 2) load the plugin
dsh plugin --profile desktop add file:./dsh-workspace-combiner

# 3) verify
dsh plugin --profile desktop ls dsh-workspace-combiner

# 4) restart DSH Desktop (or re-run "dsh web" for the web profile)

Update after changing source: pnpm build, then remove and re-add the plugin.

---

Usage

1. Open the Workspace Combiner tab in the sidebar.
2. Pick a workspace from the list, or create one with the New workspace wizard (name + base path; the host creates the primary folder and scans for code projects).
3. Add directories (folder picker or a pasted absolute path) and review each row: the primary row is marked Docs only, the rest Code, with its Git branch, group and access. Reorder by dragging; select several rows to bulk-edit access, group or delete.
4. Open Advanced for the workspace mode, the file load mode and snapshots, and the @ command cheat sheet.
5. Expand Injected prompt to preview exactly what will be sent, and copy it if useful.
6. Click New session — the primary directory is opened, a session is created, the active directories are injected into the system prompt and the sandbox writable roots are synced.
7. Watch the Context budget card: donut, stat cards and the per-directory column chart. Drag the divider above it to trade space with the directory list.

⚠️ Directory changes only affect newly created sessions; already-open sessions are not re-loaded.

Injected prompt (appended to the system prompt)

# Multi-workspace joint development mode active
Current session loads[2]project directories:
1.example-anchor[Primary: Workspace anchor (docs/non-code area)]absolute path: /abs/path
[Backend]
2.example-backend[Code project]absolute path: /abs/path

# File index (load mode: summary)
[example-anchor]/abs/path
  12 files / 3 dirs
[example-backend]/abs/path
  210 files / 42 dirs

# @-command dynamic scope
- Tokens prefixed with @ are explicitly referenced paths: @absolute/path or @relative/to-a-workspace-root
- A trailing slash marks a directory: list its tree when its contents matter
- Otherwise it is a file: read it first, never claim inspection before reading
- @"path with spaces" quotes a path containing spaces
- @-referenced files/dirs take priority; paths outside the file index are still readable (sandbox reads are unrestricted)

Development rules:
1. Read/write files and view code must use full absolute paths — no relative paths
2. Different repositories' Git commits are independent and do not interfere
3. On API changes, update backend and frontend request code together
4. Terminal commands must be run with full absolute paths, not relative paths

---

Configuration (optional)

No schema; configure via cordis.patch.yml:

workspace-combiner:
  enabled: true          # master switch
  announceToAgent: true  # inject the multi-workspace prompt section

---

Design notes / constraints

1. The session shell has a single, immutable cwd. The plugin does not try to change it; instead the prompt rules force absolute paths.
2. New sessions only. On session/created the selection is snapshotted and bound to that session id; old sessions and child/fork sessions (those with parentSession) are not injected.
3. Read model — reads are already unrestricted in the DSH sandbox; the tri-state access only gates writes (via extraWritableRoots) and prompt inclusion.
4. Dependencies are declared in package.json dsh.client.inject and peerDependencies (@chaoset/sandbox-extra-roots, DSH host services).
5. Aux routes (loopback-only): scan, file-index, git-status, context-stats, workspace-patch, plus state / workspace CRUD routes.

---

Development

pnpm install
pnpm typecheck     # tsc --noEmit
pnpm build         # tsdown -> lib/host/index.js + lib/client.js
pnpm watch         # watch rebuild

• Host logs: ctx.logger.warn(...) on sync failures.
• Persistence: ~/.dsh/dsh-workspace-combiner.json.
• Sandbox config: ~/.dsh/plugins/sandbox-extra-roots/config.json.

License

MIT