agentp 0.10.0 → 0.11.1

package/docs/specification.md

@@ -0,0 +1,391 @@
+# agentp — Specification
+
+## Overview
+
+Three zero-dependency Node.js CLI tools that augment OpenCode with project-level server management (tmux) and a Telegram bridge.
+
+- **`agentp`** — pipe stdin → OpenCode session → stdout answer
+- **`ocmux`** — manage per-project OpenCode servers in tmux
+- **`tgagentp`** — Telegram bot bridge with multi-chat, multi-server support
+
+All tools share `lib/opencode.js` (HTTP session API client) and `lib/ocmux.js` (tmux management). Zero npm dependencies — only Node.js 18+ stdlib.
+
+---
+
+## File Reference
+
+### `package.json`
+
+**Version:** 0.13.0
+
+Fields:
+- `"bin"` — registers `agentp`, `ocmux`, `tgagentp`
+- `"files"` — whitelist for npm publish: `bin/`, `lib/`, `README.md`
+- `"type": "commonjs"`
+- `"engines": { "node": ">=18" }`
+
+### `bin/agentp` — Stdin-to-OpenCode pipe
+
+Reads stdin, sends to the most recent or named OpenCode session, streams answer to stdout.
+
+**Options:**
+
+| Flag | Effect |
+|---|---|
+| `--qa` | Print prompt/answer with rulers; auto-detect tgagentp |
+| `--tg` | Forward answer via tgagentp gateway (error if unavailable) |
+| `--no-tg` | Explicitly disable Telegram forwarding |
+| `--flush` | Flush recorded buffer without prepending |
+| `--getLast N` | Retrieve last N assistant answers from session history |
+
+**Protocol:**
+
+1. Reads all stdin → string
+2. Calls `listSessions(server)` → finds most recently updated session (or creates one named `agentp`)
+3. Calls `sendToSession(server, sessionId, text, agent?, cancelRef?)` → returns concatenated text parts
+4. Prints answer to stdout
+5. If `--tg` or `--qa` (auto-detect):
+   - POSTs `{ text, server }` to tgagentp gateway at `http://localhost:<port>/send`
+   - Gateway response includes `{ buffered }` — recorded conversation messages
+   - `--qa` prepends buffered context to stdout; `--flush` skips prepending
+
+**HTTP timeout:** 5 seconds. Pre-send gate check + post-send warning for `--tg`.
+
+### `bin/ocmux` — Tmux server manager
+
+Manages per-project OpenCode servers in a persistent `Opencode` tmux session.
+
+**Subcommands:**
+
+| Command | Description |
+|---|---|
+| `serve [dir]` | Create server + TUI pane in a new tmux window |
+| `new [dir]` | Alias for `serve` (deprecated) |
+| `kill [dir]` | Kill server, remove tmux window + `.ocmux.json` |
+| `resurrect [dir]` | Recover dead server: kill old window, remove state file, create fresh server + TUI |
+| `list [-l]` | List all running servers |
+| _(no arg)_ | Switch to existing server (searches upward for `.ocmux.json`) |
+
+**Flags:** `--git`, `--GIT`, `--print-logs`, `-l`, `--version`
+
+**Window layout:**
+
+- Pane 0: server (`opencode serve --port 0 2>&1 | tee <logfile>`)
+- Pane 1+: TUI (`opencode attach --continue '<url>'`)
+- Log: `/tmp/opencode-serve-<hashDir(dir)>.log`
+- State: `<dir>/.ocmux.json` (contains `url`, `logfile`, `window_index`)
+
+**State file discovery:** Upward from target directory, git-like.
+
+### `bin/tgagentp` — Telegram bridge
+
+Long-polling Telegram bot that routes messages to OpenCode servers.
+
+**Options:**
+
+| Flag | Effect |
+|---|---|
+| `--dev` | Enable `/shutdown` for remote restart, verbose logging, and structured message traffic log to `/tmp/tgagentp-msg.log` |
+| `--think` | Start with thinking forwarding enabled |
+| `--verbose` | Detailed logs on stderr |
+
+**Environment variables:**
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | Yes | — | Bot token from @BotFather |
+| `TGAGENTP_ALLOWED_CHAT_IDS` | No | all | Comma-separated allowed chat IDs |
+| `TGAGENTP_PORT` | No | random | Agentp gateway HTTP port |
+| `TGAGENTP_DEBOUNCE_MS` | No | 5000 | Debounce for queued-agentp Telegram notifications |
+| `OPENCODE_SERVER_PASSWORD` | No | — | HTTP Basic Auth for OpenCode + gateway |
+| `OPENCODE_SERVER_USERNAME` | No | opencode | HTTP Basic Auth username |
+
+### `lib/opencode.js` — HTTP session API client
+
+Shared by `bin/agentp` and `bin/tgagentp`. Functions:
+
+| Function | HTTP | Description |
+|---|---|---|
+| `getAuthHeaders()` | — | Reads `OPENCODE_SERVER_PASSWORD/USERNAME` |
+| `makeRequest(options, data)` | — | Thin `http.request` wrapper |
+| `buildJsonRequest(url, method, body)` | — | Builds request options |
+| `sendText(server, text)` | POST /tui/* | Convenience: clear + append + submit prompt |
+| `listenForFinalAnswer(server, onText?, cancelRef?)` | GET /event | SSE listener; `cancelRef` enables abort |
+| `listSessions(server, directory?)` | GET /session | Returns parsed JSON array |
+| `createSession(server, title?)` | POST /session | Creates a session |
+| `updateSession(server, id, title, agent?)` | PATCH /session/:id | Updates session properties |
+| `sendToSession(server, id, text, agent?, cancelRef?)` | POST /session/:id/message | Synchronous message; optional abort |
+| `sendToSessionAsync(server, id, text, agent?)` | POST /session/:id/prompt_async | Non-blocking (204); answer via SSE |
+| `respondToPermission(server, id, permissionId, response)` | POST /session/:id/permissions/:id | Permission response |
+| `selectSession(server, id)` | POST /session/:id/select | TUI navigation |
+| `listAgents(server)` | GET /agent | Returns parsed array |
+| `listProviders(server)` | GET /provider | Returns parsed array |
+| `isServerAlive(url)` | GET /session (5s timeout) | Health check, resolves true/false |
+| `listenForSessionEvents(server, id, callbacks, cancelRef?)` | GET /event | SSE with structured events |
+
+### `lib/ocmux.js` — Tmux management library
+
+Shared by `bin/ocmux` and `bin/tgagentp`. Functions:
+
+| Function | Description |
+|---|---|
+| `readState(file)` | Parses `.ocmux.json`; returns `null` on error |
+| `statefileFor(dir)` | `path.join(dir, '.ocmux.json')` |
+| `tuiPaneId(windowIndex)` | Returns pane ID of TUI pane (pane index != 0); `null` if dead |
+| `windowByDir(dir)` | Returns tmux window index matching directory name |
+| `windowNameByIndex(idx)` | Returns window name at given index |
+| `activeWindowIndex()` | Returns index of currently selected tmux window |
+| `paneCount(windowIndex)` | Number of panes in a window |
+| `listServers()` | Scans all tmux windows for `.ocmux.json`; returns `{ url, dir, index, status }` |
+| `activateServer(dir, index, url)` | Pin window name, restart dead TUI pane, select window, zoom |
+| `hashDir(dir)` | MD5 hash (first 12 chars) |
+| `logfileFor(dir)` | `/tmp/opencode-serve-<hash>.log` |
+| `sleep(seconds)` | `execSync sleep` |
+| `ensureSession()` | Create `Opencode` tmux session if missing |
+| `pinWindowName(windowIndex)` | Disable tmux auto-rename for the window |
+| `resurrectServer(dir, printLogs)` | Kill old window, remove state file, create fresh server + TUI; returns `{ url, dir }` |
+
+---
+
+## Persistence / State Files
+
+### `{project_dir}/.ocmux.json`
+
+Per-project state file created by `ocmux serve`:
+
+```json
+{
+  "url": "http://localhost:40999",
+  "logfile": "/tmp/opencode-serve-abc123.log",
+  "window_index": 5
+}
+```
+
+- **url:** The server's listen URL (assigned by `--port 0` — changes on every restart)
+- **logfile:** Path to the server's tee'd log output (used for URL polling during startup)
+- **window_index:** The tmux window index within the `Opencode` session
+
+Discovered by upward directory search from the current/target directory (git-like). Used by `ocmux`, `tgagentp`, and `agentp` for server discovery.
+
+### `/tmp/tgagentp-port`
+
+Created by tgagentp on startup. Contains the HTTP port number of the agentp gateway. Read by `agentp --tg` to discover the gateway.
+
+```
+49152
+```
+
+### `/tmp/tgagentp-connections.json`
+
+Created and maintained by tgagentp. Persists chat↔server directory mappings across restarts.
+
+```json
+{
+  "connections": [
+    {
+      "chatId": "123456789",
+      "threadId": null,
+      "dir": "/home/user/projects/myapp"
+    },
+    {
+      "chatId": "987654321",
+      "threadId": "42",
+      "dir": "/home/user/projects/other"
+    }
+  ]
+}
+```
+
+- **chatId:** Telegram chat ID (string)
+- **threadId:** Telegram forum topic ID or `null`
+- **dir:** Project directory (where `.ocmux.json` lives)
+
+On restart, tgagentp reads this file, reads `.ocmux.json` from each `dir` to discover the fresh URL, and reconnects. If `.ocmux.json` is missing, the chat starts disconnected.
+
+**Lifecycle:**
+- Written on every `/servers switch` (via `setServerForChat`)
+- Removed for displaced chats on force-takeover (via `removeConnection`)
+- Removed for pruned chats on restart (secondary per URL)
+- Cleared on `/shutdown clear` (via `clearConnections`)
+- Updated on group migration (regular group → supergroup, e.g. enabling topics): all `chatId` references in the file are replaced with the new ID
+
+### `/tmp/opencode-serve-<hashDir(dir)>.log`
+
+Server log file. Continuously written by `tee` in the server pane. Polled by `doNew`/`resurrectServer` for URL extraction during startup:
+
+```
+opencode server listening on http://localhost:40999
+```
+
+---
+
+## Inter-Process Communication
+
+### Agentp Gateway (tgagentp ↔ agentp)
+
+tgagentp starts an HTTP server on `127.0.0.1:<port>` (random by default, configurable via `TGAGENTP_PORT`). `agentp --tg` POSTs answers to this gateway.
+
+**Endpoint:** `POST /send`
+
+**Request:**
+```json
+{
+  "text": "Answer from OpenCode",
+  "server": "http://localhost:40999"
+}
+```
+
+**Headers:**
+- `Authorization: Basic <base64>` — verified against `OPENCODE_SERVER_PASSWORD`
+
+**Response:**
+```json
+{
+  "buffered": [
+    {"role": "user", "text": "What is X?"},
+    {"role": "assistant", "text": "X is..."}
+  ]
+}
+```
+
+**Flow:**
+1. Gateway looks up `serverOwners` map to find which chat owns the target server
+2. If found and it's the active server for that chat → forwards immediately via `sendLongMessage`
+3. If not the active server → debounce-queues with notification after `TGAGENTP_DEBOUNCE_MS`
+4. Returns recorded conversation buffer (if any) — `agentp --qa` prepends this to stdout
+5. If no owner found (no chat connected to that server) → returns buffered data, drops the message
+
+### Tmux Session Model (ocmux)
+
+All servers live in a single tmux session named `Opencode`. Each project gets one window:
+
+```
+Session: Opencode
+├── Window 3: /home/user/project-a
+│   ├── Pane 0: opencode serve --port 0 ...   (server)
+│   └── Pane 1: opencode attach --continue ...  (TUI, zoomed)
+├── Window 4: /home/user/project-b
+│   ├── Pane 0: opencode serve --port 0 ...
+│   └── Pane 1: opencode attach --continue ...
+```
+
+Window names are the full project directory path. Pane 0 is always the server; pane 1+ is the TUI. The TUI pane is zoomed on switch/create. Dead TUI panes are auto-restarted on switch.
+
+---
+
+## Chat-Server Ownership Model (tgagentp)
+
+### States
+
+- **Disconnected:** `chatState.serverBase === null`. Only `/help`, `/servers`, `/start` work.
+- **Connected:** `chatState.serverBase === <url>`. Server is owned by this chat.
+- **Force-taken:** Previous owner gets `serverBase = null` and a Telegram notification.
+
+### Data Structures
+
+```javascript
+serverOwners = {
+  "http://localhost:40999": { chatId: "123", threadId: null },
+  "http://localhost:41000": { chatId: "456", threadId: "42" },
+}
+```
+
+Maps server URL → owning chat. Used by the agentp gateway to route forwarded messages. Updated on every `/servers switch` and on startup restoration.
+
+```javascript
+chatStates = {
+  "123": {
+    chatId: "123",
+    threadId: null,
+    serverBase: "http://localhost:40999",
+    recording: { active: false, paused: false, messages: [], bytes: 0 },
+    ring: { messages: [], bytes: 0 },
+  },
+  "456:42": {
+    chatId: "456",
+    threadId: 42,
+    serverBase: null,
+    ...
+  },
+}
+```
+
+Keyed by `convKey(chatId, threadId)` → `${chatId}:t${threadId}` (or just `chatId` for non-thread chats). Created on first message from each chat.
+
+### Connection Flow
+
+1. **First message** → `getChatState` creates state with `serverBase: null`
+2. **`/servers switch <name>`** → `cmdServers`:
+   - Finds server directory by name match
+   - Checks `serverOwners` — warns if owned by different chat (unless `--force`)
+   - Calls `setServerForChat(chatState, url)`:
+     - Iterates all `chatStates`, sets `serverBase = null` for any other chat on same URL
+     - Sets `chatState.serverBase = url`
+     - Sets `serverOwners[url] = { chatId, threadId }`
+     - Saves connection to `/tmp/tgagentp-connections.json`
+     - Activates tmux window
+     - Flushes agentp queue for this server
+3. **Restart** → reads `/tmp/tgagentp-connections.json`, restores each connection:
+   - Phase 1: restores all chat states (`cs.serverBase`) and populates `serverOwners`
+   - `serverOwners` picks non-thread (private chat) over topic threads as owner per URL
+   - Phase 2: prunes secondary connections — only the owner per URL survives, others have `serverBase` cleared and connection removed from file
+   - Phase 3: "Bot started" notification sent only to owner per URL (first-to-notify wins)
+4. **`/force-switch <name>`** → same as `/servers switch --force <name>`: bypasses ownership check, takes over server, notifies previous owner
+5. **`/disconnect`** → clears `serverBase`, removes ownership, deletes connection from file
+
+### Disconnected Guard
+
+Both command and non-command paths in the message loop check `cs.serverBase`:
+
+- Commands: only `/help`, `/servers`, `/force-switch`, `/start`, `/comment`, `/shutdown` pass through without a server
+- Non-commands: `🔌 Not connected. Use /servers to see available servers.`
+
+---
+
+## Logging Conventions (tgagentp)
+
+- **stdout** — informational messages (startup, discovery, session switches)
+- **stderr** — errors (always shown) + trace/debug (only `--verbose` flag)
+- Default usage: `tgagentp 2>/dev/null`
+
+### Dev Mode Message Log
+
+When `--dev` is active, tgagentp writes a structured JSON-lines message traffic log to `/tmp/tgagentp-msg.log`:
+
+```
+{"ts":"2026-06-09 06:25:01","type":"in","chatId":-1004291964025,"from":"user","text":"/status"}
+{"ts":"2026-06-09 06:25:01","type":"out","chatId":-1004291964025,"from":"assistant","text":"**Server:** ..."}
+```
+
+Each line contains a timestamp, direction (`in`/`out`), chat ID, sender, and text content.
+
+---
+
+## Error Handling
+
+### Server Health (tgagentp)
+
+```javascript
+// Pre-send check
+if (st.serverDead) {
+  const alive = await isServerAlive(url);  // GET /session, 5s timeout
+  if (alive) { st.serverDead = false; }
+}
+if (st.serverDead) {
+  // Auto-queue the message
+  st.messageQueue.push({ text, replyTo });
+  // Notify user with options (ocmux serve, /servers switch, /flush)
+}
+```
+
+Health check runs before every non-command message. Dead servers cause auto-queue with user notification. Connection errors in `processMessageAsync` mark `serverDead = true` and requeue.
+
+### Busy Server
+
+When `st.busy` is true, non-command messages are dropped with a "⏳ Busy" notice. Use `/queue <message>` to explicitly queue.
+
+### Gateway Errors
+
+- Missing owning chat → return buffered data, drop message
+- Socket errors → caught by try-catch in gateway handler (no crash)
+- HTTP timeout (5s) in agentp → post-send warning (not hard error)

package/lib/ocmux.js

@@ -2,18 +2,43 @@
 
 const fs = require('fs');
 const path = require('path');
-const { spawnSync } = require('child_process');
+const crypto = require('crypto');
+const child_process = require('child_process');
 
 const SESSION = 'Opencode';
+const URL_RE = /opencode server listening on (http:\/\/[^\s]*)/;
 
 function _tmux(args) {
-  const result = spawnSync('tmux', args, { encoding: 'utf8', maxBuffer: 1024 * 1024 });
+  const result = child_process.spawnSync('tmux', args, { encoding: 'utf8', maxBuffer: 1024 * 1024 });
   if (result.error && result.error.code === 'ENOENT') {
     return { status: -1, stdout: '', stderr: 'tmux not found' };
   }
   return result;
 }
 
+function hashDir(dir) {
+  return crypto.createHash('md5').update(dir).digest('hex').slice(0, 12);
+}
+
+function logfileFor(dir) {
+  return `/tmp/opencode-serve-${hashDir(dir)}.log`;
+}
+
+function sleep(seconds) {
+  child_process.execSync(`sleep ${seconds}`, { stdio: 'ignore' });
+}
+
+function ensureSession() {
+  const r = _tmux(['has-session', '-t', SESSION]);
+  if (r.status !== 0) {
+    _tmux(['new-session', '-d', '-s', SESSION]);
+  }
+}
+
+function pinWindowName(windowIndex) {
+  _tmux(['set-window-option', '-t', `${SESSION}:${windowIndex}`, 'automatic-rename', 'off']);
+}
+
 function readState(file) {
   try {
     return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -143,8 +168,88 @@ function activateServer(dir, index, url) {
   return true;
 }
 
+// Recover a dead/crashed server: kill old window, remove state file,
+// create fresh server + TUI in the same directory.
+// Returns { url, dir } on success, throws on error.
+function resurrectServer(dir, printLogs) {
+  const sf = path.join(dir, '.ocmux.json');
+  const state = readState(sf);
+
+  // Kill old tmux window if it exists
+  if (state && state.window_index != null) {
+    let winIdx = state.window_index;
+    const sessionR = _tmux(['has-session', '-t', SESSION]);
+    if (sessionR.status === 0) {
+      const actualName = windowNameByIndex(winIdx);
+      if (actualName !== dir) {
+        const found = windowByDir(dir);
+        if (found != null) winIdx = found;
+      }
+      if (winIdx != null) {
+        _tmux(['select-window', '-t', `${SESSION}:${winIdx}`]);
+        _tmux(['send-keys', '-t', `${SESSION}:${winIdx}.0`, 'C-c']);
+        sleep(0.3);
+        _tmux(['kill-window', '-t', `${SESSION}:${winIdx}`]);
+      }
+    }
+  }
+
+  // Remove old state file so we can create a fresh one
+  try { fs.unlinkSync(sf); } catch {}
+
+  // Create fresh server + TUI
+  ensureSession();
+  const lf = logfileFor(dir);
+
+  const rc = _tmux(['new-window', '-d', '-t', SESSION, '-n', dir, '-c', dir]);
+  if (rc.status !== 0) throw new Error(`failed to create tmux window for ${dir}`);
+
+  const winIdx = windowByDir(dir);
+  if (winIdx == null) throw new Error('window was not created properly');
+
+  pinWindowName(winIdx);
+
+  try { fs.truncateSync(lf); } catch {}
+
+  const serveFlags = printLogs ? '--port 0 --print-logs' : '--port 0';
+  _tmux(['send-keys', '-t', `${SESSION}:${winIdx}.0`,
+    `opencode serve ${serveFlags} 2>&1 | tee '${lf}'`, 'Enter']);
+
+  let url = null;
+  for (let i = 0; i < 50; i++) {
+    sleep(0.2);
+    const log = (() => { try { return fs.readFileSync(lf, 'utf8'); } catch { return ''; } })();
+    const m = log.match(URL_RE);
+    if (m) url = m[1];
+  }
+
+  if (!url) {
+    const wi = windowByDir(dir);
+    if (wi != null) _tmux(['kill-window', '-t', `${SESSION}:${wi}`]);
+    throw new Error('opencode server did not start within 10 seconds');
+  }
+
+  const newState = { url, logfile: lf, window_index: winIdx };
+  fs.writeFileSync(sf, JSON.stringify(newState) + '\n');
+
+  const splitResult = _tmux(['split-window', '-v', '-P', '-F', '#{pane_id}', '-t', `${SESSION}:${winIdx}`, '-c', dir]);
+  const tuiPane = splitResult.stdout.trim();
+  sleep(0.2);
+  _tmux(['send-keys', '-t', tuiPane, `opencode attach --continue '${url}'`, 'Enter']);
+  sleep(0.5);
+  if (tuiPane) _tmux(['resize-pane', '-Z', '-t', tuiPane]);
+
+  const activeWin = activeWindowIndex();
+  if (activeWin !== null && activeWin !== winIdx) {
+    _tmux(['select-window', '-t', `${SESSION}:${winIdx}`]);
+  }
+
+  return { url, dir };
+}
+
 module.exports = {
   SESSION,
+  URL_RE,
   readState,
   statefileFor,
   tuiPaneId,
@@ -154,4 +259,10 @@ module.exports = {
   paneCount,
   listServers,
   activateServer,
+  hashDir,
+  logfileFor,
+  sleep,
+  ensureSession,
+  pinWindowName,
+  resurrectServer,
 };

package/lib/opencode.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const http = require('http');
+const https = require('https');
 const { URL } = require('url');
 
 function getAuthHeaders() {
@@ -252,16 +253,25 @@ async function selectSession(server, sessionId) {
 // Get a single session by ID, including its message history.
 // Tries GET /session/:id first; falls back to filtering the sessions list.
 async function getSession(server, sessionId) {
-  // Try dedicated endpoint first (newer opencode versions)
-  try {
-    const url = `${server}/session/${encodeURIComponent(sessionId)}`;
-    const { status, body } = await makeRequest(buildJsonRequest(url, 'GET'), null, null, 10000);
-    if (status === 200) {
-      const parsed = JSON.parse(body);
-      if (parsed) return parsed;
-    }
-  } catch {
-    // Fall through
+  const encoded = encodeURIComponent(sessionId);
+  // Try several endpoint patterns that different opencode versions may expose
+  const urls = [
+    `${server}/session/${encoded}`,
+    `${server}/session/${encoded}/messages`,
+    `${server}/session/${encoded}/history`,
+    `${server}/session/${encoded}/conversation`,
+    `${server}/conversation/${encoded}`,
+  ];
+  for (const url of urls) {
+    try {
+      const { status, body } = await makeRequest(buildJsonRequest(url, 'GET'), null, null, 10000);
+      if (status === 200) {
+        try {
+          const parsed = JSON.parse(body);
+          if (parsed != null) return parsed;
+        } catch {}
+      }
+    } catch {}
   }
   // Fallback: get all sessions and find the one we need
   const sessions = await listSessions(server);
@@ -310,8 +320,13 @@ async function respondToPermission(server, sessionId, permissionId, response, re
 // permission requests. Resolves with the full collected text when the session goes idle.
 // callbacks: { onText(chunk), onPermission(permission), onThinking(chunk), onConnected() }
 // cancelRef — allows aborting the SSE stream via req.destroy()
-function listenForSessionEvents(server, sessionId, callbacks, cancelRef) {
-  process.stderr.write(`  [SSE] connecting to ${server}/event for session ${sessionId}\n`);
+// logFn — optional logger; if provided, used instead of process.stderr.write
+function listenForSessionEvents(server, sessionId, callbacks, cancelRef, logFn) {
+  const sseLog = logFn || ((msg) => {
+    const ts = new Date().toISOString().replace('T', ' ').replace(/\.\d{3}Z$/, '');
+    process.stderr.write(`${ts} ${msg}`);
+  });
+  sseLog(`  [SSE] connecting to ${server}/event for session ${sessionId}\n`);
   return new Promise((resolve, reject) => {
     const url = `${server}/event`;
     const parsed = new URL(url);
@@ -328,7 +343,7 @@ function listenForSessionEvents(server, sessionId, callbacks, cancelRef) {
         reject(new Error('OpenCode server authentication failed. Set OPENCODE_SERVER_PASSWORD to match the server password.'));
         return;
       }
-      process.stderr.write(`  [SSE] connected for session ${sessionId}\n`);
+      sseLog(`  [SSE] connected for session ${sessionId}\n`);
       if (callbacks.onConnected) callbacks.onConnected();
       let buffer = '';
       const userMessageIDs = new Set();
@@ -339,7 +354,7 @@ function listenForSessionEvents(server, sessionId, callbacks, cancelRef) {
       const safetyTimer = setTimeout(() => {
         if (resolved) return;
         resolved = true;
-        process.stderr.write(`  [SSE] safety timeout (90s) for session ${sessionId}, collected ${collected.length} chars\n`);
+        sseLog(`  [SSE] safety timeout (90s) for session ${sessionId}, collected ${collected.length} chars\n`);
         cleanup();
         req.destroy();
         res.destroy();
@@ -365,9 +380,9 @@ function listenForSessionEvents(server, sessionId, callbacks, cancelRef) {
             const props = event.properties || {};
 
             if (event.type === 'session.status') {
-              process.stderr.write(`  [SSE] session.status: type=${props.status?.type} status=${JSON.stringify(props.status)}\n`);
+              sseLog(`  [SSE] session.status: type=${props.status?.type} status=${JSON.stringify(props.status)}\n`);
             } else {
-              process.stderr.write(`  [SSE] event type=${event.type} sessionID=${props.sessionID} waitSession=${sessionId}\n`);
+              sseLog(`  [SSE] event type=${event.type} sessionID=${props.sessionID} waitSession=${sessionId}\n`);
             }
 
             // Filter by sessionID when the event carries one (string-compare to handle type mismatches)
@@ -380,18 +395,18 @@ function listenForSessionEvents(server, sessionId, callbacks, cancelRef) {
 
             if (event.type === 'permission.asked') {
               const permStr = JSON.stringify(props);
-              process.stderr.write(`  [SSE] PERMISSION ASKED: ${permStr}\n`);
+              sseLog(`  [SSE] PERMISSION ASKED: ${permStr}\n`);
               if (callbacks.onPermission) {
-                process.stderr.write(`  [SSE] calling onPermission callback\n`);
+                sseLog(`  [SSE] calling onPermission callback\n`);
                 callbacks.onPermission(props);
               } else {
-                process.stderr.write(`  [SSE] WARNING: no onPermission callback registered\n`);
+                sseLog(`  [SSE] WARNING: no onPermission callback registered\n`);
               }
               continue;
             }
 
             if (event.type === 'permission.replied') {
-              process.stderr.write(`  [SSE] PERMISSION REPLIED: type=${props.type}\n`);
+              sseLog(`  [SSE] PERMISSION REPLIED: type=${props.type}\n`);
               if (callbacks.onPermissionReplied) {
                 callbacks.onPermissionReplied(props);
               }
@@ -453,7 +468,7 @@ function listenForSessionEvents(server, sessionId, callbacks, cancelRef) {
         if (resolved) return;
         resolved = true;
         cleanup();
-        process.stderr.write(`  [SSE] response stream error for session ${sessionId}: ${err.message}\n`);
+        sseLog(`  [SSE] response stream error for session ${sessionId}: ${err.message}\n`);
         resolve(collected);   // resolve with what we have
       });
     });
@@ -472,6 +487,29 @@ function listenForSessionEvents(server, sessionId, callbacks, cancelRef) {
   });
 }
 
+// Check if an OpenCode server is reachable by making a GET /session request.
+// Returns a Promise that resolves to `true` (any response) or `false` (connection error / timeout).
+function isServerAlive(url) {
+  return new Promise((resolve) => {
+    const mod = url.startsWith('https') ? https : http;
+    const parsed = new URL(url + '/session');
+    const opts = {
+      hostname: parsed.hostname,
+      port: parsed.port,
+      path: parsed.pathname,
+      method: 'GET',
+      headers: { ...getAuthHeaders() },
+    };
+    const req = mod.request(opts, (res) => {
+      res.resume();
+      resolve(true);
+    });
+    req.on('error', () => resolve(false));
+    req.setTimeout(5000, () => { req.destroy(); resolve(false); });
+    req.end();
+  });
+}
+
 module.exports = {
   getAuthHeaders,
   makeRequest,
@@ -492,4 +530,5 @@ module.exports = {
   listenForSessionEvents,
   listAgents,
   listProviders,
+  isServerAlive,
 };