opencode-remote-login 0.1.0 → 0.1.2

package/README.md

@@ -1,75 +1,98 @@
 # opencode-remote-login
 
-Dispatch opencode sessions to remote hosts and continue tasks there.
+Dispatch opencode sessions to remote hosts via SSH. Migrate context, execute tasks remotely, and optionally pull results back.
 
-## Setup
+## Install
 
-1. Copy `hosts.example.json` to `hosts.json` and configure your hosts:
+```bash
+opencode plug opencode-remote-login
+```
+
+This adds the plugin to your `opencode.jsonc`. The `remote_login` tool becomes available immediately.
+
+## Configure hosts
+
+Hosts are defined via a `hosts` entry in one of these locations (checked in order):
+
+**Option 1 — `~/.config/opencode/hosts.json`**
 
 ```json
 {
   "hosts": {
-    "pi": "user@192.168.1.100",
-    "dev": "user@10.0.0.5"
+    "pi": {
+      "host": "wenjun@192.168.100.100",
+      "agent": "build",
+      "model": "opencode/big-pickle"
+    }
   }
 }
 ```
 
-2. Ensure SSH key-based auth is configured for each host:
+**Option 2 — Inline in `opencode.jsonc`**
 
-```bash
-ssh-copy-id user@192.168.1.100
+```jsonc
+{
+  "plugin": [
+    ["opencode-remote-login", {
+      "hosts": {
+        "pi": { "host": "wenjun@192.168.100.100" }
+      }
+    }]
+  ]
+}
 ```
 
-3. Add to your `opencode.json`:
+### Host fields
 
-```json
-{
-  "plugin": ["../opencode-remote-login/src/index.ts"]
-}
+| Field   | Required | Description                            |
+| ------- | -------- | -------------------------------------- |
+| `host`  | Yes      | SSH address (`user@host`)              |
+| `agent` | No       | Override agent on the remote           |
+| `model` | No       | Override model in `provider/id` format |
+
+Only host **names** are shown to the LLM; SSH addresses stay on disk.
+
+### SSH setup
+
+```bash
+ssh-copy-id user@192.168.100.100
 ```
 
 ## Usage
 
-### One-way mode (default)
+### One-way
 
-Dispatch the session and return immediately. The remote host takes over autonomously.
+Hand off the session and return. The remote host picks up the task autonomously.
 
 ```
-> call remote_login host=pi, we need to fix the login bug in auth.ts
+> call remote_login host=pi, fix the auth bug
 ```
 
-### Round-trip mode
+### Round-trip
 
-Dispatch, wait for remote to complete, then pull the updated session back locally.
+Wait for the remote to finish, then pull results back. The original agent and model are restored automatically on return.
 
 ```
-> call remote_login mode=round-trip host=pi, investigate the memory leak in worker.ts
+> call remote_login mode=round-trip host=pi, find the memory leak
 ```
 
-## hostnames.json
-
-Only host **names** are exposed to the LLM in the tool description. Actual SSH addresses remain private.
+### Target directory
 
-```json
-{
-  "hosts": {
-    "pi": "wenjun@192.168.100.100"
-  }
-}
+```
+> call remote_login host=pi directory=/home/wenjun/projects/app
 ```
 
-The LLM sees: `Available hosts: pi`
+Omit to default to `~`.
 
 ## How it works
 
 ```
-local opencode                    remote opencode
-─────────────                    ───────────────
-1. export session (JSON)
-2. SCP → remote import
-3. Trigger remote task (nohup)
-4. [round-trip] poll for back-file
-5. [round-trip] SCP ← remote export
-6. [round-trip] local import
+local                                     remote
+─────                                     ──────
+export session JSON
+patch agent/model per host config ────→   SCP + import session
+                                          nohup opencode run --session=<id>
+[round-trip] poll for completion     ←──  export session JSON
+[round-trip] restore agent/model
+[round-trip] import back
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-remote-login",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "exports": {
     "./server": "./src/index.ts"

package/NOTES.md

@@ -1,100 +0,0 @@
-# Implementation Notes
-
-## Architecture
-
-```
-opencode-remote-login/
-├── package.json       # exports: ./server (plugin entry)
-├── hosts.json         # host aliases (gitignored)
-├── hosts.example.json # template
-└── src/
-    └── index.ts       # server plugin (~250 lines)
-```
-
-The plugin registers a single tool `remote_login` with two modes (`one-way` / `round-trip`) and a `tool.execute.after` hook that triggers `promptAsync` after round-trip completes.
-
-## Round-trip Flow
-
-```
-local                                              remote
-─────                                              ──────
-1. opencode export <sid>          → stdout JSON
-2. fixPendingRemoteLogin()        ← patch pending tool-call in JSON
-3. writeFile → SCP                → /tmp/opencode-import-<sid>.json
-4. SSH opencode import            → writes to remote SQLite
-5. SCP script → SSH bash          → nohup opencode run --session=<sid>
-6. poll: SSH "test -f back-file"  → wait for remote export
-7. SCP back-file ←                ← opencode export <sid>
-8. opencode import back-file      → writes to local SQLite
-9. [hook] promptAsync fork        → LLM processes imported context
-```
-
-## Pitfalls and Lessons
-
-### 1. `opencode export` captures the tool mid-execution
-
-The export subprocess runs while the `remote_login` tool is still executing. The exported JSON shows the tool call in `"pending"` state with empty input. The remote LLM sees an incomplete tool call and gets confused.
-
-**Fix**: `fixPendingRemoteLogin()` patches the last assistant message's `remote_login` tool part from `pending` → `completed` with proper output and a `step-finish` part.
-
-### 2. Shell quoting across SSH boundaries
-
-Building shell commands with nested quoting (ssh → bash → opencode run) is fragile. Double quotes in the continuation message were passed literally to the remote LLM.
-
-**Fix**: Write a shell script file locally, SCP it to remote, then execute it. Avoids quoting hell entirely.
-
-### 3. `execSync` blocks the event loop
-
-`child_process.execSync` is synchronous and blocks Node's event loop. This is fine for shell commands but incompatible with async SDK calls.
-
-**Fix**: All SDK calls (`promptAsync`) are done OUTSIDE `execSync` blocks, either after all sync work is done or in hooks.
-
-### 4. `session.prompt({ noReply: true })` does not persist
-
-Looking at the source (`prompt.ts:1631`): when `noReply === true`, the message is created in memory and returned via HTTP but never written to SQLite. No SSE events are emitted. The TUI never sees it.
-
-**Lesson**: Always verify persistence behavior in the source code.
-
-### 5. `session.prompt({ noReply: false })` blocks the tool pipeline
-
-Calling `session.prompt` (without `noReply`) from within `tool.execute.after` hook blocks the entire tool execution pipeline waiting for LLM processing. The session state transitions cause conflicts.
-
-**Lesson**: `tool.execute.after` runs synchronously within the tool execution Effect fiber. Don't block it.
-
-### 6. `promptAsync` has a different API shape than `prompt`
-
-```ts
-// prompt (v1 SDK)
-session.prompt({ id: string, parts: [...] })
-
-// promptAsync (v1 SDK)
-session.promptAsync({ path: { id: string }, body: { parts: [...] } })
-```
-
-Using the `prompt` shape for `promptAsync` resulted in `{id}` not being substituted in the URL path, causing `%7Bid%7D` errors.
-
-**Lesson**: Always check the generated SDK types. Don't assume consistent API shapes.
-
-### 7. `promptAsync` forks via `Effect.forkIn(scope)` — scope matters
-
-The `promptAsync` handler forks the LLM loop into the HTTP request's scope. The forked fiber runs independently of the caller. The hook returns immediately while the LLM processes in the background. SSE events are emitted for the response.
-
-**Key insight**: This is the only way to trigger LLM processing from a plugin hook without blocking. The `Effect.forkIn(scope, { startImmediately: true })` pattern makes the prompt fire-and-forget.
-
-### 8. TUI session messages are loaded once, then updated via SSE events only
-
-The TUI loads session messages on first entry (`createResource` → `sync.session.sync()`). After that, messages are only added/updated via SSE events (`message.updated`). Direct DB writes by subprocesses produce no SSE events, so the TUI never shows them.
-
-**Fix**: Use `promptAsync` (which goes through the server API and emits SSE) to trigger a visible response. The full imported history is in the DB and visible after restart.
-
-### 9. Cross-platform `sleep` needs a JavaScript spin-loop
-
-`child_process.execSync('sleep 2')` fails on Windows. `execSync('timeout /t 2')` fails on Linux. Using `process.platform` branching is fragile.
-
-**Fix**: Simple spin-loop `while (Date.now() < end) {}` works everywhere.
-
-### 10. Host config should be separate from code
-
-Hardcoding SSH addresses in the plugin is inflexible and leaks info to the LLM.
-
-**Fix**: `hosts.json` maps host names to addresses. Only names are injected into the tool description. The file is gitignored; `hosts.example.json` serves as a template.