Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
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.mdindex 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 seholds conversations with a coding agent and one or more terminals, all running in anabstracted *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 "theproject 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 anear-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.mdindex 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 Herediff --git a/dash/agents/architecture/renderer.md b/dash/agents/architecture/renderer.mdindex 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.mdindex 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 AliasesAll 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.mdindex 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>/`.## Rulesdiff --git a/dash/agents/conventions/main-patterns.md b/dash/agents/conventions/main-patterns.mdindex 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`:```tsexport 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 roadditional 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.mdindex 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.```tsxconst { 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 directlydiff --git a/dash/agents/integrations/mcp.md b/dash/agents/integrations/mcp.mdindex 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 theircredential 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 thepayload handed to an agent based on provider capabilities## Current Behavior