Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

docs(switchdash): correct the structural inventories in the dash agent docs (CHOO-1860)

Louis Amaudruz5e134fd97427
diff --git a/dash/agents/architecture/data-model.md b/dash/agents/architecture/data-model.md
index 70ae9a48f..672d6367e 100644
--- a/dash/agents/architecture/data-model.md
+++ b/dash/agents/architecture/data-model.md
@@ -6,10 +6,10 @@ project (repo) holds several sessions (originally one per git worktree), each se
holds conversations with a coding agent and one or more terminals, all running in an
abstracted *workspace* (worktree / SSH / remote).
-switchdash is being reworked to manage **local Switch agent sessions** instead:
-multiple agents living in a directory, each tied to one provider, each with its
-own runs. This page is the system of record for how the switchdash model
-diverges from that upstream model and how the abstractions map across.
+switchdash manages **Switch agent sessions** instead: multiple agents living in a
+directory, each tied to one provider, each with its own runs. This page is the system
+of record for how the switchdash model diverges from that upstream model and how the
+abstractions map across.
The schema is defined in `apps/switchdash-desktop/src/main/db/schema.ts`.
@@ -17,25 +17,42 @@ The schema is defined in `apps/switchdash-desktop/src/main/db/schema.ts`.
| switchdash | upstream equivalent | What it is |
|---|---|---|
-| **project** | `project` | A directory on disk (repo root). Unchanged in spirit. |
+| **location** | `project` + `workspace` | A working directory on a host — local, or on an SSH host. Replaces both the upstream project *and* the workspace abstraction; the table is `locations`. |
| **agent** | *(none)* — new | A Switch agent identity bound to one provider. **Many agents per directory.** Carries the optional Switch identity (`switchAgentId`, `apiEndpoint`) detected from `.claude/settings.local.json`. |
| **provider** | `agent` | The CLI agent kind (claude, codex, gemini, …). Upstream called this an "agent"; here it's a *provider*, referenced by an agent via `providerId`. It stays a static code registry, not a table. |
| **session** | `conversation` | One instantiation/run of an agent. The unit shown under an agent in the sidebar. |
| *(folded into session)* | `terminal` | A session is 1:1 with its terminal, so the terminal's `shellId` lives on the session; there is no `terminals` table. |
| **message** | `message` | A message in a session (was keyed by `conversationId`, now `sessionId`). |
-| *(removed)* | `session` (worktree-era) | The upstream parallel-run grouping. Removed — switchdash runs every session in the project root, so the grouping layer is gone. |
+| *(removed)* | `session` (worktree-era) | The upstream parallel-run grouping. Removed — switchdash runs every session in the location's directory, so the grouping layer is gone. |
| *(removed)* | `workspace` | The upstream execution-location abstraction (worktree / SSH / BYOI remote). Removed — see below. |
+### Tables with no upstream equivalent
+
+These carry the Switch- and remote-specific state that upstream had no concept of:
+
+| Table | What it is |
+|---|---|
+| `switch_servers` | A Switch server switchdash talks to, managed or external. |
+| `remote_hosts` | An SSH host (keyed by its `~/.ssh/config` alias) that can run agents. |
+| `remote_host_reachability` | The last observed reachability of a host. Separate from the host record so a probe result never masquerades as configuration — see the reachability note below. |
+| `remote_host_setup_plans` | A host's onboarding plan (CHOO-1809). See "Remote host setup". |
+| `location_settings` | Per-location DB-backed settings (distinct from `.switchdash.json`). |
+| `session_room_connections` | The Switch room a session is attending (0..1). |
+| `kv`, `app_secrets` | Generic key/value state and encrypted secrets. |
+
## Resulting hierarchy
```
-project (directory on disk)
- └─ agent (Switch identity; one provider each; many per dir)
+location (a working directory, local or on an SSH host)
+ └─ agent (Switch identity; one provider each; many per location)
└─ session (a run/instantiation; was "conversation")
├─ message
└─ session_room_connection (0..1 — the Switch room it is attending)
```
+A location that lives on an SSH host references a `remote_hosts` row; that host carries
+its own reachability and setup-plan rows alongside, not inside, the location hierarchy.
+
A session's room connection is a row keyed by `session_id` with
`ON DELETE CASCADE`, so it cannot outlive the session (or the agent above it).
It was previously a JSON blob in `app_settings`, which referenced nothing and so
@@ -51,7 +68,12 @@ agents whose Switch server had been destroyed.
runs in the project root directory."* A workspace was therefore just "the
project directory" plus lifecycle scripts. We dropped the table (and
`project.repositoryWorkspaceId` / `session.workspaceId`) and keep lifecycle
- scripts / fs access as a service hung off the project directory.
+ scripts / fs access as a service hung off the location's directory.
+
+ **What survived of it is the host split, not the table.** "Where a session runs" is
+ still a real question — it is now answered by the location's host (local or SSH) and
+ by the `execution-context` / `agent-runtime` provider pairs, rather than by a
+ `workspace` row. Dropping the table did not make switchdash local-only.
- **The worktree-era `session` grouping.** With no worktrees, a session was a
near-empty wrapper around a single conversation. We collapsed it: the upstream
`conversation` becomes switchdash's `session`.
@@ -63,7 +85,14 @@ agents whose Switch server had been destroyed.
## Naming note (code)
-The upstream "agent" concept (the provider registry and its tooling) is being renamed
-from `agents/` to `providers/` across `src/main/core/` and `src/shared/core/`, so
-that the name **agent** is free for the new Switch-agent concept. The Switch-agent
-domain absorbs the former `switch-agents/detect.ts` directory detector.
+This rename has **landed**. The upstream "agent" concept (the provider registry and its
+tooling) is now `providers/` in both `src/main/core/` and `src/shared/core/`, and the name
+**agent** belongs to the Switch-agent concept. The Switch-agent domain absorbed the former
+`switch-agents/detect.ts` directory detector, which is now `core/agents/detect.ts`.
+
+So in current code:
+
+- `core/agents/` — Switch agents (create, onboard, detect, remote discovery)
+- `core/providers/` — the CLI-provider registry, payload builder, plugin registry
+
+Both directories exist and mean different things. `core/switch-agents/` no longer exists.
diff --git a/dash/agents/architecture/main-process.md b/dash/agents/architecture/main-process.md
index 4c3e32769..917e7cde6 100644
--- a/dash/agents/architecture/main-process.md
+++ b/dash/agents/architecture/main-process.md
@@ -6,44 +6,61 @@ The main process is organized into domain modules under `src/main/core/`. Each d
## Domain Modules (`src/main/core/`)
-- **agent-hooks** — HTTP hook server for agent callbacks, event enrichment, OS notifications, hook/plugin config writer, workspace/trust services
-- **agents** — Agent payload builder, plugin registry, plugin filesystem
+Two names in this list are easy to misread, because one of them changed meaning:
+
+- **agents** is the *Switch agent* domain — an agent identity bound to a provider. It is
+ **not** the CLI-tool registry.
+- **providers** is the CLI-tool registry (claude, codex, …). Upstream called that concept
+ an "agent"; it was renamed to free the name for the Switch-agent concept above.
+
+- **agent-hooks** — HTTP hook server for agent callbacks, event enrichment, OS notifications, hook config writer (`hook-config-service.ts`), per-tool trust services (`claude-trust-service.ts`, `cursor-trust-service.ts`, `dir-trust-service.ts`)
+- **agent-runtime** — How a session is actually launched and supervised: launch profiles, the runtime supervisor, and `impl/` backends — `local-agent-runtime.ts` (local spawn) and `ssh-agent-runtime.ts` (remote), plus sidecar launch/HTTP and keystroke injection
+- **agents** — The Switch-agent domain: create/rename/delete, directory detection (`detect.ts`), onboarding, remote agent discovery and reconciliation, Switch credential/settings files
- **app** — App lifecycle service and controller
-- **conversations** — Conversation CRUD and session start
-- **dependencies** — CLI agent detection, probing, install runner, version/update services
-- **execution-context** — Execution context resolution for agent runs
+- **dependencies** — CLI agent detection, probing, install runner, version/update services, and their remote counterparts (`remote-dependency-manager.ts`, `ssh-install-runner.ts`)
+- **execution-context** — Where a command runs: `local-execution-context.ts` vs `ssh-execution-context.ts`
- **fs** — Filesystem operations with provider pattern (`impl/local-fs.ts`)
-- **projects** — Project management with provider pattern (`impl/local-project-provider.ts`), project settings, CRUD operations
+- **locations** — An agent's working directory on a host. Replaces the upstream project/workspace split; provider pattern plus lifecycle scripts
+- **managed-switch-server** — A switchdash-managed Switch server deployed via Docker Compose
- **prompt-library** — Prompt library service and controller
+- **providers** — CLI-provider plugin registry (`plugin-registry.ts`), agent payload builder, plugin filesystem, argv parity test
- **pty** — PTY lifecycle (`local-pty.ts`), session registry, env setup, spawn utilities
+- **remote-hosts** — SSH host records, reachability probing (`host-reachability-service.ts`), and host setup
- **resource-monitor** — System resource monitoring
-- **runtime** — Runtime service wiring
- **search** — Search service
- **secrets** — Encrypted app secret storage
- **sessions** — Session CRUD (create, delete, rename, provision)
- **settings** — App settings service and schema, provider settings (separate controller)
-- **shared** — Shared main-process utilities
-- **switch-agents** — Switch agent integration
+- **shared** — Shared main-process utilities (OAuth flow)
+- **sidecar** — Desktop-side view of the remote sidecar: diagnostics and health verdicts. The sidecar implementation itself is `src/sidecar/`
+- **ssh** — SSH config, connection, lifecycle, and transport
+- **switch-rooms** — Room connections, the auto-session watcher, prompt injection sinks, Switch credentials, notification polling
+- **switch-servers** — Switch server records, gateway client, auth, room creation
+- **switch-setup** — First-run Switch setup, local and remote (`remote-switch-setup.ts`)
- **terminal-shell** — Terminal shell availability and detection
- **terminals** — Terminal lifecycle with provider pattern (`impl/local-terminal-provider.ts`), lifecycle scripts
- **updates** — Auto-update service
-- **utils** — Cross-domain main-process helpers
+- **utils** — Cross-domain main-process helpers (exec, TTL cache, compensation)
- **view-state** — Persisted view/UI state
-- **workspaces** — Workspace (project-root working directory) management
## Other Main Process Areas
-- `src/main/app/` — Menu, protocol handler, window creation
-- `src/main/lib/` — Logger, events, result type, updater error
-- `src/main/db/` — Database schema and initialization
+- `src/main/app/` — Menu, protocol handler, deeplinks, window creation, app identity
+- `src/main/lib/` — Logger and file logger, log context (`AsyncLocalStorage`) and enrichment, events, rate limiter, retry, semver
+- `src/main/db/` — Database schema, client, initialization, versioned columns
- `src/main/utils/` — Shell environment, shell escaping, child process env, external links
-- `src/main/core/agent-hooks/` — Hook server, event enrichment, OS notifications, hook/plugin config writer
+- `src/sidecar/` — The headless remote sidecar. Not part of `src/main/`, but it re-implements
+ much of what the main process does for a session; see the sidecar section of `AGENTS.md`.
+
+The `Result<T, E>` type is **not** in `src/main/lib/`. It lives in the `@switchdash/shared`
+workspace package (`packages/shared/src/result.ts`) and is imported as
+`import { ok, err, type Result } from '@switchdash/shared'`.
## IPC / RPC Structure
- All domain controllers are assembled into a typed RPC router in `src/main/rpc.ts`.
-- RPC primitives live in `src/shared/ipc/rpc.ts` (`createRPCRouter`, `createRPCController`, `createRPCClient`).
-- Event primitives live in `src/shared/ipc/events.ts`.
+- RPC primitives live in `src/shared/lib/ipc/rpc.ts` (`createRPCRouter`, `createRPCController`, `createRPCClient`).
+- Event primitives live in `src/shared/lib/ipc/events.ts`.
- The preload bridge (`src/preload/index.ts`) exposes only `invoke`, `eventSend`, `eventOn`, and `getPathForFile`; there are no other manual IPC handlers.
## When Editing Here
diff --git a/dash/agents/architecture/renderer.md b/dash/agents/architecture/renderer.md
index 92fc330fb..2974a386b 100644
--- a/dash/agents/architecture/renderer.md
+++ b/dash/agents/architecture/renderer.md
@@ -12,17 +12,22 @@ All paths are relative to `apps/switchdash-desktop/`.
## App Shell (`src/renderer/app/`)
-- `workspace.tsx`, `home-view.tsx`, `welcome.tsx` — shell and top-level views
+- `workspace.tsx`, `home-view.tsx` — shell and top-level views
- `modal-registry.ts` — central modal registry; all modals are registered here
- `view-registry.ts` — central view registry; all views are registered here
- `app-menu-events.tsx` — native app menu event wiring
## Feature Areas (`src/renderer/features/`)
-- `sessions/` — session experience: `conversations/`, `terminals/`, `create-session-modal/`,
- `components/`, `hooks/`, and `stores/` (MobX session stores and `session-selectors.ts`)
-- `projects/` — project management and settings panel; `stores/` holds
- project stores and `project-selectors.ts`
+- `sessions/` — session experience: `create-session-modal/`, `components/`, `hooks/`,
+ and `stores/` (MobX session stores and `session-selectors.ts`)
+- `locations/` — an agent's working directory on a host, and its settings panel; `stores/`
+ holds location stores and `location-selectors.ts`
+- `remote-hosts/` — SSH hosts: the host list and detail views, reachability notices, and
+ host setup
+- `switch-rooms/` — Switch room membership and the inline bridge pane
+ (`room-embed-layer.tsx`)
+- `switch-servers/` — Switch server connections, including a switchdash-managed server
- `sidebar/` — app sidebar
- `settings/` — settings view
- `command-palette/` — command palette
@@ -33,11 +38,15 @@ All paths are relative to `apps/switchdash-desktop/`.
- `modal/` — modal provider, renderer, store, and close-guard infrastructure
- `layout/` — layout, navigation, and panel drag providers
- `commands/` — command registry (`registry.ts`) and view-level `commandProvider` hooks
+- `hotkeys/` — global hotkey handling
- `pty/` — frontend PTY sessions, pool provider, panes, prompt injection
-- `editor/` — Monaco editor integration
+- `updates/` — in-app update surfaces
- `stores/` — cross-feature stores (navigation, dependencies, resource monitor, ...)
- `providers/`, `hooks/`, `components/`, `ui/`, `theme/` — shared providers, hooks, and UI primitives
+There is no `editor/` directory. Monaco is still a dependency, but the only integration
+left in the renderer is `lib/components/monaco-keyboard-bridge.tsx`.
+
## Tests
- Renderer unit tests: `src/renderer/tests/`
diff --git a/dash/agents/architecture/shared.md b/dash/agents/architecture/shared.md
index e1393e53c..1ca603ec0 100644
--- a/dash/agents/architecture/shared.md
+++ b/dash/agents/architecture/shared.md
@@ -6,19 +6,28 @@
lives in `packages/plugins/src/agents/impl/<id>/index.ts`):
- `src/shared/core/providers/agent-provider-registry.ts`
- IPC primitives:
- - `src/shared/ipc/rpc.ts` — typed RPC router, controller, and client
- - `src/shared/ipc/events.ts` — typed event emitter
+ - `src/shared/lib/ipc/rpc.ts` — typed RPC router, controller, and client
+ - `src/shared/lib/ipc/events.ts` — typed event emitter
- Typed event definitions:
- - `src/shared/events/` — `appEvents.ts`, `browserEvents.ts`, `resourceEvents.ts`, `updateEvents.ts`
+ - `src/shared/events/` — `appEvents.ts`, `browserEvents.ts`, `resourceEvents.ts`,
+ `updateEvents.ts`, `sidecarEvents.ts`, `switchSetupEvents.ts`,
+ `localSwitchServerEvents.ts`, `remoteSwitchServerEvents.ts`
- additional domain events colocated under `src/shared/core/` — e.g.
- `core/agents/agentEvents.ts`, `core/conversations/conversationEvents.ts`,
- `core/fs/fsEvents.ts`, `core/projects/projectEvents.ts`, `core/sessions/sessionEvents.ts`
+ `core/providers/agentEvents.ts`, `core/fs/fsEvents.ts`,
+ `core/locations/locationEvents.ts`, `core/sessions/sessionEvents.ts`,
+ `core/switch-rooms/switchRoomEvents.ts`, `core/ssh/sshEvents.ts`,
+ `core/pty/ptyEvents.ts`
- Domain type modules (under `src/shared/core/`):
- - `agents/`, `conversations/`, `fs/`, `projects/`, `project-settings/`, `pty/`,
- `sessions/`, `terminals/`, `workspaces/`
+ - `agents/`, `fs/`, `location-settings/`, `locations/`, `managed-switch-server/`,
+ `mcp/`, `providers/`, `pty/`, `remote-hosts/`, `sessions/`, `skills/`, `ssh/`,
+ `switch-rooms/`, `switch-servers/`, `switch-setup/`, `terminals/`
- App settings types:
- `src/shared/core/app-settings.ts`
+Note the `agents/` vs `providers/` split here, which mirrors `src/main/core/`:
+`core/agents/` is the Switch-agent concept, `core/providers/` is the CLI-provider
+registry and payload types.
+
## Path Aliases
All aliases are defined in a single `tsconfig.json` and mirrored in `electron.vite.config.ts`:
diff --git a/dash/agents/conventions/ipc.md b/dash/agents/conventions/ipc.md
index c9256058c..f2d332a5c 100644
--- a/dash/agents/conventions/ipc.md
+++ b/dash/agents/conventions/ipc.md
@@ -32,7 +32,9 @@ when a browser/Electron primitive cannot fit the RPC/event path.
## Event System
-Typed events use `createEventEmitter` from `src/shared/ipc/events.ts`. Event type definitions live in `src/shared/events/`.
+Typed events use `createEventEmitter` from `src/shared/lib/ipc/events.ts`. Event type
+definitions live in `src/shared/events/`, with domain events colocated under
+`src/shared/core/<domain>/`.
## Rules
diff --git a/dash/agents/conventions/main-patterns.md b/dash/agents/conventions/main-patterns.md
index 38438412e..197def788 100644
--- a/dash/agents/conventions/main-patterns.md
+++ b/dash/agents/conventions/main-patterns.md
@@ -23,7 +23,7 @@ Controllers are assembled into the router in `src/main/rpc.ts`:
```ts
export const rpcRouter = createRPCRouter({
sessions: sessionController,
- projects: projectController,
+ locations: locationsController,
// ...
});
```
@@ -60,21 +60,35 @@ Some domains expose a provider interface with a single local backend, leaving ro
additional backends without changing call sites:
```
-src/main/core/projects/
-├── project-provider.ts # Interface
-├── create-project-provider.ts # Factory
-└── project-manager.ts # Orchestrates the provider
+src/main/core/locations/
+├── location-provider.ts # Interface
+├── create-location-provider.ts # Factory
+└── location-manager.ts # Orchestrates the provider
```
-Used in: projects, filesystem (`fs/impl/local-fs.ts`), terminals (`terminals/impl/local-terminal-provider.ts`).
-Switchdash is local-only — these providers currently have local implementations only.
+Used in: locations, filesystem (`fs/impl/local-fs.ts`), terminals (`terminals/impl/local-terminal-provider.ts`).
-## Result Type (`src/main/lib/result.ts`)
+**Switchdash is not local-only, and this is the pattern that carries the difference.**
+An agent runs either locally or on an SSH host, so the backend behind an interface is a
+real choice rather than a placeholder for one:
-Explicit error handling via discriminated union:
+- `execution-context` has `local-execution-context.ts` **and** `ssh-execution-context.ts`
+- `agent-runtime/impl/` has `local-agent-runtime.ts` **and** `ssh-agent-runtime.ts`
+- `dependencies` has local detection **and** `remote-dependency-manager.ts` /
+ `ssh-install-runner.ts`
+
+`fs` and `terminals` do currently have only a local implementation. When adding a backend,
+check whether the remote path needs one too — and see the sidecar section of `AGENTS.md`,
+because a remote session is served by `src/sidecar/`, which is a second implementation that
+will not follow your change automatically.
+
+## Result Type (`@switchdash/shared`)
+
+Explicit error handling via discriminated union. The type lives in the shared workspace
+package (`packages/shared/src/result.ts`), not in `src/main/lib/`:
```ts
-import { ok, err, type Result } from '../lib/result';
+import { ok, err, type Result } from '@switchdash/shared';
async function doSomething(): Promise<Result<Data, SomeError>> {
if (problem) return err({ type: 'not_found' as const });
diff --git a/dash/agents/conventions/renderer-patterns.md b/dash/agents/conventions/renderer-patterns.md
index dffb56eea..dae25798e 100644
--- a/dash/agents/conventions/renderer-patterns.md
+++ b/dash/agents/conventions/renderer-patterns.md
@@ -21,7 +21,7 @@ All modals use a registry-based system. Only one modal can be active at a time.
```tsx
const { showModal } = useModalContext();
-showModal('myModal', { projectId: '123', onSuccess: (result) => {...} });
+showModal('myModal', { locationId: '123', onSuccess: (result) => {...} });
```
**Rules:**
@@ -60,7 +60,7 @@ Views use a registry + parameterized navigation pattern.
**Rules:**
- Historical output comes from the main-process ring buffer; do not add renderer-side buffering
-- `sessionId` format: `makePtySessionId(projectId, scopeId, leafId)` from
+- `sessionId` format: `makePtySessionId(locationId, scopeId, leafId)` from
`src/shared/core/pty/ptySessionId.ts` — deterministic
- Panel drag pauses resizing to avoid jank (`src/renderer/lib/layout/panel-drag-store.ts`)
@@ -93,6 +93,6 @@ For state that must survive React unmounts or be shared across unrelated compone
- **`useSyncExternalStore`-compatible stores** — e.g., `panelDragStore` in `src/renderer/lib/layout/`
- **Cross-feature stores** — `src/renderer/lib/stores/` (navigation, dependencies, resource monitor, ...)
-- **MobX session and project stores** — `src/renderer/features/sessions/stores/` and
- `src/renderer/features/projects/stores/`; access them through selectors
- (`session-selectors.ts`, `project-selectors.ts`) and session view hooks, never directly
+- **MobX session and location stores** — `src/renderer/features/sessions/stores/` and
+ `src/renderer/features/locations/stores/`; access them through selectors
+ (`session-selectors.ts`, `location-selectors.ts`) and session view hooks, never directly
diff --git a/dash/agents/integrations/mcp.md b/dash/agents/integrations/mcp.md
index 24e2e875f..516068f43 100644
--- a/dash/agents/integrations/mcp.md
+++ b/dash/agents/integrations/mcp.md
@@ -9,7 +9,7 @@ small set of shared types and a static catalog.
- `src/shared/core/mcp/types.ts` — canonical MCP server entry types (e.g. `RawServerEntry`)
- `src/shared/core/mcp/catalog.ts` — static catalog of known MCP servers and their
credential keys (`catalogData`)
-- `src/main/core/agents/agent-payload-builder.ts` — includes MCP capability data in the
+- `src/main/core/providers/agent-payload-builder.ts` — includes MCP capability data in the
payload handed to an agent based on provider capabilities
## Current Behavior