Dual-protocol client: OpenCode V1 and V2 wire APIs

.emmyrc.json

@@ -4,6 +4,9 @@
         "version": "LuaJIT"
     },
     "diagnostics": {
+        "globals": [
+            "vim"
+        ],
         "enables": [
             "missing-global-doc"
         ]
@@ -15,6 +18,11 @@
         ],
         "ignoreGlobs": [
             "**/*_spec.lua"
+        ],
+        "ignoreDir": [
+            "tests/manual/deps/",
+            "tests/data/deps/",
+            "deps"
         ]
     }
 }

.github/workflows/tests.yml

@@ -20,6 +20,31 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           args: --check . -g '*.lua' -g '!deps/'
 
+  typecheck:
+    runs-on: ubuntu-latest
+    name: typecheck
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: setup neovim
+        id: setup_nvim
+        uses: rhysd/action-setup-vim@v1
+        with:
+          neovim: true
+          version: v0.11.4
+
+      - name: Add nvim to PATH
+        run: echo "${{ steps.setup_nvim.outputs.executable }}" >> $GITHUB_PATH
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install emmylua_check
+        run: cargo install emmylua_check --version 0.25.1 --locked
+
+      - name: Run type checks
+        run: ./check_types.sh -f github
+
   test:
     timeout-minutes: 4
     strategy:

AGENTS.md

@@ -6,11 +6,22 @@
 - **Run a single test:** Replace the directory in the above command with the test file path, e.g.:
   - `./run_tests.sh -t tests/unit/test_example.lua`
 
-## Code Style Guidelines
+# Developer Environment: EmmyLua Analyzer Rust (emmylua_ls)
 
+- **Static Type Enforcement:** We use `emmylua-analyzer-rust` for strict type checking. Assume the LSP handles all type diagnostics.
+- **Zero Defensive Over-Engineering:** Do not write manual runtime code (`type()`, `if nil`, or fallback operators) to catch typing errors. The Rust-backed LSP will catch them at compile-time.
+- **Annotation-Only Contracts:** Document complex shapes using `---@class`, `---@alias`, and inline shapes. If a property or parameter is optional, strictly use the `?` marker (e.g., `---@param options? Table`).
+- **Idiomatic Lua Flow:** Write clean, raw, performant Lua code. Let the application "fail fast" if code contract invariants are broken at runtime.
 - **Comments:** Avoid obvious comments that merely restate what the code does. Only add comments when necessary to explain _why_ something is done, not _what_ is being done. Prefer self-explanatory code.
-- **Config:** Centralize in `config.lua`. Use deep merge for user overrides.
-- **Types:** Use Lua annotations (`---@class`, `---@field`, etc.) for public APIs/config.
+
+# Code Validation Step (Mandatory)
+
+Before you mark a Lua code generation task as complete, you must validate your types against the project's static analysis rules:
+
+1. Run the `./check_types.sh` CLI tool over the generated workspace to execute `emmylua_check`.
+2. Review the output for any static analysis diagnostics (e.g., syntax errors, type mismatches, missing fields).
+3. If `emmylua_check` flags any type mismatches, you must fix the code's annotations or types—**do not write manual runtime boilerplate checking (`type()`) to quiet the linter**.
+4. Iterate until `emmylua_check` passes with zero errors.
 
 ## Dependency Topology Tool
 

README.md

@@ -134,6 +134,7 @@ require('opencode').setup({
     path_map = nil,        -- Map host paths to server paths: string ('/app') or function(path) -> string
     username = nil,        -- Username for Basic auth. Falls back to OPENCODE_SERVER_USERNAME env var, then "opencode"
     password = nil,        -- Password for Basic auth. Falls back to OPENCODE_SERVER_PASSWORD env var
+    password_file = nil,   -- Shared V1 password file; fixed ports default to an owner-only per-port state file
   },
 
   keymap = {
@@ -319,7 +320,7 @@ require('opencode').setup({
       info = false, -- Include diagnostics info in the context (default to false
       warning = true, -- Include diagnostics warnings in the context
       error = true, -- Include diagnostics errors in the context
-      only_closest = false, -- If true, only diagnostics for cursor/selection
+      only_closest = true, -- Only diagnostics for cursor/selection; disable to include the whole buffer
     },
     current_file = {
       enabled = true, -- Include current file path and content in the context
@@ -532,15 +533,15 @@ Available icon keys (see implementation at lua/opencode/ui/icons.lua lines 7-29)
 
 ### Window Persistence Behavior
 
-`ui.persist_state` controls how `toggle` behaves:
+`ui.persist_state` controls how `toggle` and `close` behave:
 
 - `persist_state = true` (default): `toggle()` hides/restores the UI and keeps buffers/session view in memory for fast restore.
 - `persist_state = false`: `toggle()` fully tears down UI buffers and recreates them on next open.
 
 Related APIs:
 
 - `require('opencode.api').toggle()` follows the `persist_state` behavior above.
-- `require('opencode.api').close()` always fully closes and clears hidden snapshot state.
+- `require('opencode.api').close()` preserves buffers when `persist_state = true`; otherwise it fully closes.
 - `require('opencode.api').hide()` preserves buffers only when `persist_state = true`; otherwise it behaves like close.
 
 ### Picker Layout
@@ -798,6 +799,10 @@ Opencode can issue permission requests for potentially destructive operations (f
 
 The following editor context is automatically captured and included in your conversations.
 
+Unchanged automatic payloads (diagnostics, buffer, cursor data, and staged diff) are sent once per session, then sent again only after their content changes. Explicit file mentions and selections are always sent.
+
+When a selection targets the current file, the automatic current-file attachment is skipped. The selected lines provide focused context; the agent can read more of the file when needed. An explicit file mention is still honored.
+
 | Context Type    | Description                                          |
 | --------------- | ---------------------------------------------------- |
 | Current file    | Path to the focused file before entering opencode    |

check_types.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+if ! command -v nvim >/dev/null 2>&1; then
+  echo 'error: nvim is required to resolve VIMRUNTIME' >&2
+  exit 127
+fi
+
+if ! command -v emmylua_check >/dev/null 2>&1; then
+  echo 'error: emmylua_check is required' >&2
+  exit 127
+fi
+
+if [[ ! -d "${VIMRUNTIME:-}" ]]; then
+  VIMRUNTIME="$(nvim --headless -u NONE -i NONE --noplugin \
+    --cmd 'lua io.write(vim.env.VIMRUNTIME or "")' \
+    --cmd 'qa!' 2>/dev/null)"
+fi
+
+if [[ ! -d "${VIMRUNTIME:-}" ]]; then
+  echo 'error: unable to resolve a valid VIMRUNTIME' >&2
+  exit 1
+fi
+
+export VIMRUNTIME
+exec emmylua_check . "$@"

docs/recipes/bidirectional-sync/README.md

@@ -26,7 +26,7 @@ Use a single shared HTTP server that both TUI and nvim connect to:
 
 ```mermaid
 flowchart LR
-    A[Terminal: oc-sync.sh] -->|starts| B[Shared Server :4096]
+    A[Terminal: native opencode --server] -->|connects| B[Shared Server]
     C[nvim] -->|connects| B
     D[TUI] -->|connects| B
     B -->|shares session| C
@@ -35,53 +35,40 @@ flowchart LR
 
 ## Quick Start
 
-### 1. Install Wrapper
+### V2 native service
+
+V2 2.0.x 的 TUI 默认连接 OpenCode 自己管理的后台 service。Neovim 默认也使用这个 service，无需 wrapper、固定端口、额外 password_file 或用户填写 ownership。下面的 V2 路径已在 2.0.3 实测。
+
+```lua
+require("opencode").setup({
+    server = { timeout = 30 },
+})
+```
 
 ```bash
-chmod +x oc-sync.sh
-cp oc-sync.sh ~/.local/bin/
+# 普通 TUI 使用原生后台 service
+opencode /path/to/project
+# 继续 Neovim 正在显示的同一 session
+opencode --session ses_... /path/to/project
 ```
 
-### 2. Configure Nvim
+插件用 CLI 的 `service status` 获取地址、`service get password` 获取凭据；仅当状态明确为 `stopped` 时调用 `service start`。HTTP health 决定 V1/V2 协议。Neovim 退出不关闭原生 service。CLI 能力检查只选择启动入口，不代替 server health 的协议判定。
 
-Add to your opencode.nvim setup:
+同一目录不代表两端自动选中同一 session；在另一端显式 resume 同一 session。两端共享消息、工具、question 与 permission 状态，各自保留窗口、光标和未提交输入。
 
-```lua
-server = {
-    url = "localhost",
-    port = 4096,
-    timeout = 30,  -- First boot can be slow (MCP initialization)
-    auto_kill = false,  -- Keep server alive when TUI is active
-    spawn_command = function(port, url)
-        local script = vim.fn.expand("~/.local/bin/oc-sync.sh")
-        vim.fn.system(script .. " --sync-ensure")
-        return nil  -- Server lifecycle managed externally
-    end,
-}
-```
+### V1 and explicit servers
 
-### 3. Use It
+旧 V1 CLI 没有 service 命令，插件保留原有本地 `serve` 路径。已有 `server.url`、`port`、`spawn_command` 的配置继续按显式连接处理。
 
-Terminal 1 - Start TUI:
-```bash
-oc-sync.sh /path/to/project
-```
+V1 的共享服务需要两端使用同一 endpoint 和凭据，TUI 原生命令是：
 
-Terminal 2 - Open nvim in same directory:
 ```bash
-cd /path/to/project && nvim
+opencode attach http://127.0.0.1:4096 --dir /path/to/project --session ses_...
 ```
 
-Both will share the same session state.
+V2 的显式远端连接可使用 `opencode --server <endpoint> --session ses_... <directory>`，并按服务要求提供 `OPENCODE_PASSWORD`。只有该显式场景需要双方约定地址。以下 legacy helper 配置仅适用于 V1；V2 无需安装或调用 `oc-sync.sh`。
 
-## Implementation Notes
-
-- `oc-sync.sh --sync-ensure` starts shared HTTP server (port 4096)
-- TUI runs `opencode attach <endpoint>` to connect
-- Nvim plugin connects to same endpoint
-- Server stays alive until manually killed
-
-## Customization
+## V1 legacy helper configuration
 
 Environment variables:
 
@@ -90,29 +77,47 @@ Environment variables:
 | `OPENCODE_SYNC_PORT` | 4096 | HTTP server port |
 | `OPENCODE_SYNC_HOST` | 127.0.0.1 | Server bind address |
 | `OPENCODE_SYNC_WAIT_TIMEOUT_SEC` | 20 | Startup timeout |
+| `OPENCODE_SYNC_PASSWORD_FILE` | `$XDG_STATE_HOME/nvim/opencode/server-password` or `~/.local/state/nvim/opencode/server-password` | Shared credential file |
 
 ## Troubleshooting
 
-**Port already in use?**
-```bash
-# Check what's using it
-lsof -i :4096
+V2 先用原生命令检查服务状态和真实 health：
 
-# Kill the process
-kill $(lsof -t -i :4096)
-```
-
-**MCP plugins taking too long?**
 ```bash
-# Increase timeout
-export OPENCODE_SYNC_WAIT_TIMEOUT_SEC=60
+opencode service status
+opencode api GET /api/health
 ```
 
-**Server not responding?**
-```bash
-# Check health
-curl http://localhost:4096/global/health
-```
+插件错误与 CLI 错误应分别检查。401/403 不会触发私有 server 启动或 V1 回退。无需查找并杀掉某个约定端口的进程。
+
+The nvim client and TUI share the HTTP server and session data. Selecting a
+session in one frontend does not select it in the other frontend. Pass
+`--session ses_...` when both clients must display the same conversation. Each
+frontend still owns its windows, cursor, input draft, and current selection.
+Native V2 service lifecycle belongs to OpenCode. For an explicitly managed shared server, do not use
+`--shutdown-after-last-client` when starting it.
+
+Server ownership controls shutdown and port cleanup only. Prompt completion uses
+the admission ID returned to nvim and the matching inbox events from the shared
+server. The server runs one serial execution horizon per session, so messages
+delivered by another client during that horizon are included in the same next
+terminal event. The plugin keeps one local prompt in flight per session. A lost
+event stream, or evidence that the server started overlapping execution horizons,
+resolves that local completion as `unknown`; messages already stored by the server
+remain visible to both frontends after a snapshot refresh.
+
+For a V1 explicit launcher shared with the TUI, set `server.password_file` to a state-directory path. Fixed-port
+V1 servers otherwise use an owner-only per-port file under Neovim's state directory so later nvim clients reuse
+the same credential. On a launcher path, the plugin persists the selected password before
+starting its local server, so a later nvim process and, when explicitly configured, the TUI read the same value.
+Plugin credential selection is deterministic: `server.password`, then the
+configured password file, then `OPENCODE_PASSWORD`, then
+`OPENCODE_SERVER_PASSWORD`. This recipe leaves `server.password` unset and uses
+the password file as the shared source. When the file is absent, the V1 helper
+persists the environment password or generates one; an existing invalid file
+fails immediately instead of being replaced.
+
+The legacy helper rejects a CLI with the native service command before creating credentials or starting a process. Its health endpoint is `/global/health`, where a healthy V1 JSON response is required; the liveness check does not depend on the server version. HTML 200 and authentication errors are failures. V2 never enters this script's launcher path.
 
 ## Integration Ideas