my-pi/pi-ssh/extension-spec.md

# pi-ssh extension specification

## Goal

Pi and its default tools remain local. Explicit collision-free tools perform selected operations on one configured remote server:

- `ssh_connect`
- `ssh_cd`
- `ssh_read`
- `ssh_write`
- `ssh_edit`
- `ssh_find`
- `ssh_grep`
- `ssh_bash`

The extension is for operating servers from local projects, not for replacing Pi's local workspace. It never auto-loads remote project instructions.

## Connection model

Runtime communication uses Node `ssh2` only. OpenSSH is not spawned during Pi sessions. A user must explicitly import a concrete OpenSSH alias before connecting:

```text
ssh_config.sh import <alias>
  → ssh -G <alias>
  → user chooses private-key or password auth
  → ssh2 obtains host key, user confirms fingerprint
  → ssh2 verifies authentication
  → encrypted vault is updated
```

The resulting host ID is the only runtime selector. When a direct user request names that imported host as part of a concrete remote task, the agent calls:

```text
ssh_connect({ hostId: "<host-id>", remotePath?: "/absolute/or/~/path" })
```

`ssh_connect` is the only runtime connection surface. It is a sequential, cancellable model tool governed by `pi-permission-system`: the agent calls it as a separate step and waits for success before dependent remote tools, so establishing or replacing a connection cannot overlap another tool call. Unknown IDs return at most ten sorted imported IDs and never endpoint credentials. There is no `/ssh` command, `--ssh` flag, session-resume reconnect, or user `!` remote-shell override.

Arbitrary `user@host`, port overrides, ProxyJump, and ProxyCommand are not supported in the first pure-ssh2 version. Unsupported imported configuration is rejected rather than ignored.

## Vault

Default paths:

```text
${XDG_CONFIG_HOME:-$HOME/.config}/my-pi/pi-ssh/hosts.enc
${XDG_CONFIG_HOME:-$HOME/.config}/my-pi/pi-ssh/vault.key
```

The directory is mode `700` and files are mode `600` on POSIX. A random adjacent 256-bit key encrypts and authenticates the complete validated configuration with AES-256-GCM. Each write uses a fresh IV and atomic replacement; plaintext is never written to a temporary file.

The adjacent-key design prevents casual disclosure of `hosts.enc` alone but does not protect against code able to read both files as the same local user.

The encrypted payload includes endpoint, authentication data, host groups, default cwd, and a pinned SHA256 host-key fingerprint. Private keys remain in their original paths; only their path and optional passphrase are stored.

## Authentication

Supported methods:

- password;
- single-password keyboard-interactive;
- OpenSSH private key;
- encrypted private key with passphrase.

Passwords, passphrases, private-key contents, vault key, and decrypted configuration must never enter command arguments, logs, permission evidence, system prompts, or Pi session entries.

## Host-key verification

Import displays the observed host-key algorithm and SHA256 fingerprint for explicit confirmation. Runtime `hostVerifier` must compare the server key with the pinned fingerprint and fail closed on any mismatch. Key changes require explicit host update.

## Transport

One persistent `ssh2.Client` belongs to the active host. The transport persists, but there is no persistent interactive shell or PTY. Connection loss fails closed and no operation is automatically replayed.

### Shell

`ssh_bash` opens a fresh exec channel and non-interactive Bash process for every call. Commands run through `bash -lc` after changing to the active remote cwd. The cwd supplied by Pi's local Bash factory is ignored at the transport adapter boundary; only connection state may select the remote cwd. A command-local `cd` is intentionally temporary; shell-local `cd`, exports, aliases, functions, and other process state do not persist across calls. Output streams through the normal Pi Bash operations callback. Abort or timeout closes the channel without reconnecting or replaying.

`ssh_cd` is the explicit persistent workspace operation and declares Pi's sequential execution mode so it cannot overlap sibling tool calls. It resolves absolute paths, paths relative to the active remote cwd, and `~/` paths relative to remote HOME; validates the directory by executing `pwd` from it; and updates connection state without reconnecting. The model calls it as a separate step and waits for success before issuing subsequent relative file/search operations or `ssh_bash` calls that depend on the updated cwd.

### Files

SFTP implements file operations:

- read and access checks;
- recursive directory creation;
- remote write through a temporary file;
- atomic OpenSSH rename extension when available;
- safe direct-write fallback when SFTP v3 cannot replace an existing target.

Remote paths map from Pi's local factory cwd into the selected remote cwd, but permission-system access extractors prevent those paths from entering local path normalization.

### Search

Search tools execute one capability-adaptive, bounded shell pipeline inside the already approved tool call. They never install or upload binaries.

- `ssh_find`: `fd` → `fdfind` → `git ls-files` → `find`; fixed filename/path substring semantics.
- `ssh_grep`: `rg` → `git grep` → `find + grep`; literal case-insensitive semantics by default, optional hidden-path inclusion, basename-only include globs, and a portable POSIX ERE subset when literal mode is disabled.
- each backend emits at most `limit + 1` NUL-delimited path/line/content records so truncation is explicit and newline filenames remain one result; public `limit` is 1–200; each returned line is capped.
- relative paths resolve against remote cwd and `~/` against remote home; other `~user` forms are rejected.
- the search target root is passed to the backend as an absolute argument, while the search process executes from the active remote cwd; a single-file `ssh_grep` target is never used as a process cwd.
- searches time out after 30 seconds with the resolved root and explicit guidance to narrow it before retrying.
- user strings are single-quoted as shell arguments and NUL/newline input is rejected.
- backend stdout contains only parseable results; stderr is captured independently for warnings and failure diagnostics.
- capability detection occurs only within the reviewed search call.
- search output is normalized by `pi-ssh` and excluded from RTK compaction.

Direct search commands remain denied through `ssh_bash`; structured search tools are the authoritative remote search surface.

## Permission boundary

There is one permission gate: `pi-permission-system`.

- `ssh_connect` defaults to `ask`; its preview resolves the imported host ID to the non-secret endpoint, port, and requested/default cwd before connection.
- `ssh_cd`, `ssh_read`, `ssh_write`, `ssh_edit`, `ssh_find`, and `ssh_grep` default to `ask`; remote path extractors disable local path normalization for all six tools, while previews resolve relative and `~/` requests against the active remote cwd/HOME and display both requested and absolute paths.
- `ssh_bash` is a Bash-semantic `shellTools` alias with `decisionFloor: "ask"`.
- Bash hard denies remain denies.
- All asks enter the configured authorizer chain.
- Permission service absence or bridge registration failure must not install a permissive fallback.

Evidence includes configured host ID, endpoint, port, remote cwd, and a bounded operation summary, never credentials.

Connection HOME/cwd discovery and `ssh_cd` validation use a bounded random-marker probe over a cancellable exec channel. The parser accepts exactly one framed absolute POSIX path; startup banners, malformed/multiline values, overflow, timeout, or cancellation cannot update connection state. Independent exec operations use at most four concurrent SSH channels, while SFTP operations remain serialized.

## Session lifecycle

Connections are created only by an approved `ssh_connect` call after session start. They are not persisted or automatically resumed. Connecting another imported host disposes the previous client, and session shutdown disposes the active client.

The system prompt states that default tools are local, `ssh_*` tools are remote, and each `ssh_bash` call starts a fresh non-interactive shell after a connection becomes active. It directs persistent workspace changes through `ssh_cd` and does not include remote file content.