opencode-remote-login 0.1.0 → 0.1.1

package/README.md

@@ -1,65 +1,94 @@
 # opencode-remote-login
 
-Dispatch opencode sessions to remote hosts and continue tasks there.
+Dispatch opencode sessions to remote hosts via SSH and continue tasks there.
+
+## Install
+
+```bash
+opencode plug opencode-remote-login
+```
+
+Or add to `opencode.jsonc` manually:
+
+```json
+{
+  "plugin": ["opencode-remote-login"]
+}
+```
 
 ## Setup
 
-1. Copy `hosts.example.json` to `hosts.json` and configure your hosts:
+1. Create `~/.config/opencode/hosts.json`:
 
 ```json
 {
   "hosts": {
-    "pi": "user@192.168.1.100",
+    "pi": {
+      "host": "wenjun@192.168.100.100",
+      "agent": "build",
+      "model": "opencode/big-pickle"
+    },
     "dev": "user@10.0.0.5"
   }
 }
 ```
 
-2. Ensure SSH key-based auth is configured for each host:
+2. Configure SSH key-based auth:
 
 ```bash
 ssh-copy-id user@192.168.1.100
 ```
 
-3. Add to your `opencode.json`:
+### Alternative: inline config
 
-```json
+```jsonc
+// opencode.jsonc
 {
-  "plugin": ["../opencode-remote-login/src/index.ts"]
+  "plugin": [
+    ["opencode-remote-login", {
+      "hosts": {
+        "pi": { "host": "wenjun@192.168.100.100" }
+      }
+    }]
+  ]
 }
 ```
 
+## Host config
+
+Each host entry supports:
+
+| Field   | Description                              |
+| ------- | ---------------------------------------- |
+| `host`  | SSH address (`user@host`)                |
+| `agent` | Agent name to use on the remote (optional) |
+| `model` | Model in `provider/id` format (optional)   |
+
+Only host **names** are exposed to the LLM. SSH addresses and credentials stay private.
+
 ## Usage
 
 ### One-way mode (default)
 
-Dispatch the session and return immediately. The remote host takes over autonomously.
+Dispatch and return immediately. The remote host takes over autonomously.
 
 ```
-> call remote_login host=pi, we need to fix the login bug in auth.ts
+> call remote_login host=pi, fix the login bug in auth.ts
 ```
 
 ### Round-trip mode
 
-Dispatch, wait for remote to complete, then pull the updated session back locally.
+Dispatch, wait for remote to complete, then pull the updated session back locally. The original agent and model are automatically restored on return.
 
 ```
 > call remote_login mode=round-trip host=pi, investigate the memory leak in worker.ts
 ```
 
-## hostnames.json
+### With working directory
 
-Only host **names** are exposed to the LLM in the tool description. Actual SSH addresses remain private.
-
-```json
-{
-  "hosts": {
-    "pi": "wenjun@192.168.100.100"
-  }
-}
 ```
-
-The LLM sees: `Available hosts: pi`
+> call remote_login host=pi directory=/home/wenjun/projects/myapp
+```
 
 ## How it works
 
@@ -67,9 +96,11 @@ The LLM sees: `Available hosts: pi`
 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
+2. patch agent/model from host config
+3. SCP → remote import
+4. Trigger remote task (nohup)
+5. [round-trip] poll for back-file
+6. [round-trip] SCP ← remote export
+7. [round-trip] restore original agent/model
+8. [round-trip] local import
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-remote-login",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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.