Document session-scoped SSH remote tools

Author: rcarmo

README.md

@@ -11,8 +11,8 @@ It is built for people who want a practical, stateful agent they can run locally
 ![Demo Animation](docs/demo.gif)
 
 - **Streaming web UI** — real-time chat with Markdown, KaTeX, Mermaid, and Adaptive Cards
-- **Persistent agent state** — SQLite-backed messages, media, tasks, token usage, and encrypted keychain
-- **Workspace-native workflow** — browse files, preview documents, upload attachments, edit code, and reference files in prompts
+- **Persistent agent state** — SQLite-backed messages, media, tasks, token usage, encrypted keychain, and per-chat SSH profiles
+- **Workspace-native workflow** — browse files, preview documents, upload attachments, edit code, reference files in prompts, and optionally flip core tools to a remote SSH host per chat
 - **Built-in tools** — Ghostty-based terminal, code editor, Office/PDF/CSV/image/video viewers, draw.io, kanban board and mindmap editors, VNC client, and browser automation
 - **Agent control features** — steering, queued follow-ups, threading, side prompts, autoresearch experiment loops, and scheduled tasks
 - **Optional auth and channels** — passkeys/TOTP for the web UI, plus optional WhatsApp integration
@@ -108,7 +108,7 @@ Key environment variables:
 | `PICLAW_KEYCHAIN_KEY` | _(empty)_ | Master key for encrypted secret storage |
 | `PICLAW_TRUST_PROXY` | `0` | Enable when behind a reverse proxy or tunnel |
 
-For the full list, auth setup (TOTP/passkeys), reverse proxy configuration, and SSHFS/FUSE support, see [docs/configuration.md](docs/configuration.md).
+For the full list, auth setup (TOTP/passkeys), per-chat SSH-backed remote tools, reverse proxy configuration, and SSHFS/FUSE support, see [docs/configuration.md](docs/configuration.md).
 
 ## Other install methods
 

docs/architecture.md

@@ -118,6 +118,7 @@ These are compiled into the package and registered via `extensionFactories` on t
 | `sqlIntrospect` | `introspect_sql` (read-only SQLite queries) |
 | `internalTools` | `list_internal_tools` |
 | `sendAdaptiveCard` | `send_adaptive_card` for agent-owned Adaptive Card posting |
+| `sshTool` | `ssh` agent-only tool for per-chat SSH profile get/set/clear |
 | `uiThemeExtension` | `/theme`, `/tint` web UI theme controls |
 | `smartCompaction` | Smart compaction via `session_before_compact` hook (DB-driven file lists, junk-path filtering) |
 
@@ -131,6 +132,7 @@ In addition to the inline factories, piclaw ships **optional extensions** under
 |-----------|------|---------|
 | `integrations/azure-openai.ts` | `AOAI_BASE_URL` must be set | Azure OpenAI + Foundry provider with managed-identity or API-key auth |
 | `integrations/context-mode.ts` | Always loaded | Tool-output storage, search handles, and `exec_batch` tool |
+| per-chat `ssh-core` session extension | Created per session by `AgentPool` | Wraps `read`/`write`/`edit`/`bash` with chat-scoped local-or-remote SSH execution |
 | `browser/cdp-browser/` | Always loaded | Cross-platform Chromium CDP browser control tool (`cdp_browser`) |
 | `platform/windows/win-ui/` | Always loaded (runtime no-op off Windows) | Windows desktop automation via bun:ffi + IAccessible (`win_*` tools) |
 | `viewers/drawio-editor/` | Always loaded | Self-hosted draw.io editor with extension route, save endpoint, and workspace export |
@@ -211,6 +213,7 @@ Page load
 - Web and WhatsApp share the same storage and agent pool.
 - Core utilities (config/env/chat context) live in `src/core`; shared helpers live in `src/utils`.
 - Chat context (chat JID + channel) is tracked in AsyncLocalStorage; tools/extensions read from the scoped context (defaults to `web:default` / `web`) rather than env variables.
+- SSH-backed core-tool state is chat-scoped and persisted in SQLite (`chat_ssh_configs`). `AgentPool` injects a per-session `ssh-core` extension and can hot-swap the live SSH backend for an existing warm chat session.
 - Workspace tree responses are cached briefly (1s) and rate-limited to prevent bursty UI reloads (HTTP 429 when exceeded).
 - The **workspace explorer** is a responsive sidebar (visible on desktop/tablet ≥1024px landscape) that shows a file tree of `/workspace`, supports file previews, drag-and-drop upload, inline file creation, inline rename, drag-and-drop move, and file reference pills for prompts.
 - The **code editor** is a standalone pane extension (`extensions/viewers/editor/`) using CodeMirror 6 directly (no Preact wrapper). It opens in the tabbed content area when a file is clicked in the explorer. Supports syntax highlighting for 12 languages, search/replace, line wrapping, dirty tracking, Cmd+S save, vim mode, whitespace toggle, and accent-aware theming. The editor bundle is lazy-loaded on first file open. Backend endpoints: `GET /workspace/file?mode=edit` (full content up to 256 KB) and `PUT /workspace/file` (save).

docs/configuration.md

@@ -118,6 +118,59 @@ Notes:
 
 Deprecated env names (still supported): `ASSISTANT_NAME`, `ASSISTANT_AVATAR`, `AGENT_TIMEOUT`, `AGENT_TIMEOUT_BACKGROUND`.
 
+## SSH-backed remote core tools
+
+Piclaw can redirect the core file/shell tools (`read`, `write`, `edit`, `bash`) to a remote host over SSH.
+
+There are two ways to enable it:
+
+1. **Startup/default session config** via env vars:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `PICLAW_SSH_TARGET` | _(empty)_ | SSH target as `user@host` or `user@host:/remote/path` |
+| `PICLAW_SSH_PORT` | `22` | SSH port for startup/default remote sessions |
+
+2. **Per-chat live config** via the agent-only `ssh` tool:
+   - `ssh { action: "set", ssh_target, private_key_keychain, ... }`
+   - `ssh { action: "get" }`
+   - `ssh { action: "clear" }`
+
+The `ssh` tool stores chat-scoped profiles in SQLite and applies them immediately to live sessions when possible. That means the agent can switch a chat from local → remote → local again in the same turn/session without recreating the session runtime.
+
+### Required key material
+
+Live per-chat SSH uses keychain-backed credentials:
+
+- `private_key_keychain` — required; keychain entry containing the OpenSSH private key
+- `known_hosts_keychain` — optional; keychain entry containing `known_hosts` content
+- `strict_host_key_checking` — `yes`, `accept-new`, or `no`
+
+Example tool payload:
+
+```json
+{
+  "action": "set",
+  "ssh_target": "[email protected]:/srv/project",
+  "ssh_port": 22,
+  "private_key_keychain": "ssh/prod",
+  "known_hosts_keychain": "ssh/prod.known_hosts",
+  "strict_host_key_checking": "accept-new"
+}
+```
+
+### Transport behavior
+
+The SSH backend keeps the same remote-tool semantics as the packaged SSH extension model:
+
+- multiplexed connection reuse with `ControlMaster=auto`
+- `ControlPersist=600`
+- persistent remote shell/session reuse across tool calls
+- remote cwd/home mapping from the configured target path
+- immediate live switching when the chat already has a warm session
+
+If a chat has no stored SSH profile, core tools run locally as usual.
+
 ### Assistant name and avatar
 
 Set via environment variables (see above) or in `.piclaw/config.json`:

docs/keychain.md

@@ -118,6 +118,32 @@ The tracked bash runner also replaces `keychain:<name>` placeholders directly in
 
 `keychain:<name>:username` resolves to the stored username (if present).
 
+## SSH keys and known_hosts entries
+
+The per-chat `ssh` tool expects SSH material to come from the keychain.
+
+Typical entries:
+
+- `ssh/prod` — type `secret`, secret = full OpenSSH private key
+- `ssh/prod.pub` — optional public key copy
+- `ssh/prod.known_hosts` — optional `known_hosts` text blob
+
+Example:
+
+```bash
+PICLAW_KEYCHAIN_KEY="your-master-key" \
+  piclaw keychain set ssh/prod \
+    --type secret \
+    --secret-file ~/.ssh/id_ed25519
+
+PICLAW_KEYCHAIN_KEY="your-master-key" \
+  piclaw keychain set ssh/prod.known_hosts \
+    --type secret \
+    --secret-file ~/.ssh/known_hosts
+```
+
+The runtime writes these values to temporary files with restrictive permissions and uses them for the SSH control connection.
+
 ## Notes
 
 - Entry names can be hierarchical (`github/foo/bar`).

docs/runtime-flows.md

@@ -219,6 +219,47 @@ Without isolation, a scheduled task's prompt and response would appear in the ag
 - **Model safety**: The model is restored to its pre-task state on the correct branch.
 - **No session forking**: Unlike `fork()` which creates a new session file, `navigateTree()` stays in the same file and simply moves the branch pointer.
 
+## Session-scoped SSH remote tools
+
+A chat can optionally switch its core file/shell tools to a remote host over SSH.
+
+- Control surface: agent-only `ssh` tool
+- Scope: one chat JID at a time
+- Persistence: SQLite `chat_ssh_configs`
+- Affected tools: `read`, `write`, `edit`, `bash`
+
+The important runtime property is that SSH mode is **live mutable**. If a warm session already exists, `ssh set` and `ssh clear` can flip the backend immediately for the next tool/model step without rebuilding the whole session.
+
+```mermaid
+sequenceDiagram
+  participant Agent
+  participant ssh as ssh tool
+  participant Pool as AgentPool
+  participant DB as SQLite
+  participant Core as ssh-core wrappers
+  participant Host as Local or Remote host
+
+  Agent->>ssh: action=set target+keychain
+  ssh->>Pool: setChatSshConfig(chatJid, config)
+  Pool->>DB: upsert chat_ssh_configs
+  Pool->>Core: applyLiveChatSshConfig(chatJid)
+  Core-->>Host: next read/write/edit/bash uses SSH
+
+  Agent->>ssh: action=clear
+  ssh->>Pool: clearChatSshConfig(chatJid)
+  Pool->>DB: delete chat_ssh_configs row
+  Pool->>Core: clearLiveChatSshConfig(chatJid)
+  Core-->>Host: next core tool call runs locally
+```
+
+Transport semantics match the packaged SSH extension model:
+
+- multiplexed connection reuse
+- `ControlMaster=auto`
+- `ControlPersist=600`
+- persistent remote shell state
+- configured remote cwd/home mapping
+
 ## Session lifecycle (summary)
 
 - Messages for a chat JID share a warm `AgentSession`.

docs/tools-and-skills.md

@@ -64,12 +64,24 @@ You can extend that baseline with `.piclaw/config.json`:
 - `exec_batch` — run multiple shell commands and return concise summaries for each
 - `powershell` — Windows-only replacement for the default shell tool; active instead of `bash` on Windows hosts
 - `exit_process` — gracefully terminate piclaw so Supervisor restarts it; kept always active because lifecycle control should not depend on same-turn lazy activation
+- `ssh` — get, set, or clear the session-scoped SSH profile used by remote-backed core tools (`read`, `write`, `edit`, `bash`)
 
 `messages` `search` accepts `query`, `chat_jid` (or `*`/`all`), `role`, `after`, `before`, `since`, `limit`, `offset`, and `details_max_chars` for controlling detail payloads.
 `messages` `get` accepts `row_ids`, optional `chat_jid`, `role`, `context_before`, `context_after`, and `details_max_chars`.
 `messages` `add` accepts `content`, optional `chat_jid`, `type` (`user` or `agent`), and `media_ids`.
 `messages` `delete` accepts `row_ids` and optional `chat_jid`, `force`, and `dry_run`.
 
+`ssh` accepts:
+- `action` — `get`, `set`, or `clear`
+- `chat_jid` — optional override; defaults to the current chat
+- `ssh_target` — `user@host` or `user@host:/remote/path`
+- `ssh_port` — optional port (default `22`)
+- `private_key_keychain` — keychain entry containing the private key
+- `known_hosts_keychain` — optional keychain entry containing `known_hosts`; empty string clears it
+- `strict_host_key_checking` — `yes`, `accept-new`, or `no`
+
+When a live session already exists for the chat, `ssh set` and `ssh clear` apply immediately to subsequent tool/model steps in the same turn.
+
 `search_workspace` accepts:
 - `query` — FTS query text
 - `scope` — `notes`, `skills`, or `all` (default)