opencode-remote-login 0.1.0

package/NOTES.md

@@ -0,0 +1,100 @@
+# 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.

package/README.md

@@ -0,0 +1,75 @@
+# opencode-remote-login
+
+Dispatch opencode sessions to remote hosts and continue tasks there.
+
+## Setup
+
+1. Copy `hosts.example.json` to `hosts.json` and configure your hosts:
+
+```json
+{
+  "hosts": {
+    "pi": "user@192.168.1.100",
+    "dev": "user@10.0.0.5"
+  }
+}
+```
+
+2. Ensure SSH key-based auth is configured for each host:
+
+```bash
+ssh-copy-id user@192.168.1.100
+```
+
+3. Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["../opencode-remote-login/src/index.ts"]
+}
+```
+
+## Usage
+
+### One-way mode (default)
+
+Dispatch the session and return immediately. The remote host takes over autonomously.
+
+```
+> call remote_login host=pi, we need to fix the login bug in auth.ts
+```
+
+### Round-trip mode
+
+Dispatch, wait for remote to complete, then pull the updated session back locally.
+
+```
+> call remote_login mode=round-trip host=pi, investigate the memory leak in worker.ts
+```
+
+## hostnames.json
+
+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`
+
+## 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
+```

package/hosts.example.json

@@ -0,0 +1,9 @@
+{
+  "hosts": {
+    "gpu-server": {
+      "host": "dev@10.0.0.5",
+      "agent": "build",
+      "model": "opencode/big-pickle"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "opencode-remote-login",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    "./server": "./src/index.ts"
+  },
+  "engines": {
+    "opencode": "^1.0.0"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "latest"
+  }
+}

package/src/index.ts

@@ -0,0 +1,378 @@
+import { execSync } from "child_process"
+import { writeFileSync, unlinkSync, readFileSync, existsSync } from "fs"
+import { tmpdir, homedir } from "os"
+import { join, dirname } from "path"
+import { randomBytes } from "crypto"
+import { fileURLToPath } from "url"
+
+const pluginDir = dirname(fileURLToPath(import.meta.url))
+
+type HostConfig = { host: string; agent?: string; model?: string }
+
+function opencodeConfigDir(): string {
+  if (process.env.OPENCODE_CONFIG_DIR) return process.env.OPENCODE_CONFIG_DIR
+  const home = homedir()
+  if (process.platform === "win32") return join(process.env.APPDATA || home, "opencode")
+  if (process.platform === "darwin") return join(home, "Library", "Application Support", "opencode")
+  return join(process.env.XDG_CONFIG_HOME || join(home, ".config"), "opencode")
+}
+
+function loadHosts(inlineHosts: any): Record<string, HostConfig> {
+  const paths = [join(opencodeConfigDir(), "hosts.json"), join(pluginDir, "..", "hosts.json")]
+
+  const inline = parseHostsEntry(inlineHosts)
+  if (inline) return inline
+
+  for (const configPath of paths) {
+    if (!existsSync(configPath)) continue
+    try {
+      const raw = JSON.parse(readFileSync(configPath, "utf-8"))
+      const parsed = parseHostsEntry(raw?.hosts)
+      if (parsed) return parsed
+    } catch {}
+  }
+  return {}
+}
+
+function parseHostsEntry(raw: unknown): Record<string, HostConfig> | undefined {
+  if (!raw || typeof raw !== "object") return undefined
+  const entries = raw as Record<string, unknown>
+  const result: Record<string, HostConfig> = {}
+  let found = false
+  for (const [name, value] of Object.entries(entries)) {
+    if (typeof value === "string") {
+      result[name] = { host: value }
+      found = true
+    } else if (value && typeof value === "object") {
+      const v = value as { host: string; agent?: string; model?: string }
+      if (typeof v.host === "string") {
+        result[name] = { host: v.host, agent: v.agent, model: v.model }
+        found = true
+      }
+    }
+  }
+  return found ? result : undefined
+}
+
+const plugin = {
+  id: "opencode-remote-login",
+  server: async (_input: any, options?: Record<string, unknown>) => {
+    const hosts = loadHosts(options?.hosts)
+    const hostList = Object.keys(hosts).sort().join(", ")
+
+    const localClient = _input.client
+    const localDir = _input.directory
+    const localOS = process.platform === "win32" ? "Windows" : process.platform === "darwin" ? "macOS" : "Linux"
+    return {
+      tool: {
+        remote_login: {
+          description: `Dispatch the current session to a remote opencode host and continue the task there.
+Available hosts: ${hostList || "(none configured in hosts.json)"}`,
+          args: {
+            host: {
+              type: "string",
+              description: `Target host name. Available: ${hostList || "none"}`,
+            },
+            mode: {
+              type: "string",
+              description: "one-way: dispatch and return immediately. round-trip: wait for remote to finish, then pull the updated session back.",
+            },
+            directory: {
+              type: "string",
+              description: "Optional: working directory on the remote host (auto-created if missing). Defaults to home directory.",
+            },
+          },
+          async execute(args: any, ctx: any) {
+            const sessionID = ctx.sessionID
+            const hostName = ((args.host as string) ?? "").trim()
+            const hostCfg = hosts[hostName]
+            const host = hostCfg?.host ?? hostName
+            const mode = (args.mode as string) ?? "one-way"
+            const workDir = ((args.directory as string) ?? "").trim()
+
+            if (!hostName) {
+              return { output: `host is required. Available: ${hostList || "none"}` }
+            }
+
+            // 1. Export current session
+            let exportJson: string
+            try {
+              exportJson = execSync(`opencode export ${winQuote(sessionID)}`, {
+                encoding: "utf-8",
+                stdio: ["pipe", "pipe", "pipe"],
+              })
+            } catch (e: any) {
+              return { output: `Export failed: ${e.message}` }
+            }
+
+            if (!exportJson.trim()) {
+              return { output: `Export returned empty data for session ${sessionID}` }
+            }
+
+            // 2. Fix pending remote_login tool-call
+            let exportData: any
+            try { exportData = JSON.parse(exportJson) } catch {
+              return { output: "Export JSON parse failed" }
+            }
+            fixPendingRemoteLogin(exportData, hostName, sessionID)
+
+            const localAgent = exportData.info?.agent
+            const localModel = exportData.info?.model
+            if (hostCfg) patchAgentAndModel(exportData, hostCfg.agent, hostCfg.model)
+
+            // 3. Write JSON to temp file
+            const tmpFile = join(tmpdir(), `opencode-export-${randomBytes(6).toString("hex")}.json`)
+            writeFileSync(tmpFile, JSON.stringify(exportData), "utf-8")
+
+            // 4. SCP to remote
+            const remoteFile = `/tmp/opencode-import-${sessionID}.json`
+            try {
+              execSync(`scp ${winQuote(tmpFile)} ${host}:${remoteFile}`, {
+                encoding: "utf-8",
+                stdio: "pipe",
+              })
+            } catch (e: any) {
+              unlinkSync(tmpFile)
+              return { output: `SCP transfer failed: ${e.message}` }
+            }
+
+            // 5. Import on remote
+            try {
+              execSync(`ssh ${host} opencode import ${remoteFile}`, {
+                encoding: "utf-8",
+                stdio: "pipe",
+              })
+            } catch (e: any) {
+              unlinkSync(tmpFile)
+              return { output: `Remote import failed: ${e.message}` }
+            }
+
+            unlinkSync(tmpFile)
+            try { execSync(`ssh ${host} rm ${remoteFile}`, { stdio: "ignore" }) } catch { /* ok */ }
+
+            // 6. Execute on remote
+            const cdLine = workDir ? `mkdir -p ${workDir} && cd ${workDir}` : `cd ~`
+            const scriptFile = join(tmpdir(), `opencode-continue-${randomBytes(6).toString("hex")}.sh`)
+            const logFile = `/tmp/opencode-continue-${sessionID}.log`
+
+            if (mode === "round-trip") {
+              writeFileSync(scriptFile, [
+                `#!/bin/bash`,
+                cdLine,
+                `CWD=$(pwd)`,
+                `export MSG="[Environment]`,
+                `You are now on remote host ${hostName}, working directory: $CWD.`,
+                `This session was migrated from a ${localOS} machine — all conversation history, tool results, and task context are preserved.`,
+                ``,
+                `[Constraints]`,
+                `- The local machine's filesystem and tools are NOT accessible from here.`,
+                `- Use this host's filesystem, tools, and resources exclusively.`,
+                `- Do not delegate to other hosts or call remote_login again.`,
+                ``,
+                `[Task]`,
+                `Complete the assigned task on this host.`,
+                ``,
+                `[Return]`,
+                `After you finish, this session will be exported and pulled back to the original machine automatically. Stop immediately once the work is done. Do not continue chatting or ask follow-up questions."`,
+                `nohup bash -c 'opencode run --session=${sessionID} "$MSG" > ${logFile} 2>&1; opencode export ${sessionID} > /tmp/opencode-back-${sessionID}.json' &`,
+              ].join("\n"), "utf-8")
+
+              try {
+                execSync(`scp ${winQuote(scriptFile)} ${host}:/tmp/opencode-continue.sh`, { encoding: "utf-8", stdio: "pipe" })
+                unlinkSync(scriptFile)
+                execSync(`ssh ${host} "bash /tmp/opencode-continue.sh && rm /tmp/opencode-continue.sh"`, { encoding: "utf-8", stdio: "pipe" })
+              } catch (e: any) {
+                return { output: `Remote execution failed: ${e.message}` }
+              }
+
+              // Poll for back-file
+              const backRemote = `/tmp/opencode-back-${sessionID}.json`
+              let ready = false
+              for (let i = 0; i < 30; i++) {
+                wait(2)
+                try {
+                  const r = execSync(`ssh ${host} "test -f ${backRemote} && echo ok"`, { encoding: "utf-8", stdio: "pipe" })
+                  if (r.trim() === "ok") { ready = true; break }
+                } catch {}
+              }
+
+              if (!ready) {
+                return {
+                  output: [
+                    `Task dispatched to ${hostName} but results not ready after 60s.`,
+                    `Pull manually: scp ${host}:${backRemote} . && opencode import <file>`,
+                  ].join("\n"),
+                }
+              }
+
+              // Pull back
+              const backFile = join(tmpdir(), `opencode-back-${randomBytes(6).toString("hex")}.json`)
+              try {
+                execSync(`scp ${host}:${backRemote} ${winQuote(backFile)}`, { encoding: "utf-8", stdio: "pipe" })
+                execSync(`ssh ${host} rm ${backRemote}`, { stdio: "ignore" })
+                if (hostCfg) restoreAgentAndModel(backFile, localAgent, localModel)
+                execSync(`opencode import ${winQuote(backFile)}`, { encoding: "utf-8", stdio: "pipe" })
+                unlinkSync(backFile)
+              } catch (e: any) {
+                return { output: `Pull-back failed: ${e.message}` }
+              }
+
+              return {
+                title: `Round-trip completed via ${hostName}`,
+                output: [
+                  `Session ${sessionID} completed on ${hostName} and pulled back.`,
+                  `The updated session with remote results is now available locally.`,
+                ].join("\n"),
+              }
+            }
+
+            // One-way: nohup background
+            writeFileSync(scriptFile, [
+              `#!/bin/bash`,
+              cdLine,
+              `CWD=$(pwd)`,
+              `MSG="[Environment]`,
+              `You are now on remote host ${hostName}, working directory: $CWD.`,
+              `This session was migrated from a ${localOS} machine — all conversation history, tool results, and task context are preserved.`,
+              ``,
+              `[Constraints]`,
+              `- The local machine's filesystem and tools are NOT accessible from here.`,
+              `- Use this host's filesystem, tools, and resources exclusively.`,
+              `- Do not delegate to other hosts or call remote_login again.`,
+              ``,
+              `[Task]`,
+              `Continue the assigned task from where it left off. Complete the work and stop."`,
+              `nohup opencode run --session=${sessionID} "$MSG" > ${logFile} 2>&1 &`,
+            ].join("\n"), "utf-8")
+
+            try {
+              execSync(`scp ${winQuote(scriptFile)} ${host}:/tmp/opencode-continue.sh`, { encoding: "utf-8", stdio: "pipe" })
+              unlinkSync(scriptFile)
+              execSync(`ssh ${host} "bash /tmp/opencode-continue.sh && rm /tmp/opencode-continue.sh"`, { encoding: "utf-8", stdio: "pipe" })
+            } catch (e: any) {
+              return {
+                output: [
+                  `Session ${sessionID} migrated to ${hostName}, but auto-continue failed: ${e.message}`,
+                  `Run manually: ssh ${host} "opencode --session=${sessionID}"`,
+                ].join("\n"),
+              }
+            }
+
+            return {
+              title: `Task handed off to ${hostName}`,
+              output: [
+                `Session ${sessionID} has been migrated to ${hostName}. The remote host is executing the task.`,
+                `This conversation ends here. Do not reply.`,
+              ].join("\n"),
+            }
+          },
+        },
+      },
+      "tool.execute.after": async (input: any) => {
+        if (input.tool !== "remote_login") return
+        if (input.args?.mode !== "round-trip") return
+        const host = input.args?.host ?? "remote"
+        const dir = input.args?.directory || "~"
+        try {
+          await localClient.session.promptAsync({
+            path: { id: input.sessionID },
+            body: {
+              parts: [{
+                text: [
+                  `[Status]`,
+                  `Round-trip completed. Remote host "${host}" (${dir}) has finished execution and all results have been merged into this session.`,
+                  ``,
+                  `[Environment]`,
+                  `You are now back on the local ${localOS} machine in ${localDir}.`,
+                  ``,
+                  `[Constraints]`,
+                  `- Remote files and paths (e.g., /tmp, ~/ on "${host}") are NOT directly accessible from this environment.`,
+                  `- Any further operations requiring the remote host must use the remote_login tool again.`,
+                  ``,
+                  `[Next Steps]`,
+                  `Review the remote execution results from the conversation history above. Do not re-execute tasks already completed on the remote.`,
+                ].join("\n"),
+                type: "text",
+              }],
+            },
+          })
+        } catch {}
+      },
+    }
+  },
+}
+
+export default plugin
+
+function winQuote(arg: string): string {
+  return `"${arg}"`
+}
+
+function wait(seconds: number) {
+  const end = Date.now() + seconds * 1000
+  while (Date.now() < end) {}
+}
+
+function patchAgentAndModel(data: any, agentVal: string | undefined, modelVal: string | undefined) {
+  if (!data?.info) return
+  const agent = ((agentVal as string) ?? "").trim()
+  const model = ((modelVal as string) ?? "").trim()
+
+  if (agent) {
+    data.info.agent = agent
+  }
+
+  if (model) {
+    const [providerID, ...rest] = model.split("/")
+    const modelID = rest.join("/")
+    if (providerID && modelID) {
+      data.info.model = { providerID, id: modelID }
+    }
+  }
+}
+
+function restoreAgentAndModel(filePath: string, agent: any, model: any) {
+  if (agent === undefined && model === undefined) return
+  try {
+    const data = JSON.parse(readFileSync(filePath, "utf-8"))
+    if (!data?.info) return
+    if (agent !== undefined) data.info.agent = agent
+    if (model !== undefined) data.info.model = model
+    writeFileSync(filePath, JSON.stringify(data), "utf-8")
+  } catch {}
+}
+
+function fixPendingRemoteLogin(data: any, hostName: string, sessionID: string) {
+  if (!data?.messages?.length) return
+  const msgs = data.messages as any[]
+  const last = msgs[msgs.length - 1]
+  if (!last?.info || last.info.role !== "assistant" || !last.parts?.length) return
+
+  const toolPart = last.parts.find((p: any) => p.type === "tool" && p.tool === "remote_login" && p.state?.status === "pending")
+  if (!toolPart) return
+
+  const now = Date.now()
+  const output = `Login successful. Session migrated to ${hostName}. Proceed with the task.`
+
+  toolPart.state = {
+    status: "completed",
+    input: { host: hostName },
+    output,
+    metadata: { truncated: false },
+    title: `Task handed off to ${hostName}`,
+    time: { start: now - 100, end: now },
+  }
+
+  last.parts.push({
+    reason: "tool-calls",
+    type: "step-finish",
+    tokens: { total: 0, input: 0, output: 0, reasoning: 0, cache: { write: 0, read: 0 } },
+    cost: 0,
+    id: `prt_${randomBytes(8).toString("hex")}`,
+    sessionID,
+    messageID: last.info.id,
+  })
+
+  last.info.time = { ...last.info.time, completed: now }
+  last.info.finish = "tool-calls"
+}