opencode-ufr 0.2.9 → 0.2.10

package/README.md

@@ -2,14 +2,14 @@
 
 An [opencode](https://opencode.ai) provider for **Uni Freiburg's Open WebUI
 models**. A small local gateway runs on your machine, pools your UFR API
-key(s), and handles UFR's rate limits and outages so opencode doesn't have to.
+key, and handles UFR's rate limits and outages so opencode doesn't have to.
 Off campus, it connects through the uni's Fortinet VPN **by itself** — with no
 TUN device, no admin rights and no external tools.
 
 ```
 opencode ⇄ gateway (127.0.0.1) ⇄ [Fortinet tunnel] ⇄ openwebui.uni-freiburg.de
                     │
-                    ├─ key pool (1…n UFR accounts)
+                    ├─ key pool (your UFR account)
                     ├─ rate-limit pacing, circuit breakers, fallbacks
                     └─ VPN when off campus (userspace TCP/IP stack)
 ```
@@ -17,13 +17,12 @@ opencode ⇄ gateway (127.0.0.1) ⇄ [Fortinet tunnel] ⇄ openwebui.uni-freibur
 ## Install
 
 ```bash
-bun add -g opencode-ufr              # puts `ufr` on PATH
 opencode plugin add opencode-ufr     # registers the plugin
 ```
 
 (or add `"plugins": ["opencode-ufr"]` to your `opencode.json` manually.)
 
-## Install
+## Update
 
 opencode installs the plugin once into its cache and does not look for a newer
 version while that copy exists — restarting opencode alone keeps the old one.
@@ -32,9 +31,8 @@ that keeps running after you close the TUI. To update, remove the cached copy
 and stop that server:
 
 ```bash
-bun add -g opencode-ufr@latest                      # update the `ufr` CLI
 rm -rf ~/.cache/opencode/npm/opencode-ufr@latest    # opencode's cached plugin copy
-/restart in opencode eintippen                      # opencode's background server
+/restart in opencode                                # stops opencode's background server
 ```
 
 The next opencode start installs the latest version and replaces the old
@@ -43,28 +41,17 @@ Manager and delete the `opencode-ufr@latest` folder in opencode's cache.
 
 ## Setup
 
-**Inside opencode — the normal way:** open `/connect`, pick **Uni Freiburg**,
-and fill in:
+Open `/connect` in opencode, pick **Uni Freiburg**, and fill in:
 
 | Field | Needed? |
 |---|---|
-| **API keys** | always — paste one key per UFR account, comma-separated (whitespace is filtered) |
+| **API key** | always — your UFR API key (Open WebUI → Settings → Account → API keys) |
 | **Uni login** | only off campus — e.g. `xx0000@uni-freiburg.de`, empty on the uni network |
 | **Uni password** | only with a login above |
 
 Submitted credentials land in your OS keyring (never on disk), the gateway
 restarts with them, and the `unifreiburg/…` models appear in the model picker.
 
-**In a terminal — the fallback:** works before opencode ever starts.
-
-```bash
-ufr connect --keys "<key1>,<key2>"                                 # keys only
-ufr connect --login xx0000@uni-freiburg.de --password … --keys "…"   # + VPN login
-```
-
-`ufr connect` verifies every key against UFR, assigns aliases (`key1`, `key2`,
-…) automatically and accepts keys comma- or line-separated.
-
 ## Use
 
 Models show up in opencode as `unifreiburg/<model>`, e.g.
@@ -72,21 +59,17 @@ Models show up in opencode as `unifreiburg/<model>`, e.g.
 gateway starts itself the first time opencode needs it (the plugin waits up to
 40 s) and shuts down after 5 minutes idle. You never manage it directly.
 
-```bash
-ufr status       # gateway, keys, limits, breakers, vpn, spend today
-ufr stats        # requests, tokens and cost
-ufr keys list    # stored aliases
-ufr keys test    # check your keys against UFR
-ufr login show   # the stored uni login
-ufr disconnect   # remove everything: keys, uni login, config, gateway
-```
+The plugin adds a line to opencode's sidebar with live gateway throughput —
+requests/s and tokens/s (in and out) over the gateway's rolling 60 s window.
+It hides while the gateway is off, and polling it never keeps the gateway
+alive. The same numbers are served on `GET /v1/_status` under `rates` for
+anything else that wants them.
 
-Removing the **unifreiburg** integration in opencode's `/connect` panel does the
-same as `ufr disconnect`: the stored keys and uni login are wiped, the gateway
-stops, and the models disappear from the picker on the next opencode start.
-While opencode runs, connecting and removing are noticed within seconds. If
-opencode was closed when you removed the integration, run `ufr disconnect` once
-to wipe what is left.
+Removing the **unifreiburg** integration in opencode's `/connect` panel wipes
+everything: the stored key and uni login are deleted, the gateway stops, and
+the models disappear from the picker on the next opencode start. While
+opencode runs, connecting and removing are noticed within seconds — and even
+if opencode was closed during the removal, the next start wipes what is left.
 
 ## The built-in VPN
 
@@ -115,20 +98,32 @@ What that means in practice:
 - If the tunnel dies, it reconnects with backoff — no session is lost, the
   gateway just waits until the path is back.
 
-## More than one key
-
-UFR allows one API key per account, so one key is one account's worth of
-throughput. The key pool round-robins across all stored keys and keeps each
-under UFR's per-key limits; adding more keys only helps if they belong to
-different UFR accounts.
+## PDF to Markdown (skill)
+
+The plugin registers a **ufr-pdf2md** skill with opencode: an agentic
+PDF-to-Markdown pipeline on the UFR vision models — page classification,
+OCR with tables and LaTeX, and for circuit diagrams and flowcharts a
+three-model ensemble (glm-5.3-flash, deepseek-v4.1-flash, qwen-3.5-397b)
+with quadrant zoom and an adjudication pass that resolves disagreements
+against the page image. Flowcharts and node graphs additionally come out as
+node lists, edge lists and Mermaid graphs; a refinement loop and cross-page
+table merging finish the document. opencode's agent loads the skill on its
+own when you ask it to convert a PDF — you never run anything by hand.
+
+Every model call goes through the gateway's relay (`POST /v1/_relay`): the
+same central key rotation and soft rate limiting as chat. Pages run with up
+to 16 parallel workers (auto-tuned), the key pool queues them and waits for
+a free slot — nothing hammers UFR. The relay is also usable by your own
+scripts (`src/client/gateway.ts`), and the context probe uses it too: the
+old fixed pause between probe calls is gone, the key pool paces instead.
 
 ## What the gateway does
 
-- Keeps each key under 18 of UFR's 20 requests-per-rolling-minute, waiting
-  instead of failing when a key is close to its limit.
-- Enforces a pool-wide cap of 800 requests/hour across all keys and models —
-  UFR walls a model group for hours once it sees sustained traffic above
-  roughly 900/hour.
+- Keeps the key under 19 of UFR's 20 requests-per-rolling-minute, waiting
+  instead of failing when it is close to its limit.
+- Can enforce a pool-wide cap on requests/hour across all models (off by
+  default; `limits.poolPerHour`) — the old ~900/h model-group wall is gone,
+  so nothing throttles beyond the per-key bucket unless you set a cap.
 - Runs a circuit breaker per model: after repeated failures it backs off from
   30 s up to 60 minutes before probing again, instead of hammering a walled
   model.
@@ -141,15 +136,15 @@ different UFR accounts.
 - Retries once with reasoning turned off if a `glm` model spends its whole
   token budget thinking and returns no text.
 - Keeps local stats in the same "% of $20/day" unit UFR's own portal uses, so
-  the numbers in `ufr status` line up with what you see there.
+  the recorded spend lines up with what you see there.
 - Survives being killed: if the gateway's lock file is left behind by an
   unclean shutdown, the next start detects it's stale and takes it over
   rather than refusing to start.
 
 ## Configuration
 
-Non-secret settings live in a JSON file; keys and the uni login always stay in
-the OS keyring.
+Non-secret settings live in a JSON file; the key and the uni login always stay
+in the OS keyring.
 
 - **Linux / macOS:** `~/.config/opencode-ufr/config.json` (state in
   `~/.local/state/opencode-ufr`, cache in `~/.cache/opencode-ufr`, data in
@@ -169,11 +164,12 @@ except `port`, which is written on first start):
   "port": 47300,
   "transport": { "type": "auto" },
   "vpn": { "gateway": "https://fortivpn.uni-freiburg.de", "mode": "auto" },
-  "keys": ["a", "b"],
+  "upstream": { "baseUrl": "https://openwebui.uni-freiburg.de/api", "requestTimeoutS": 600 },
+  "keys": [],
   "limits": {
-    "keyRpm": 18,
+    "keyRpm": 19,
     "keyWindowS": 60,
-    "poolPerHour": 800,
+    "poolPerHour": 0,
     "poolWindowS": 3600,
     "keyMaxWaitS": 60,
     "poolMaxWaitS": 20,
@@ -186,21 +182,19 @@ except `port`, which is written on first start):
     "probeTimeoutS": 120
   },
   "allowPaid": false,
-  "catalog": {
-    "url": "https://raw.githubusercontent.com/FinleyLaempe/opencode-ufr/main/models.json",
-    "refreshHours": 6
-  },
   "idleShutdownMin": 5
 }
 ```
 
 `port` is chosen once (preferred `47300`, next free port if taken) and then
-stays fixed across restarts. `poolPerHour: 0` disables the pool limiter.
-`transport.type: "direct"` never opens the tunnel.
+stays fixed across restarts. `poolPerHour: 0` (the default) disables the pool limiter.
+`transport.type: "direct"` never opens the tunnel. `upstream.requestTimeoutS`
+is the per-request timeout in seconds. `keys` lists keyring aliases and is
+filled in by the plugin when you connect — you normally never edit it by hand.
 
 ## Releases
 
-Releases are tag-driven: `scripts/release.sh 0.2.1` bumps, commits, tags and
+Releases are tag-driven: `scripts/release.sh 0.2.9` bumps, commits, tags and
 pushes; the workflow then verifies on Ubuntu, macOS and Windows, stages the
 package on npm (trusted publishing via OIDC — no stored tokens), and creates
 the GitHub release after a maintainer approves the staged version with 2FA.
@@ -214,12 +208,11 @@ doesn't expose or gets wrong. Fixes reach users with the next plugin update.
 Context windows are measured, not guessed: the `probe contexts` workflow
 (weekly, on demand, and after every release tag) sends one oversized — and
 therefore free, since UFR rejects it before pricing — request per model and
-commits the exact limit the server names back to `models.json` on main. Run
-it yourself with a stored key:
+commits the exact limit the server names back to `models.json` on main.
+Maintainers run the same measurement locally:
 
 ```bash
-ufr context-probe            # report: measured context vs. models.json
-ufr context-probe --write    # also patch your local models.json
+bun scripts/probe-all-contexts.ts --keyring key1 --write   # report + patch models.json
 ```
 
 To contribute a measurement (a price, a context window, a missing alias),
@@ -228,7 +221,7 @@ open a PR against `models.json` with the source of the measurement in a
 
 ## Privacy
 
-- UFR API keys and the uni VPN login live only in your OS keyring (Keychain,
+- Your UFR API key and the uni VPN login live only in your OS keyring (Keychain,
   Credential Manager, or libsecret/KWallet on Linux) — never in a config file
   or in this repository.
 - The gateway listens on `127.0.0.1` only, behind a random local token; it

package/package.json

@@ -1,20 +1,25 @@
 {
   "name": "opencode-ufr",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Uni Freiburg (UFR) Open WebUI models in opencode — local gateway with key pool, UFR-aware rate limiting, circuit breaker and fallbacks",
   "license": "MIT",
   "type": "module",
   "main": "./src/plugin/index.ts",
   "exports": {
-    ".": "./src/plugin/index.ts"
+    ".": "./src/plugin/index.ts",
+    "./tui": "./src/plugin/tui.tsx"
   },
-  "bin": {
-    "ufr": "bin/ufr.ts",
-    "opencode-ufr": "bin/ufr.ts"
+  "dependencies": {
+    "@opencode/plugin": "^2.0.23"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.8",
+    "@opentui/solid": ">=0.5.8",
+    "solid-js": ">=1.9.0"
   },
   "files": [
-    "bin",
     "src",
+    "skills",
     "models.json",
     "README.md",
     "LICENSE"
@@ -38,7 +43,10 @@
     "prepublishOnly": "bun run typecheck && bun test"
   },
   "devDependencies": {
+    "@opentui/core": "^0.5.14",
+    "@opentui/solid": "^0.5.14",
     "@types/bun": "^1.3.0",
+    "solid-js": "^1.9.15",
     "typescript": "^5.9.0"
   }
 }

package/skills/pdf2md/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: PDF to Markdown
+description: Convert a PDF to clean Markdown using UFR vision models — full OCR with tables, math (LaTeX), circuit diagrams (component tables via quadrant zoom), a refinement loop and cross-page table merging. Use whenever the user asks to convert a PDF or scanned document to Markdown, especially with tables, formulas or technical drawings where plain text extraction fails.
+---
+
+Convert a PDF to Markdown with the UFR vision pipeline:
+
+```
+bun {{PDF2MD_SCRIPT}} <input.pdf> [output.md] [options]
+```
+
+Options: `--workers N` (0 = auto-tune, default), `--dpi 300`, `--no-dedup`, `--dedup-threshold 0.98`, `--no-refine`, `--no-merge`, `--verbose` / `-v`.
+
+## Workflow
+
+1. Check the prerequisites are on PATH: `pdftoppm`/`pdfinfo` (poppler-utils) and `magick` (ImageMagick). If missing, tell the user to install them (`poppler-utils` and `imagemagick` packages) instead of trying another conversion path.
+2. Run the command. Prefer giving an explicit `output.md` next to the input (stdout is the fallback); report the output path and page count.
+3. For large documents (> 20 pages), start with `--no-refine --no-merge` for a fast first pass, then refine only the pages the user cares about.
+
+## What the pipeline does
+
+- Renders each page at 300 DPI and drops PowerPoint-style incremental-reveal duplicates.
+- Classifies each page (TEXT / TABLE_MATH / DIAGRAM / MIXED) and routes it to the best model: glm-5.3-flash for text and tables (structure + LaTeX), and for diagrams an ensemble of three vision models (glm-5.3-flash, deepseek-v4.1-flash, qwen-3.5-397b) that each read the full page and every quadrant crop, followed by an adjudication pass that resolves disagreements against the image. Flowcharts and node graphs additionally get a node/edge list and a Mermaid rendering.
+- Runs a refinement loop that compares the markdown against the page image (3 rounds for tables/diagrams, 1 for text).
+- Merges tables that span page breaks at the end.
+
+## Notes
+
+- Every model call goes through the local opencode-ufr gateway, which rotates keys and paces requests automatically — **never add artificial sleeps between runs**; parallelism is handled and safe.
+- The first run with > 2 pages auto-tunes concurrency with a few lightweight probe requests.
+- Progress and page logs go to stderr; only the final markdown goes to stdout/the output file.
+- The script needs the gateway running (it starts one automatically if the plugin is installed); model availability depends on the Uni Freiburg connection like every other UFR model.

package/src/client/gateway.ts

@@ -0,0 +1,101 @@
+/**
+ * The one door scripts knock on: a connection to the local opencode-ufr
+ * gateway. Every model call made through here rides the gateway's central
+ * key rotation and soft rate limiting — the caller waits for a key slot
+ * instead of being told to back off, and never has to pace itself with
+ * artificial sleeps. Two primitives:
+ *
+ *  - relay(): one raw upstream call to exactly the requested model (no
+ *    fallbacks, no context hub, no reasoning retry) with UFR's status and
+ *    body passed through verbatim. For context probes and tools that must
+ *    know which model answered.
+ *  - chat(): a full chat completion with the gateway's fallback chain and
+ *    reasoning retry, for tools that just want text.
+ */
+import { fileURLToPath } from "node:url"
+import { type Conn, ensureDaemon, spawnDaemon } from "../plugin/ensure-daemon"
+import { resolvePaths } from "../shared/paths"
+import { VERSION } from "../shared/version"
+
+const DAEMON_ENTRY = fileURLToPath(new URL("../daemon/main.ts", import.meta.url))
+
+export type Gateway = { port: number; token: string; baseUrl: string }
+
+/** Find the running gateway or start one (waits up to ~40 s on a cold start). */
+export async function connectGateway(): Promise<Gateway> {
+  const paths = resolvePaths()
+  const conn: Conn = await ensureDaemon({
+    paths,
+    version: VERSION,
+    spawn: () => spawnDaemon(DAEMON_ENTRY, paths.stateDir),
+  })
+  return { port: conn.port, token: conn.token, baseUrl: `http://127.0.0.1:${conn.port}` }
+}
+
+export type RawResult = { status: number; body: string; retryAfterMs?: number; contentType: string }
+
+function retryAfterOf(res: Response): number | undefined {
+  const s = Number(res.headers.get("retry-after"))
+  return Number.isFinite(s) && s > 0 ? s * 1000 : undefined
+}
+
+/** One raw upstream call through the gateway (POST /v1/_relay). */
+export async function relay(
+  gw: Gateway,
+  body: Record<string, unknown>,
+  o: { signal?: AbortSignal; timeoutMs?: number } = {},
+): Promise<RawResult> {
+  const signal = o.timeoutMs
+    ? AbortSignal.any([o.signal, AbortSignal.timeout(o.timeoutMs)].filter((s): s is AbortSignal => s !== undefined))
+    : o.signal
+  const res = await fetch(`${gw.baseUrl}/v1/_relay`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${gw.token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal,
+  }).catch((e) => {
+    throw new Error(`cannot reach the gateway at ${gw.baseUrl} (${(e as Error).message})`)
+  })
+  return {
+    status: res.status,
+    body: await res.text(),
+    retryAfterMs: retryAfterOf(res),
+    contentType: res.headers.get("content-type") ?? "application/json",
+  }
+}
+
+export type ChatResult = { status: number; json: unknown }
+
+/** A full chat completion through the gateway (POST /v1/chat/completions). */
+export async function chat(
+  gw: Gateway,
+  body: Record<string, unknown>,
+  o: { signal?: AbortSignal } = {},
+): Promise<ChatResult> {
+  const res = await fetch(`${gw.baseUrl}/v1/chat/completions`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${gw.token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: o.signal,
+  }).catch((e) => {
+    throw new Error(`cannot reach the gateway at ${gw.baseUrl} (${(e as Error).message})`)
+  })
+  const text = await res.text()
+  let json: unknown = null
+  try {
+    json = JSON.parse(text)
+  } catch {
+    json = { error: { message: text.slice(0, 500), type: "invalid_response", code: res.status } }
+  }
+  return { status: res.status, json }
+}
+
+/** The gateway's raw catalog inputs: UFR's model list plus the bundled models.json. */
+export async function catalogData(gw: Gateway): Promise<{ ufr: unknown; file: unknown } | null> {
+  const res = await fetch(`${gw.baseUrl}/v1/_catalog`, {
+    headers: { Authorization: `Bearer ${gw.token}` },
+    signal: AbortSignal.timeout(10_000),
+  }).catch(() => null)
+  if (!res?.ok) return null
+  return (await res.json()) as { ufr: unknown; file: unknown } | null
+}