@timlaing/opencode-tunnel-switch 0.0.0 → 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Laing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,102 @@
 # @timlaing/opencode-tunnel-switch
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+OpenCode v2 plugin that discovers the Python service's HTTP proxy, configures proxy environment variables for the OpenCode server process, and rotates an SSH SOCKS tunnel when a configured provider reports exhausted free usage. `/tunnel-status` displays the current connection ID and start time without a model request.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+The external [ssh-tunnel-switch](https://github.com/timlaing/ssh-tunnel-switch) server, available on [PyPI](https://pypi.org/project/ssh-tunnel-switch/), must be running before plugin startup. See the repository [setup guide](https://github.com/timlaing/opencode-tunnel-switch#readme).
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+After a successful tunnel switch, the plugin requests that OpenCode retry the current model request after one second, continuing the existing work automatically. Status display runs independently so a slow or failed notification cannot delay continuation. If a switch returns 429 (for example, another switch is already in progress), only the current work request is retried after `Retry-After`; the switch is not retried in that retry sequence. A local cooldown similarly delays the work request until it expires. Other switch failures stop the retry, and OpenCode's retry limit still applies.
 
-## Purpose
+The OpenCode session sidebar also includes a **Tunnel** section with connection
+state, server, start time, uptime, proxy address and API availability. While
+collapsed, the header still names the tunnel and its reachability, for example
+`▶ Tunnel (fra1 · reachable)`. It refreshes every five seconds;
+`/tunnel-refresh` refreshes immediately. Failed checks mark previous details
+stale. Reload OpenCode after updating the plugin.
+The TUI uses the same API options from the terminal machine, so remote-server
+setups need an API address reachable from that machine.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@timlaing/opencode-tunnel-switch`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+OpenCode's TUI runtime does not receive plugin options from `opencode.json(c)`;
+it only receives options declared in the terminal's `cli.json`
+(`~/.config/opencode/cli.json`). Declare the same options there to enable the
+sidebar; without that declaration the sidebar degrades to one error toast while
+rotation and `/tunnel-status` keep working through the server plugin:
 
-## What is OIDC Trusted Publishing?
+```json
+{
+  "plugins": [
+    {
+      "package": "@timlaing/opencode-tunnel-switch@latest",
+      "options": {
+        "apiIp": "127.0.0.1",
+        "apiPort": 8765,
+        "apiToken": "copy-the-token-displayed-by-the-python-service"
+      }
+    }
+  ]
+}
+```
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+## Install
 
-## Setup Instructions
+The same archive is published to the public npm registry and to GitHub Packages.
 
-To properly configure OIDC trusted publishing for this package:
+### npm
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+No authentication is required:
 
-## DO NOT USE THIS PACKAGE
+```sh
+npm install @timlaing/opencode-tunnel-switch
+```
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+### GitHub Packages
 
-## More Information
+Public npm packages on GitHub Packages still require authentication, as documented by [GitHub](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-to-github-packages). Use a GitHub personal access token (classic) with `read:packages`:
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```sh
+npm login --scope=@timlaing --auth-type=legacy --registry=https://npm.pkg.github.com
+```
 
----
+Add this scope mapping to your user `~/.npmrc` if it is not already present:
 
-**Maintained for OIDC setup purposes only**
+```ini
+@timlaing:registry=https://npm.pkg.github.com
+```
+
+Note that npm resolves a scope mapping ahead of a plain `--registry` flag, so an `@timlaing` mapping routes every `@timlaing/opencode-tunnel-switch` install to GitHub Packages.
+
+Keep registry credentials in your npm user configuration, not the repository. Configure OpenCode using the singular `plugin` key and the `[package, options]` tuple:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "@timlaing/opencode-tunnel-switch@1.5.0",
+      {
+        "apiIp": "127.0.0.1",
+        "apiPort": 8765,
+        "apiToken": "copy-the-token-displayed-by-the-python-service"
+      }
+    ]
+  ]
+}
+```
+
+The REST token is separate from GitHub registry credentials. Proxy IP/port are discovered automatically from `/status`. OpenCode's Bun runtime loads the shipped TypeScript root `index.ts`; no consumer build step is required. Local development can still configure the absolute `plugin` directory instead of the package name.
+
+## Serializer dependency
+
+OpenTUI currently requires a Solid version that constrains Seroval to a vulnerable
+release range. This checkout overrides Seroval to `~1.6.11` and audits that resolved
+tree. npm applies overrides only from the installing root project: applications
+installing this package must also enforce a patched Seroval version in their root
+dependency configuration. This package's override does not patch OpenCode's own
+bundled dependencies.
+
+## Publishing
+
+The repository's `Publish plugin` workflow runs plugin types and tests, checks the package allowlist, installs the packed tarball and verifies its OpenCode entrypoint in a job that holds no OIDC credentials, then hands that exact archive to a separate publishing job — the only one granted `id-token: write`, and the only one that runs no dependencies and no tests — which uploads it to `https://registry.npmjs.org` and `https://npm.pkg.github.com`.
+
+Publishing runs when a GitHub release is published, or manually on `main`. A release tag must be `v<package-version>`, matching `package.json`. Update the manifest and lockfile version before releasing a new version. Published versions cannot be overwritten; a version that already exists on a registry is skipped only when its archive integrity matches the tested tarball, and is rejected when it differs.
+
+The npm registry publish authenticates through [OIDC trusted publishing](https://docs.npmjs.com/trusted-publishers/): npmjs.com must list this repository and `publish-plugin.yml` as a trusted publisher for the package, and the workflow holds `id-token: write`. No npm token is stored in the repository. Signed provenance is enforced rather than assumed: npm releases publish with `--provenance`, and the readback requires a `dist.attestations` entry for every npm release, so an unattested npm version fails the workflow. Two things carry no attestation by design — the `0.0.0*` placeholder versions created by the one-time trusted-publishing bootstrap (they hold no code, and releases never route through them), and GitHub Packages, which does not support npm provenance attestations. GitHub Packages publishes with the workflow's `GITHUB_TOKEN` and `packages: write`; no publishing PAT is required. The package is linked to the public repository. The manifest requests public access; the workflow checks that both the repository and existing GitHub package are public before publishing. GitHub package visibility is a separate setting: maintainers manage it under [package settings](https://github.com/users/timlaing/packages/npm/opencode-tunnel-switch/settings), rather than relying on npm access flags. The workflow reads the published version back from both registries and verifies its archive integrity and repository link. Do not set the npm `private: true` flag, which prohibits publication.

package/index.ts

@@ -0,0 +1,2 @@
+// OpenCode's local-directory loader resolves a root index/server entrypoint.
+export { default } from "./src/index.js";

package/package.json

@@ -1,10 +1,54 @@
 {
   "name": "@timlaing/opencode-tunnel-switch",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for @timlaing/opencode-tunnel-switch",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "version": "1.5.0",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./tui": "./tui.ts"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --conditions=browser --import tsx --test test/*.test.ts",
+    "test:coverage": "mkdir -p coverage && node --conditions=browser --import tsx --experimental-test-coverage --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info test/*.test.ts",
+    "test:tui": "node --conditions=browser --import tsx test/verify-tui.ts",
+    "verify:package": "bun scripts/verify-package.ts",
+    "publish:package": "node scripts/publish-package.mjs",
+    "verify:published": "node scripts/verify-published-package.mjs"
+  },
+  "dependencies": {
+    "@opencode/plugin": "2.1.4",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "tsx": "^4.20.0",
+    "typescript": "^7.0.2"
+  },
+  "main": "./index.ts",
+  "description": "OpenCode v2 SSH tunnel rotation and proxy discovery plugin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/timlaing/opencode-tunnel-switch.git",
+    "directory": "plugin"
+  },
+  "homepage": "https://github.com/timlaing/opencode-tunnel-switch#readme",
+  "files": [
+    "index.ts",
+    "tui.ts",
+    "src/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com",
+    "access": "public"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@opentui/core": "^0.5.17",
+    "@opentui/solid": "^0.5.17",
+    "solid-js": "^1.9.12"
+  },
+  "overrides": {
+    "seroval": "~1.6.11"
+  }
 }

package/src/client.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+
+export const Options = z.object({
+  apiIp: z.union([z.ipv4(), z.ipv6()]).default("127.0.0.1"),
+  apiPort: z.number().int().min(1).max(65535).default(8765),
+  apiScheme: z.enum(["http", "https"]).default("http"),
+  apiToken: z.string().min(1).refine((token) => token.trim().length > 0, "apiToken must not be blank"),
+  configureProxy: z.boolean().default(true),
+  proxyIp: z.union([z.ipv4(), z.ipv6()]).optional(),
+  proxyPort: z.number().int().min(1).max(65535).optional(),
+  noProxy: z.array(z.string().min(1)).default([]),
+  providers: z.array(z.string().min(1)).min(1).default(["opencode"]),
+  patterns: z.array(z.string().min(1)).min(1).default([
+    "FreeUsageLimitError", "free usage exceeded", String.raw`rate limit exceeded\. please try again later`,
+  ]),
+  timeoutMs: z.number().int().positive().default(25000),
+  cooldownMs: z.number().int().nonnegative().default(30000),
+}).strict();
+
+export type OptionsType = z.infer<typeof Options>;
+export type Failure = { type: string; message: string; status?: number };
+/** A rejected rotation whose timeout applies to retrying the current work request. */
+export class RotationRateLimit extends Error {
+  /** Carry the wait before retrying work, without requesting another rotation. */
+  constructor(message: string, readonly retryAfterMs: number) {
+    super(message);
+  }
+}
+/** Match configured exhaustion errors only for permitted providers and HTTP statuses. */
+export function detector(options: OptionsType) {
+  const patterns = options.patterns.map((pattern) => new RegExp(pattern, "i"));
+  return (provider: string, error: Failure) => options.providers.includes(provider)
+    && (error.status === undefined || [402, 403, 429].includes(error.status))
+    && patterns.some((pattern) => pattern.test(`${error.type}: ${error.message}`));
+}
+
+/** Parse Retry-After as seconds or an HTTP date, retaining a bounded fallback. */
+function retryDelay(header: string | null, cooldownMs: number): number {
+  if (header === null) return Math.max(1000, cooldownMs);
+  const seconds = /^\d+(?:\.\d+)?$/.test(header.trim()) ? Number(header) : Number.NaN;
+  const delay = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(header) - Date.now();
+  return Number.isFinite(delay) ? Math.max(1000, delay) : Math.max(1000, cooldownMs);
+}
+
+/** Create an authenticated control client with shared rotation requests and cooldowns. */
+export function makeClient(options: OptionsType, token: string, fetcher: typeof fetch = fetch) {
+  const host = options.apiIp.includes(":") ? `[${options.apiIp}]` : options.apiIp;
+  const base = new URL(`${options.apiScheme}://${host}:${options.apiPort}/`);
+  let pending: Promise<string> | undefined;
+  let lastRotation = -Infinity;
+  /** Call the control API directly and expose 429 retry delays to the work retry hook. */
+  async function call(path: string, method: string) {
+    const init: RequestInit & { proxy: false } = {
+      // Bun fetch must reach the control API even while the SSH tunnel is down.
+      proxy: false,
+      method, headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(options.timeoutMs), redirect: "error",
+    };
+    const response = await fetcher(new URL(path, base), init);
+    if (!response.ok) {
+      const message = `Tunnel API ${response.status}: ${await response.text()}`;
+      if (response.status === 429) {
+        throw new RotationRateLimit(message, retryDelay(response.headers.get("Retry-After"), options.cooldownMs));
+      }
+      throw new Error(message);
+    }
+    return await response.text();
+  }
+  return {
+    /** Read tunnel status without rotating or using the tunnel proxy. */
+    status: () => call("status", "GET"),
+    /** Attempt one rotation, sharing in-flight calls and reporting remaining cooldowns. */
+    rotate: () => {
+      if (pending) return pending;
+      const remaining = options.cooldownMs - (Date.now() - lastRotation);
+      if (remaining > 0) return Promise.reject(new RotationRateLimit("Tunnel rotation cooldown active", remaining));
+      lastRotation = Date.now();
+      pending = call("rotate", "POST").finally(() => { pending = undefined; });
+      return pending;
+    },
+  };
+}

package/src/discovery.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import type { OptionsType } from "./client.js";
+
+const Status = z.object({
+  http_proxy: z.object({
+    enabled: z.boolean(),
+    ip: z.union([z.ipv4(), z.ipv6()]),
+    port: z.number().int().min(1).max(65535),
+  }),
+});
+
+export function discoverProxy(options: OptionsType, response: string): { proxyIp: string; proxyPort: number } {
+  let status: z.infer<typeof Status>;
+  try {
+    status = Status.parse(JSON.parse(response));
+  } catch {
+    throw new Error("Proxy discovery failed: /status must contain valid http_proxy enabled, ip and port fields");
+  }
+  if (!status.http_proxy.enabled)
+    throw new Error("Proxy discovery failed: the service HTTP proxy is disabled");
+  const bindIp = status.http_proxy.ip;
+  const advertisedIp = bindIp === "0.0.0.0" || bindIp === "::" ? options.apiIp : bindIp;
+  const proxyIp = options.proxyIp ?? advertisedIp;
+  if (proxyIp === "0.0.0.0" || proxyIp === "::")
+    throw new Error("Proxy discovery failed: proxyIp must be a reachable address, not a wildcard bind address");
+  return { proxyIp, proxyPort: options.proxyPort ?? status.http_proxy.port };
+}

package/src/environment.ts

@@ -0,0 +1,55 @@
+import type { OptionsType } from "./client.js";
+
+const keys = ["HTTP_PROXY", "http_proxy", "HTTPS_PROXY", "https_proxy", "ALL_PROXY", "all_proxy", "NO_PROXY", "no_proxy"] as const;
+type Variables = Partial<Record<typeof keys[number], string>>;
+type Lease = { proxy: string; bypass: string[] };
+type State = { baseline: Variables; applied: Variables; leases: Lease[] };
+const states = new WeakMap<NodeJS.ProcessEnv, State>();
+
+function values(state: State): Variables {
+  const top = state.leases.at(-1);
+  if (!top) return state.baseline;
+  const bypass = new Set([
+    ...(state.baseline.NO_PROXY ?? "").split(/[\s,]+/),
+    ...(state.baseline.no_proxy ?? "").split(/[\s,]+/),
+    ...state.leases.flatMap((lease) => lease.bypass),
+  ].filter(Boolean));
+  return Object.fromEntries(keys.map((key) => [key,
+    key.toLowerCase() === "no_proxy" ? [...bypass].join(",") : top.proxy]));
+}
+
+/** Leases prevent unloading one project plugin from breaking another in the same process. */
+export function configureProcessProxy(options: Omit<OptionsType, "proxyPort"> & { proxyPort: number }, environment: NodeJS.ProcessEnv = process.env): () => void {
+  if (!options.configureProxy) return () => {};
+  let state = states.get(environment);
+  if (!state) {
+    const baseline = Object.fromEntries(keys.map((key) => [key, environment[key]]));
+    state = { baseline, applied: baseline, leases: [] };
+    states.set(environment, state);
+  }
+  const ip = options.proxyIp ?? options.apiIp;
+  const host = ip.includes(":") ? `[${ip}]` : ip;
+  const lease: Lease = {
+    proxy: `http://${host}:${options.proxyPort}`,
+    bypass: ["localhost", "127.0.0.1", "::1", options.apiIp, ...options.noProxy],
+  };
+  state.leases.push(lease);
+  state.applied = values(state);
+  for (const key of keys) environment[key] = state.applied[key];
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const previous = state.applied;
+    state.leases.splice(state.leases.indexOf(lease), 1);
+    const next = values(state);
+    for (const key of keys) {
+      // Preserve changes made by another component after we configured the environment.
+      if (environment[key] !== previous[key]) continue;
+      if (next[key] === undefined) delete environment[key];
+      else environment[key] = next[key];
+    }
+    state.applied = next;
+    if (!state.leases.length) states.delete(environment);
+  };
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+import { Plugin } from "@opencode/plugin";
+import { Options, RotationRateLimit, detector, makeClient } from "./client.js";
+import { configureProcessProxy } from "./environment.js";
+import { discoverProxy } from "./discovery.js";
+
+export default Plugin.define({
+  id: "tunnel-switch",
+  /** Discover the proxy, register bounded work retries and status commands, and return environment cleanup. */
+  async setup(ctx) {
+    const options = Options.parse(ctx.options);
+    const client = makeClient(options, options.apiToken);
+    const matches = detector(options);
+    const rateLimitedSessions = new Set<string>();
+    let restoreEnvironment = () => {};
+    if (options.configureProxy) {
+      let status: string;
+      try { status = await client.status(); }
+      catch (error) {
+        throw new Error(`Proxy discovery failed: could not query /status: ${String(error)}`);
+      }
+      restoreEnvironment = configureProcessProxy({ ...options, ...discoverProxy(options, status) });
+    }
+    try {
+      await ctx.session.hook("retry", async (event) => {
+        // Only the first retry opportunity may rotate. OpenCode retains its hard retry limit.
+        if (event.attempt > 2) {
+          rateLimitedSessions.delete(event.sessionID);
+          return;
+        }
+        if (!matches(event.model.providerID, event.error)) return;
+        // A rate-limited switch only delays the work; do not attempt another switch in this retry sequence.
+        if (event.attempt === 1) rateLimitedSessions.delete(event.sessionID);
+        else if (rateLimitedSessions.delete(event.sessionID)) return;
+        try {
+          const status = await client.rotate();
+          event.decision = { retry: true, delay: 1000 };
+          // Return the retry decision immediately so status rendering cannot hold up continuation.
+          void Promise.resolve().then(() => ctx.session.synthetic({ sessionID: event.sessionID, text: `SSH tunnel rotated: ${status}. Continuing the current work.` }))
+            .catch((error) => console.error("[tunnel-switch] Could not display rotation status", String(error)));
+        } catch (error) {
+          if (error instanceof RotationRateLimit) {
+            rateLimitedSessions.add(event.sessionID);
+            event.decision = { retry: true, delay: Math.ceil(error.retryAfterMs) };
+          } else {
+            event.decision = { retry: false };
+          }
+          console.error(`[tunnel-switch] ${error instanceof Error ? error.message : String(error)}`);
+        }
+      });
+      await ctx.command.transform((editor) => {
+        editor.add({
+          name: "tunnel-status",
+          description: "Display SSH tunnel connection ID and start time",
+          execute: async ({ sessionID }) => {
+            let text: string;
+            try { text = `SSH tunnel status: ${await client.status()}`; }
+            catch (error) { text = `SSH tunnel status failed: ${String(error)}`; }
+            await ctx.session.synthetic({ sessionID, text });
+          },
+        });
+      });
+    } catch (error) {
+      restoreEnvironment();
+      throw error;
+    }
+    return restoreEnvironment;
+  },
+});

package/src/status.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { discoverProxy } from "./discovery.js";
+import type { OptionsType } from "./client.js";
+
+const Status = z.object({
+  state: z.enum(["connected", "disconnected", "rotating"]),
+  connection_id: z.string().nullable(),
+  started_at: z.iso.datetime({ offset: true }).nullable(),
+  server: z.string().nullable().optional(),
+});
+export type TunnelStatus = z.infer<typeof Status> & { proxy: string };
+
+/** Validate the server response and display only allowlisted connection fields. */
+export function parseStatus(response: string, options: OptionsType): TunnelStatus {
+  const raw: unknown = JSON.parse(response);
+  const status = Status.parse(raw);
+  let proxy = "Disabled";
+  const disabled = z.object({ http_proxy: z.object({ enabled: z.literal(false) }) }).safeParse(raw).success;
+  if (!disabled) {
+    const { proxyIp, proxyPort } = discoverProxy(options, response);
+    const host = proxyIp.includes(":") ? `[${proxyIp}]` : proxyIp;
+    proxy = `${host}:${proxyPort}`;
+  }
+  return { ...status, proxy };
+}
+
+/** Format elapsed time without reporting negative uptime for clock skew. */
+export function uptime(startedAt: string | null, now: number): string {
+  if (!startedAt) return "—";
+  const seconds = Math.max(0, Math.floor((now - Date.parse(startedAt)) / 1000));
+  return `${Math.floor(seconds / 3600)}h ${Math.floor(seconds / 60) % 60}m ${seconds % 60}s`;
+}
+
+/** Poll serially, retain the last good response on failure, and stop on disposal. */
+export function watchStatus(read: () => Promise<string>, options: OptionsType,
+  update: (status: TunnelStatus | undefined, available: boolean, checked: number, lastSuccessful: number | undefined) => void,
+  intervalMs = 5000) {
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let pending: Promise<void> | undefined;
+  let status: TunnelStatus | undefined;
+  let lastSuccessful: number | undefined;
+  function refresh(): Promise<void> {
+    if (stopped) return Promise.resolve();
+    if (pending) return pending;
+    clearTimeout(timer);
+    pending = (async () => {
+      let available = false;
+      try {
+        status = parseStatus(await read(), options);
+        lastSuccessful = Date.now();
+        available = true;
+      } catch { /* Never display API errors or credentials. */ }
+      if (!stopped) update(status, available, Date.now(), lastSuccessful);
+    })().finally(() => {
+      pending = undefined;
+      if (!stopped) timer = setTimeout(() => { void refresh(); }, intervalMs);
+    });
+    return pending;
+  }
+  void refresh();
+  return { refresh, stop() { stopped = true; clearTimeout(timer); } };
+}

package/src/tui.ts

@@ -0,0 +1,226 @@
+import { Plugin } from "@opencode/plugin/tui";
+import { Options, makeClient, type OptionsType } from "./client.js";
+import { uptime, watchStatus, type TunnelStatus } from "./status.js";
+
+type JsxRuntime = typeof import("@opentui/solid/jsx-runtime");
+type SolidRuntime = typeof import("solid-js");
+
+/**
+ * The TUI runtime shares its OpenTUI/Solid singletons with plugins through
+ * virtual `opentui:runtime-module:` ids (registered by OpenCode at startup).
+ * Importing `@opentui/solid`/`solid-js` directly loads a second renderer
+ * instance whose `RendererContext` is never provided, so every slot render
+ * throws "No renderer found". Prefer the host ids, then the local packages
+ * (test harnesses), then give up.
+ */
+const runtimeModule = (specifier: string) => `opentui:runtime-module:${encodeURIComponent(specifier)}`;
+
+async function uiRuntime(): Promise<{ readonly jsx: JsxRuntime["jsx"]; readonly createSignal: SolidRuntime["createSignal"] } | undefined> {
+  try {
+    const [jsxRuntime, solid] = await Promise.all([
+      import(runtimeModule("@opentui/solid/jsx-runtime")) as Promise<JsxRuntime>,
+      import(runtimeModule("solid-js")) as Promise<SolidRuntime>,
+    ]);
+    return { jsx: jsxRuntime.jsx, createSignal: solid.createSignal };
+  } catch {
+    try {
+      const [jsxRuntime, solid] = await Promise.all([
+        import("@opentui/solid/jsx-runtime"),
+        import("solid-js"),
+      ]);
+      return { jsx: jsxRuntime.jsx, createSignal: solid.createSignal };
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+/** Format an ISO timestamp as HH:MM:SS DD/MM/YY. */
+function formatTimestamp(value: string | null | undefined): string {
+  if (!value) return "—";
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  const pad = (part: number) => String(part).padStart(2, "0");
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())} `
+    + `${pad(date.getDate())}/${pad(date.getMonth() + 1)}/${pad(date.getFullYear() % 100)}`;
+}
+
+/** Compact relative age for the last check, e.g. "25s ago" or "2.5hr ago". */
+function formatAge(from: number, to: number): string {
+  const seconds = Math.max(0, Math.round((to - from) / 1000));
+  if (seconds < 60) return `${seconds}s ago`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m ago`;
+  if (seconds < 86400) return `${(seconds / 3600).toFixed(1)}hr ago`;
+  return `${(seconds / 86400).toFixed(1)}d ago`;
+}
+
+export default Plugin.define({
+  id: "tunnel-switch",
+  /** Add a read-only sidebar with bounded serial polling and disposal cleanup. */
+  async setup(ctx) {
+    let options: OptionsType;
+    try {
+      options = Options.parse(ctx.options);
+    } catch (error) {
+      // OpenCode's TUI runtime only receives options declared in cli.json; options
+      // from opencode.json(c) stay server-side, so degrade with actionable guidance.
+      const issue = (error as { issues?: Array<{ path: PropertyKey[]; message: string }> }).issues?.[0];
+      const detail = issue ? `${issue.path.join(".")}: ${issue.message}` : String(error);
+      ctx.ui.toast.show({
+        variant: "error",
+        title: "tunnel-switch: options unavailable",
+        message: `${detail} — declare this plugin with its options in cli.json to enable the `
+          + "tunnel sidebar.",
+        duration: 10000,
+      });
+      return () => {};
+    }
+    const ui = await uiRuntime();
+    if (!ui) {
+      ctx.ui.toast.show({
+        variant: "error",
+        title: "tunnel-switch: sidebar unavailable",
+        message: "Neither the host UI runtime nor a local @opentui/solid install is available; "
+          + "the tunnel still rotates through the server plugin.",
+        duration: 10000,
+      });
+      return () => {};
+    }
+    const { jsx, createSignal } = ui;
+    // Follow the MCP sidebar's conventions: <text fg> for whole-line colours,
+    // style={{ fg }} on <span> for inline runs (a bare fg prop on a span is
+    // silently dropped by the reconciler), theme feedback colours for states.
+    const themed = (path: readonly string[], fallback: string): string => {
+      let current: unknown = ctx.theme;
+      for (const key of path) current = (current as Record<string, unknown> | undefined)?.[key];
+      return typeof current === "string" ? current : fallback;
+    };
+    const base = themed(["text", "base"], "#ffffff");
+    const muted = themed(["text", "muted"], "#868895");
+    const positive = themed(["text", "feedback", "success", "base"], "#a6e3a1");
+    const warning = themed(["text", "feedback", "warning", "base"], "#f9e2af");
+    const negative = themed(["text", "feedback", "error", "base"], "#f38ba8");
+    // A row: bold title in the theme's base colour, two-space indented and
+    // without a colon; value flush right (muted or state-coloured), matching
+    // the sibling sidebars' label/value layout.
+    const line = (label: string, value: string | (() => string), colour?: string, suffix?: string) =>
+      jsx("box", { flexDirection: "row", gap: 1, minWidth: 0, get children() { return [
+        jsx("text", { fg: base, wrapMode: "none", truncate: true, flexGrow: 1, flexShrink: 1, minWidth: 0,
+          get children() { return jsx("b", { children: `  ${label}` }); } }),
+        jsx("text", { wrapMode: "none", truncate: true, flexShrink: 0, get children() {
+          const children = [jsx("span", {
+            style: { fg: colour ?? muted },
+            get children() { return typeof value === "function" ? value() : value; },
+          })];
+          if (suffix) children.push(jsx("span", { style: { fg: muted }, children: suffix }));
+          return children;
+        } }),
+      ]; } });
+    // Muted summary shown beside "Tunnel" while the sidebar is collapsed,
+    // naming the tunnel (its configured server) once one has been reported.
+    // The name is capped so a long hostname cannot push the reachability
+    // state out of the collapsed header.
+    /** Keep a server name within 20 columns, elided with an ellipsis. */
+    const clipName = (name: string): string => (name.length <= 20 ? name : `${name.slice(0, 19)}…`);
+    const collapsedSummary = (name: string | null | undefined, checked: number | undefined,
+      available: boolean): string => {
+      let reach: string;
+      if (!checked) reach = "checking…";
+      else if (available) reach = "reachable";
+      else reach = "unavailable";
+      if (!name) return ` (${reach})`;
+      return ` (${clipName(name)} · ${reach})`;
+    };
+    // Feedback colour for a tunnel state.
+    const stateColour = (state: TunnelStatus["state"]): string => {
+      if (state === "connected") return positive;
+      if (state === "rotating") return warning;
+      return negative;
+    };
+    const client = makeClient(options, options.apiToken);
+    const [snapshot, setSnapshot] = createSignal<{
+      status?: TunnelStatus; available: boolean; checked?: number; lastSuccessful?: number;
+    }>({ available: false });
+    const [clock, setClock] = createSignal(Date.now());
+    const [expanded, setExpanded] = createSignal(true);
+    // Tick once a second so the relative "Checked" age stays live between polls.
+    const ticker = setInterval(() => setClock(Date.now()), 1000);
+    const watcher = watchStatus(client.status, options, (status, available, checked, lastSuccessful) => {
+      setSnapshot({ status, available, checked, lastSuccessful });
+    });
+    let removeSlot: (() => void) | undefined;
+    let warned = false;
+    const stop = () => { clearInterval(ticker); watcher.stop(); removeSlot?.(); };
+    try {
+      removeSlot = ctx.ui.slot({
+        append: "sidebar.content",
+        render: () => {
+          try {
+            return jsx("box", { flexDirection: "column", marginTop: 1, get children() {
+              const { status, available, checked, lastSuccessful } = snapshot();
+              const open = expanded();
+              // Collapsible header, toggled by clicking like the MCP sidebar box.
+              const header = jsx("box", { flexDirection: "row", gap: 1, onMouseDown: () => setExpanded(!open), get children() { return [
+                jsx("text", { fg: base, children: open ? "▼" : "▶" }),
+                jsx("text", { fg: base, get children() {
+                  const children = [jsx("b", { children: "Tunnel" })];
+                  if (!open) children.push(jsx("span", { style: { fg: muted },
+                    children: collapsedSummary(status?.server, checked, available) }));
+                  return children;
+                } }),
+              ]; } });
+              if (!open) return [header];
+              if (!checked) return [header, jsx("text", { fg: muted, children: "Checking status…" })];
+              const lines = [
+                line("API", available ? "reachable" : "unavailable", available ? positive : negative),
+              ];
+              if (status) {
+                lines.push(
+                  line("State", status.state, stateColour(status.state), available ? undefined : " (last known)"),
+                  line("Server", status.server ?? "—"),
+                  line("Started", formatTimestamp(status.started_at)),
+                  line("Uptime", () => uptime(status.started_at, lastSuccessful ?? checked), undefined,
+                    available ? undefined : " (at last success)"),
+                  line("Proxy", status.proxy),
+                );
+              }
+              // The relative age stays muted (the default value colour) between polls.
+              lines.push(line("Checked", () => formatAge(checked, clock()), muted));
+              return [header, ...lines];
+            } });
+          } catch {
+            // The local fallback instance cannot render against the host's
+            // renderer; degrade once instead of crashing the slot boundary.
+            if (!warned) {
+              warned = true;
+              ctx.ui.toast.show({
+                variant: "error",
+                title: "tunnel-switch: sidebar unavailable",
+                message: "This OpenCode build did not share its UI runtime with the plugin "
+                  + "(OpenTUI instance mismatch); the tunnel still rotates server-side.",
+                duration: 10000,
+              });
+            }
+            return null;
+          }
+        },
+      });
+      ctx.keymap.layer(() => ({
+        mode: "global",
+        commands: [{
+          id: "tunnel-switch.refresh", title: "Refresh tunnel status", group: "Tunnel",
+          palette: true, slash: { name: "tunnel-refresh" },
+          run: async () => { await watcher.refresh(); },
+        }, {
+          id: "tunnel-switch.toggle", title: "Toggle tunnel sidebar details", group: "Tunnel",
+          palette: true, slash: { name: "tunnel-toggle" },
+          run: () => { setExpanded(!expanded()); },
+        }],
+      }));
+    } catch (error) {
+      stop();
+      throw error;
+    }
+    return stop;
+  },
+});

package/tui.ts

@@ -0,0 +1,2 @@
+// OpenCode's local-directory loader resolves this root TUI entrypoint.
+export { default } from "./src/tui.js";