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): cover remote execution and Switch rooms (CHOO-1860)
Louis Amaudruzb326ab7afd9b
diff --git a/dash/AGENTS.md b/dash/AGENTS.mdindex 86602e6a2..8320ceb71 100644--- a/dash/AGENTS.md+++ b/dash/AGENTS.md@@ -525,6 +525,8 @@ pnpm run test- [Main process architecture](agents/architecture/main-process.md)- [Renderer architecture](agents/architecture/renderer.md)- [Shared modules](agents/architecture/shared.md)+- [Remote execution: hosts, reachability, sidecar](agents/architecture/remote-execution.md)+- [Switch rooms and sessions](agents/architecture/switch-rooms.md)- [Data model (switchdash vs. its upstream origin)](agents/architecture/data-model.md)- [Testing workflow](agents/workflows/testing.md)- [Provider integration](agents/integrations/providers.md)diff --git a/dash/agents/README.md b/dash/agents/README.mdindex 907112c7a..466ccc0c7 100644--- a/dash/agents/README.md+++ b/dash/agents/README.md@@ -8,6 +8,11 @@ This directory is the system of record for agent-facing repo guidance. Keep topi2. `architecture/overview.md`3. the task-specific page for the area you are changing+If the change touches remote hosts or Switch rooms, read+`architecture/remote-execution.md` and `architecture/switch-rooms.md` too — switchdash+runs agents on SSH hosts as well as locally, and the remote path is a separate+implementation.+## Directory Layout- `architecture/`diff --git a/dash/agents/architecture/overview.md b/dash/agents/architecture/overview.mdindex ba82400d2..408db4035 100644--- a/dash/agents/architecture/overview.md+++ b/dash/agents/architecture/overview.md@@ -8,6 +8,7 @@ All paths are relative to `apps/switchdash-desktop/`.- `src/preload/`: Electron preload bridge — exposes typed `invoke`, `eventSend`, `eventOn` to renderer- `src/renderer/`: React UI — app shell (`app/`), feature areas (`features/`), shared infrastructure (`lib/`), typed RPC client- `src/shared/`: Agent provider registry, IPC primitives (RPC + events), shared domain types under `src/shared/core/`+- `src/sidecar/`: The headless on-host sidecar that keeps a remote session running while switchdash is closed. Not an Electron process — see `remote-execution.md`## Boot Sequence@@ -29,3 +30,5 @@ All paths are relative to `apps/switchdash-desktop/`.- Main process details: `main-process.md`- Renderer details: `renderer.md`- Shared modules and provider registry: `shared.md`+- Remote hosts, reachability, and the sidecar: `remote-execution.md`+- Switch rooms and session binding: `switch-rooms.md`diff --git a/dash/agents/architecture/remote-execution.md b/dash/agents/architecture/remote-execution.mdnew file mode 100644index 000000000..58bea6e9b--- /dev/null+++ b/dash/agents/architecture/remote-execution.md@@ -0,0 +1,105 @@+# Remote Execution: Hosts, Reachability, and the Sidecar++All paths are relative to `apps/switchdash-desktop/` unless noted.++**Switchdash is not local-only.** An agent runs either on the local machine or on an SSH+host. That choice reaches almost every layer — execution context, agent runtime,+dependency detection, PTY — so a change that only handles the local case is a change that+silently does less on a remote host. This page is the map of the remote half.++## The pieces++| Concern | Where |+|---|---|+| SSH host records, keyed by `~/.ssh/config` alias | `src/main/core/remote-hosts/`, table `remote_hosts` |+| Reachability state machine | `remote-hosts/host-reachability-service.ts`, `src/shared/core/remote-hosts/reachability.ts`, table `remote_host_reachability` |+| SSH config, connection, transport | `src/main/core/ssh/` |+| Where a command runs | `src/main/core/execution-context/` — `local-execution-context.ts` / `ssh-execution-context.ts` |+| How a session is launched | `src/main/core/agent-runtime/impl/` — `local-agent-runtime.ts` / `ssh-agent-runtime.ts` |+| Remote dependency detection and install | `dependencies/remote-dependency-manager.ts`, `dependencies/ssh-install-runner.ts` |+| The on-host sidecar | `src/sidecar/` (implementation), `src/main/core/sidecar/` (desktop-side diagnostics) |+| A switchdash-managed Switch server | `src/main/core/managed-switch-server/` |+| Renderer surfaces | `src/renderer/features/remote-hosts/` |++## Reachability is a state machine, not a boolean (CHOO-1682)++Before it existed, "can we reach host X?" was answered independently by every caller — the+pooled connection's in-memory state, an on-demand `testConnection`, or just attempting the+work and interpreting the ssh2 error. That produced unbounded retry loops against dead+hosts and raw transport errors in the UI. Now there is **one per-host state** that every+host-dependent path consults up front:++- `unknown` — never probed this run. **Work is allowed through**; the first attempt is what+ establishes reachability.+- `reachable` — a probe or live connection succeeded.+- `unreachable` — probes failing. Background work pauses; a bounded backoff probe keeps+ checking so recovery is automatic.+- `suspended` — **authentication** failed. Retrying a rejected key never self-heals, so+ there is no automatic probing; the user must fix auth and retry explicitly.++The backoff is `1s, 5s, 15s, 30s, 60s, 300s` (capped and repeated). Early steps are tight+because the common cause is a credential the user is actively re-establishing (VPN,+`aws sso login`); the long tail keeps a genuinely dead host from costing anything. A manual+retry short-circuits the schedule.++**When adding a host-dependent path, gate it on reachability rather than discovering the+failure yourself.** The distinction between `unreachable` and `suspended` is the point: one+is worth retrying automatically and the other is not.++### Never report "fine" for something you did not observe++A check that could not run is **not** a passing check. Collapsing "couldn't determine" into+"satisfied" is the stale-green bug (CHOO-1780) — the UI claims a host is ready, the user+acts on it, and the failure surfaces somewhere less obvious. Keep `unknown` as a+first-class answer all the way to the surface.++## Host setup is a persisted plan (CHOO-1809)++> This section describes `feature-request/remote-host-onboarding-rewrite`. If you are+> reading it on a checkout where `src/main/core/remote-hosts/setup/` does not exist, that+> branch has not merged yet.++Onboarding a host used to be a single boolean — a row existed or it didn't — with every+prerequisite probed independently by whichever component happened to render. There was no+notion of *where a host got to*, so nothing could be resumed or ordered, and a failure+halfway through left no record.++A **setup plan** is that missing object: an ordered list of steps, persisted per host in+`remote_host_setup_plans`, answering "what still needs to happen on this host, and what+went wrong last time?".++- Model: `src/shared/core/remote-hosts/setup.ts`, `host-status.ts`+- Main: `src/main/core/remote-hosts/setup/` — `plan-builder.ts`, `host-setup-runner.ts`,+ `host-setup-service.ts`, `setup-plan-store.ts`, `step-outcomes.ts`+- Renderer: `src/renderer/features/remote-hosts/setup/`, `host-readiness.ts`++Two properties worth preserving:++- **Nothing advances the plan on its own.** Each step runs when the user asks for that+ step; the ordering is guidance, not automation. There is deliberately no+ run-everything button.+- **A check outcome is richer than a boolean** — `satisfied`, `missing`, `not-running`,+ `wrong-version`, `unknown`. `not-running` matters because `docker` being on `PATH` tells+ you nothing about whether `dockerd` is up, and running an installer over a stopped+ service would misreport the cause.++## The sidecar++A remote agent runs inside tmux next to a switchdash-deployed **sidecar**, so it keeps+working and listening to its Switch rooms while switchdash is closed (CHOO-1059).++`src/sidecar/` is a second, headless implementation of what the desktop does for a+session — it starts sessions, keeps them connected to their room, and injects messages into+their pane — with no Electron, no database and no renderer.++**Read the sidecar section of `AGENTS.md` before changing session launch behaviour.** It+lists the desktop/sidecar pairs that must stay in step, and the sharpest edge: anything+reaching a session through its **environment** is built separately on each side.++## When editing here++- Check the reachability state before adding a host-dependent code path.+- Ask whether a change to local session launch needs the same change in `src/sidecar/`.+- Remote dependency detection and install are separate implementations from the local+ ones — see `dependencies/remote-dependency-manager.ts`.+- See `agents/architecture/switch-rooms.md` for how a session binds to a Switch room.diff --git a/dash/agents/architecture/switch-rooms.md b/dash/agents/architecture/switch-rooms.mdnew file mode 100644index 000000000..8f9f9e2b1--- /dev/null+++ b/dash/agents/architecture/switch-rooms.md@@ -0,0 +1,86 @@+# Switch Rooms and Sessions++All paths are relative to `apps/switchdash-desktop/`.++Switchdash exists to manage Switch agents, and a Switch agent's work happens in **rooms**.+A session can be *attending* a room: it receives the room's events and can post back into+it. This page covers that binding, how a session is started in response to room activity,+and how a room's conversation is shown in the app.++## Where it lives++| Concern | Where |+|---|---|+| Room connection, credentials, event stream | `src/main/core/switch-rooms/` |+| Room/session binding | table `session_room_connections`, `session-room-store.ts` |+| Auto-start a session from room activity | `switch-rooms/auto-session-watcher.ts` |+| Prompt injection into a live TUI | `switch-rooms/injection-sink.ts`, `tmux-injection-sink.ts` |+| Switch servers (managed or external) | `src/main/core/switch-servers/`, `managed-switch-server/` |+| Renderer | `src/renderer/features/switch-rooms/`, `features/switch-servers/` |+| Shared types | `src/shared/core/switch-rooms/` |++## A session attends at most one room++The binding is a `session_room_connections` row keyed by `session_id` with+`ON DELETE CASCADE`, so it cannot outlive the session (or the agent above it).++This is worth knowing because of what it replaced: the binding used to be a JSON blob in+`app_settings`, which referenced nothing and therefore survived both. Switchdash would+restore sessions on every launch for agents whose Switch server had been destroyed. If you+are tempted to persist session-adjacent state somewhere convenient, that is the bug to+remember.++## Auto-sessions++`auto-session-watcher.ts` watches for room activity addressed to an agent that has no live+session, and starts one. This is why an agent can be addressed from Slack or Mattermost and+simply respond, without anyone opening switchdash first.++**The sidecar has its own implementation of this watcher**+(`src/sidecar/notification-watcher.ts`). They are two implementations of one behaviour, and+neither follows the other — see the sidecar table in `AGENTS.md`.++## Prompt injection++Some providers cannot be handed a new prompt through an API once their TUI is running, so+switchdash types it in. `InjectionSink` abstracts the transport:++- **Local** — write straight to the agent's PTY via node-pty.+- **Remote** — the sidecar performs `tmux send-keys` into the agent's tmux pane.++`acquire` returns null when the target is not ready to receive input (e.g. the PTY is not+live yet); callers defer and retry rather than dropping the injection.++## The inline bridge pane (CHOO-1674)++A room's conversation can be rendered **inside** switchdash in a `<webview>`, rather than+sending the user out to a browser. `src/shared/core/switch-rooms/room-embed.ts` resolves+one of two answers:++- `kind: 'inline'` — a `<webview>` on a partition that already has the Mattermost session+ cookie installed, with `chromeless` asking the guest preload+ (`src/preload/mattermost-guest.ts`) to hide the global header and sidebars.+- **Deeplink** — the room is bridged somewhere we cannot embed (Slack, or a Mattermost we+ hold no credentials for). The app offers the deeplink **instead of pretending** it can+ show the conversation.++Two things not to rediscover:++- **Only managed servers can be embedded.** Mattermost embedding needs a port we chose and+ credentials we hold; an external server's Mattermost is somebody else's deployment.+- **Mattermost's `/_popout/` route does not work for this.** It looks like the supported+ way to embed a single channel, but it requires the desktop app's `window.opener` token+ handshake — under an Electron user agent the web app ignores our session cookie and+ bounces to a login page. The ordinary channel URL is loaded and the surrounding chrome+ hidden instead. The decision sits behind one resolved value so swapping strategies later+ touches that module and nothing else.++`room-embed-layer.tsx` keeps at most `MAX_LIVE_EMBEDS` (4) live webviews once visited —+each is a real renderer process, so this trades memory for instant switching and drops the+oldest beyond a handful.++## When editing here++- Changing session startup? Check whether `src/sidecar/` needs the same change.+- Changing what reaches a session's environment? Both sides build that separately.+- See `agents/architecture/remote-execution.md` for hosts, reachability, and the sidecar.diff --git a/dash/agents/conventions/versioned-schemas.md b/dash/agents/conventions/versioned-schemas.mdindex a4a18fcc3..cef9b62ec 100644--- a/dash/agents/conventions/versioned-schemas.md+++ b/dash/agents/conventions/versioned-schemas.md@@ -219,8 +219,14 @@ For Drizzle column helpers, use the exported `parseVersionedColumn` and## All migrated columns+These are the columns currently bound with `versionedJsonColumn()` in+`src/main/db/schema.ts`:+| Column | Schema file | Versioning ||--------|-------------|------------|-| `workspaces.config` | `src/shared/core/workspaces/workspace-config.ts` | v1 → v2 → v3 (versioned from start) |-| `workspaces.data` | `src/shared/core/workspaces/workspace-provider-data.ts` | unversioned (v0) |-| `conversations.config` | `src/shared/core/conversations/conversation-config.ts` | unversioned (v0) |+| `agents.provider_config` | `src/shared/core/agents/agent-provider-config.ts` | v1 (versioned from start) |+| `sessions.config` | `src/shared/core/sessions/session-config.ts` | unversioned (v0) |++The `workspaces.*` and `conversations.config` columns this table used to list are gone —+both tables were dropped when the location/session model replaced the upstream+project/workspace/conversation model. See `agents/architecture/data-model.md`.diff --git a/dash/agents/risky-areas/database.md b/dash/agents/risky-areas/database.mdindex 4c4abeeda..9d12982b1 100644--- a/dash/agents/risky-areas/database.md+++ b/dash/agents/risky-areas/database.md@@ -130,9 +130,8 @@ guidance.| Column | Schema file ||--------|-------------|-| `workspaces.config` | `src/shared/core/workspaces/workspace-config.ts` |-| `workspaces.data` | `src/shared/core/workspaces/workspace-provider-data.ts` |-| `conversations.config` | `src/shared/core/conversations/conversation-config.ts` |+| `agents.provider_config` | `src/shared/core/agents/agent-provider-config.ts` |+| `sessions.config` | `src/shared/core/sessions/session-config.ts` |### Snapshot columns and raw SQLdiff --git a/dash/agents/workflows/testing.md b/dash/agents/workflows/testing.mdindex 81c2e2afc..b9756c45c 100644--- a/dash/agents/workflows/testing.md+++ b/dash/agents/workflows/testing.md@@ -23,12 +23,14 @@ pnpm run test- Vitest config is in `vitest.config.ts` (separate from the build config in `electron.vite.config.ts`).- Five test projects:- - `node` — `src/**/*.test.ts` excluding `_*` dirs, browser tests, migration tests, `*.db.test.ts`, and `src/main/db/legacy-port/**/*.test.ts`- - `main-db` — `src/main/core/**/*.db.test.ts` and `src/main/db/legacy-port/**/*.test.ts` against real SQLite+ - `node` — `src/**/*.test.ts` excluding `_*` dirs, browser tests, migration tests, and `*.db.test.ts` under `src/main/core/` and `src/main/db/`+ - `main-db` — `src/main/core/**/*.db.test.ts` and `src/main/db/**/*.db.test.ts` against real SQLite- `fixtures` — fixture generator, run via `pnpm run db:fixtures`- `migrations` — `src/main/db/tests/migrations/**`, run via `pnpm run test:migrations`- `browser` — `src/renderer/tests/browser/**/*.test.{ts,tsx}` via Playwright- `pnpm run test` runs the `node`, `main-db`, `migrations`, and `browser` projects.+- Both project globs still mention `src/main/db/legacy-port/`, which no longer exists. The+ globs are harmless but match nothing — do not go looking for that directory.- Tests use per-file `vi.mock()` setup.- Integration-style tests create temporary project directories in `os.tmpdir()`.