dsh-llm-workbuddy 0.1.0

package/README.md

@@ -0,0 +1,235 @@
+# dsh-llm-workbuddy
+
+在 DeepSeek Harness 中使用你的 **WorkBuddy / CodeBuddy** 账号模型的 LLM 适配器插件。
+
+它把 `workbuddy` 这个 provider 路由指向本地运行的
+[workbuddy2api](https://github.com/hawklithm/workbuddy2api) 代理
+（默认 `http://127.0.0.1:8787/v1`）。workbuddy2api 把 CodeBuddy/WorkBuddy 的
+私有协议转成标准 OpenAI chat-completions 格式，并用本地保存的登录态完成认证，
+因此本插件**不需要任何 API Key**。
+
+装好并启动后提供两件事：
+
+1. **模型能力**：Web 界面的模型选择器（composer 模型菜单或 `/model` 命令）会多出
+   一个 **WorkBuddy** 分组，模型（DeepSeek-V4、GLM-5.x、Kimi-K2.x、MiniMax-M3、
+   Hy3、Hunyuan…）随账号可用列表实时同步，点一下即可切换。
+2. **Web 登录状态小组件**：在 Web GUI 右下角常驻一个状态胶囊，**实时显示登录/
+   代理状态**，未登录时一键在新标签页打开 WorkBuddy 登录页，登录完成后自动变绿。
+   无需再回到终端手动跑登录脚本。
+
+---
+
+## 架构一览
+
+```
+┌──────────────────────────── DeepSeek Harness Web GUI ───────────────────────────┐
+│                                                                                  │
+│   [ 模型选择器 (WorkBuddy 分组) ]            [ WorkBuddy 状态胶囊 (右下角) ]      │
+│        │                                            │                            │
+│        │ GET /v1/models (代理发现)                  │ GET  /api/workbuddy/status │
+│        ▼                                            │ POST /api/workbuddy/login │
+│   lib/index.js (WorkBuddyAdapter)                  ▼                            │
+│        │ fetch                                       lib/index.js               │
+│        ▼  POST /chat/completions                     (registerWorkbuddyRoutes)  │
+│   workbuddy2api 代理 (127.0.0.1:8787)  ──health──▶   ├─ 读 .workbuddy/session.json│
+│        │                                            ├─ 探测代理 /health          │
+│        ▼                                            └─ spawn login_workbuddy.py │
+│   WorkBuddy / CodeBuddy 云端                                            │        │
+│                                                                          ▼        │
+│                                                       login_workbuddy.py ──▶ 写回 │
+│                                                            (设备流)        session │
+└──────────────────────────────────────────────────────────────────────────────────┘
+```
+
+- **后端路由**（`lib/index.js` 的 `registerWorkbuddyRoutes`）运行在 `dsh web` 的
+  HTTP 服务上，通过 Cordis 的 `ctx.webServer` 注册，headless profile 下自动跳过。
+- **前端胶囊**（`lib/client.js`）是零依赖的原生浏览器 JS，由 DSH 的 `dsh.client`
+  双端机制在 `window.__DSH_BOOT__` 中注入，serve 于
+  `/plugins/dsh-llm-workbuddy/client.js`。
+- **登录脚本**（`login_workbuddy.py`，仓库根）实现与官方 CodeBuddy 插件一致的
+  device flow（`platform=CLI` + codebuddy.cn 请求头）。
+
+---
+
+## 前置条件（重要）
+
+1. 代理必须跑在 **workbuddy2api 主分支源码**上，不能用 PyPI 的 2.0.3：
+   旧版缺少 `X-Product-Code` / Genie-IDE 等请求头，登录会在最后一步 401。
+2. 登录请使用仓库里的 `login_workbuddy.py`（`platform=CLI` + codebuddy.cn
+   请求头，与官方插件一致），**不要**用代理自带的 `--login`（VSCode platform
+   会 401）。
+3. 插件装入 profile 后需要**重启 `dsh web`** 才能加载新的 bundle（包括本小部件）。
+
+---
+
+## 安装插件
+
+在插件包目录（本仓库 `dsh-llm-workbuddy/`）执行：
+
+```sh
+dsh plugin --profile web add ./dsh-llm-workbuddy
+```
+
+CLI 会把依赖写进 profile 并把 `dsh-llm-workbuddy` 追加到 `dsh.profile.bundles`，
+同时在 `package.json` 的 `dsh.client` 声明里登记浏览器入口（见下文「Web 小部件
+工作原理」）。然后**重启** `dsh web`。
+
+> 本插件**没有任何构建步骤、零运行时依赖**：`lib/client.js` 是浏览器原生 JS，
+> 直接被 DSH serve，不需要 vite / react / TypeScript 编译。
+
+---
+
+## 启动代理（日常，先决条件）
+
+小组件依赖本地代理才能判断「代理是否运行」。先启动它：
+
+```sh
+./start-workbuddy.sh
+# 监听 http://127.0.0.1:8787
+```
+
+验证：
+
+```sh
+curl http://127.0.0.1:8787/health    # {"status":"ok","authenticated":true,...}
+curl http://127.0.0.1:8787/v1/models # 模型列表（含 glm-5.2 / deepseek-v4-pro ...）
+```
+
+> 登录态过期时 `authenticated` 变回 `false`，重跑登录即可，代理无需重启
+> （会话按请求读取）。
+
+---
+
+## 登录：两种方式
+
+### 方式 A（推荐）：在 Web GUI 里点一下
+
+1. 浏览器打开 `dsh web`（默认 `http://127.0.0.1:3080`）。
+2. 看**右下角**的状态胶囊：
+   - 🟢 `WorkBuddy · <账号昵称>` —— 已登录，无需操作。
+   - 🔴 `WorkBuddy · 未登录` 或带 `代理未运行` 提示 —— 点胶囊里的 **「登录」** 按钮。
+3. 点击后，后端 `POST /api/workbuddy/login` 会 `spawn` 运行 `login_workbuddy.py`，
+   解析它打印的设备流链接（`authUrl`）返回给前端；前端用 `window.open` 在**新标签页**
+   打开该登录页。
+4. 在新标签页用 WorkBuddy / CodeBuddy 账号（腾讯账号）完成扫码/授权。
+5. 胶囊会自动从每 5 秒轮询加快到每 2 秒（最多 30 次），一旦检测到
+   `.workbuddy/session.json` 的 `auth.expiresAt` 未过期且含 `accessToken`，
+   就切回 🟢 绿态，显示账号昵称。
+
+整个过程**不需要离开浏览器、不需要回终端**。
+
+### 方式 B（传统）：在终端手动跑
+
+```sh
+./login-workbuddy.sh
+# 浏览器打开打印的链接，用 WorkBuddy/CodeBuddy 账号登录
+# 完成后自动保存会话到 .workbuddy/session.json（也提示已写入 ~/.codebuddy-session.json）
+```
+
+两种方式的产物是同一个 `session.json`，可混用：终端登录后 Web 胶囊会自动变绿，
+Web 登录后终端脚本也读得到同一份会话。
+
+---
+
+## Web 小部件工作原理
+
+### 后端路由（`lib/index.js`）
+
+插件在 `apply(ctx, config)` 里通过 `ctx.webServer.register(...)` 注册两条路由
+（headless profile 无 `webServer`，自动跳过）：
+
+| 方法 + 路径 | 行为 |
+|---|---|
+| `GET /api/workbuddy/status` | 读取 `.workbuddy/session.json` 的 `auth.expiresAt` 判断会话是否有效，并 `fetch` 代理 `/health` 判断 `proxyUp`；返回 JSON：`{ sessionFile, authenticated, expiresAt, account, proxyUp, tokenValid, loginScriptAvailable }` |
+| `POST /api/workbuddy/login` | 若已有有效会话则直接返回 `alreadyLoggedIn`；否则 `spawn` `.tools/uv run login_workbuddy.py --session-file .workbuddy/session.json`，从子进程 stdout 解析出 `authUrl` 立即返回 `{ authUrl, pending:true }`（设备流在后台继续，前端轮询 status 感知完成） |
+
+> 会话文件与登录脚本路径按插件包位置自动推导：
+> `dsh-llm-workbuddy/lib/index.js` 向上两级即仓库根 `dsh-workbuddy/`，其下的
+> `.workbuddy/session.json` 与 `login_workbuddy.py` 即为目标。
+
+### 前端胶囊（`lib/client.js`）
+
+- 作为经典 `<script>` 被 DSH 注入页面，IIFE 内直接操作 DOM，**零依赖**。
+- 启动时在 `document.body` 末尾挂一个 `position:fixed` 的胶囊（右下角）。
+- 每 **5 秒** `GET /api/workbuddy/status`；点「登录」后加快到每 **2 秒**轮询、
+  最多 30 次，直到 `authenticated:true`。
+- 状态映射：
+  - `authenticated && proxyUp` → 🟢 绿，显示 `WorkBuddy · <昵称>`
+  - 否则 → 🔴 红，显示「登录」按钮；`proxyUp` 为 false 时额外提示 `代理未运行`
+
+### 为什么不需要构建
+
+DSH 的 `dsh.client` 机制只要求 `package.json` 里：
+
+```json
+{
+  "dsh": { "client": { "platform": "web" } },
+  "exports": { "./client": "./lib/client.js" }
+}
+```
+
+`dsh web` 会自动把 `exports["./client"]` 指向的文件 serve 到
+`/plugins/<package-name>/client.js` 并注入引导清单，**不要求打包器**。
+
+---
+
+## 配置
+
+插件入口配置（profile 的 `cordis.patch.yml` 或用户设置文档的 `llm-workbuddy:`
+分节）。注意：状态小组件使用的代理地址取自这里的 `baseURL`（去掉 `/v1` 后探
+`/health`）。
+
+```yaml
+- id: llm-workbuddy
+  name: 'dsh-llm-workbuddy'
+  config:
+    baseURL: http://127.0.0.1:8787/v1   # workbuddy2api 端点（小组件据此探 /health）
+    # apiKey: ''                        # 代理一般不需要；如代理以 --api-key 启动则填写
+    # maxTokens: 32000                  # 单请求输出上限
+    # defaultContextWindow: 200000      # 未在目录中标明容量的模型使用
+    # discovery: true                   # 实时拉取代理的 /v1/models（30s 缓存）
+    # models: [...]                     # 静态目录（代理不可达时的兜底）
+```
+
+模型列表默认取插件内置目录；代理可达时改为实时拉取 `/v1/models`（支持
+`{"models": [...]}` / `{"data": [...]}` 两种返回），未列出的模型 id 仍可原样
+传递。
+
+---
+
+## 排错
+
+| 现象 | 可能原因 / 解决 |
+|---|---|
+| 右下角没有胶囊 | `dsh web` 没重启加载新 bundle → 重启 `dsh web`；或 `curl /plugins/dsh-llm-workbuddy/client.js` 应返回 200 |
+| 胶囊一直 `…`（加载中） | `GET /api/workbuddy/status` 失败 → 确认 `dsh web` 在跑、端口正确 |
+| 胶囊红 + `代理未运行` | `start-workbuddy.sh` 没起或挂了 → 启动代理后再看 |
+| 点「登录」没反应 / 按钮灰 | `loginScriptAvailable:false` → `login_workbuddy.py` 或 `.tools/uv` 不在仓库根；检查路径 |
+| 新标签页打开后登录完成，胶囊仍是红 | 会话文件 `.workbuddy/session.json` 未刷新或 `expiresAt` 已过期 → 刷新页面或重跑登录 |
+| 启动 `dsh web` 报 `EPERM ... cordis.yml` | `.dsh` 所在系统卷受保护（`/System/Volumes/Data` 带 `protect`）。解决：`sudo chown -R $(whoami) /Users/jiyunyang/.dsh`，或 `export DSH_HOME=$HOME/dsh-home` 后重新 `dsh plugin --profile web add` 并把插件链接进新 home |
+| 模型请求 `TRANSPORT` 错误 | 代理未运行或端口不对（连接被拒绝） |
+
+---
+
+## 限制
+
+- 当前为纯文本适配器：图片输入会以 `UNSUPPORTED_CONTENT` 拒绝（后续可加）。
+- 不公布 reasoning effort 选择器；模型按平台默认强度运行。
+- 代理未运行时，模型请求会以 `TRANSPORT` 错误快速失败（连接被拒绝）；但状态
+  小组件本身不依赖代理——代理挂了它仍能显示「代理未运行」并允许触发登录。
+- 登录态有效期由 WorkBuddy 云端决定；过期后胶囊变红，重新点「登录」即可，
+  代理无需重启。
+
+---
+
+## 文件索引
+
+| 路径 | 作用 |
+|---|---|
+| `lib/index.js` | Cordis 插件主体：LLM 适配器 `WorkBuddyAdapter` + `/api/workbuddy/*` 路由注册 |
+| `lib/client.js` | 零依赖浏览器小部件（状态胶囊 + 登录流程），被 `dsh.client` 注入 |
+| `cordis.patch.yml` | 本包的 Cordis bundle 挂载声明（`id: llm-workbuddy`） |
+| `package.json` | 包元数据、`dsh.client` 浏览器入口声明、`llm-workbuddy` peer 依赖 |
+| `../login_workbuddy.py` | 设备流登录脚本（被后端路由 spawn） |
+| `../start-workbuddy.sh` | 启动 workbuddy2api 代理 |
+| `../.workbuddy/session.json` | 登录会话文件（胶囊与适配器共读） |

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# dsh-llm-workbuddy bundle patch
+#
+# This file is the `dsh.bundle.patch` layer of the package: it mounts the
+# plugin row into the profile. Installing through the official CLI —
+#
+#   dsh plugin --profile web add dsh-llm-workbuddy
+#
+# — reconciles `dsh.profile.bundles` against installed packages and, seeing
+# this declaration, appends `dsh-llm-workbuddy` to the bundle stack.
+- insert:
+    - id: llm-workbuddy
+      name: 'dsh-llm-workbuddy'

package/lib/client.js

@@ -0,0 +1,156 @@
+/**
+ * dsh-llm-workbuddy — 浏览器端（客户端）插件
+ *
+ * DSH 会把一个声明了 `dsh.client`（platform: web）的包视作 client-module：
+ * 它把本文件编译/服务为 /plugins/dsh-llm-workbuddy/client.js 并以 classic
+ * script 注入。client-modules 加载器（@deepseek-ai/dsh-client-modules）要求
+ * 这种 bundle 在脚本执行时只做一件事——调用
+ * `window.__ModuleLoader__.load({ id, factory })` 注册自己（工厂是惰性的，
+ * 不能执行副作用）。之后加载器会物化 factory，并调用其返回模块面的
+ * `apply(ctx)` 来激活这个客户端插件。
+ *
+ * 因此这里用一个标准的 Cordis 客户端插件面（{ name, apply }）作为模块内容，
+ * 最后用 __ModuleLoader__.load 把它注册给加载器——这是「无构建、零依赖」
+ * 环境下最贴近官方 defineClient 产物的一种写法（官方构建产物本质上也是
+ * 把 { name, apply } 包进 load 注册）。
+ */
+window.__ModuleLoader__.load({
+  id: "dsh-llm-workbuddy",
+  factory: function () {
+    "use strict";
+
+    return {
+      /** 与服务器端插件同名，便于在浏览器端 Cordis 中辨识。 */
+      name: "llm-workbuddy",
+
+      /**
+       * 客户端插件入口。DSH 在浏览器端激活本插件时调用。
+       *
+       * 负责在 Web GUI 右下角注入一个常驻状态小圆点：轮询
+       * GET /api/workbuddy/status 显示绿/红登录态；点击「登录」会调用
+       * POST /api/workbuddy/login，打开返回的 device-flow authUrl，并持续
+       * 轮询直到会话 authenticated。
+       */
+      apply: function () {
+        startWidget();
+      },
+    };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Widget 实现
+// ---------------------------------------------------------------------------
+
+var POLL_MS = 5000;
+var LOGIN_POLL_MS = 2000;
+var LOGIN_POLLS = 30;
+
+/** 插件激活后、DOM 就绪时开始挂载 widget。 */
+function startWidget() {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", runWidget, { once: true });
+  } else {
+    runWidget();
+  }
+}
+
+/** 真正的 widget 逻辑：注入样式、渲染状态条、轮询、登录。 */
+function runWidget() {
+  var host = document.createElement("div");
+  host.id = "wb-status-host";
+  host.style.cssText =
+    "position:fixed;right:12px;bottom:12px;z-index:2147483647;" +
+    "font:12px/1.4 system-ui,-apple-system,sans-serif;";
+
+  var style = document.createElement("style");
+  style.textContent =
+    ".wb-pill{display:flex;align-items:center;gap:6px;padding:6px 10px;border-radius:999px;" +
+    "background:#111827;color:#e5e7eb;box-shadow:0 2px 8px rgba(0,0,0,.35);}" +
+    ".wb-dot{width:8px;height:8px;border-radius:50%;background:#9ca3af;}" +
+    ".wb-pill--ok .wb-dot{background:#22c55e;}" +
+    ".wb-pill--bad .wb-dot{background:#ef4444;}" +
+    ".wb-btn{margin-left:4px;border:0;border-radius:6px;background:#2563eb;color:#fff;" +
+    "padding:3px 8px;cursor:pointer;font:inherit;}" +
+    ".wb-btn:disabled{opacity:.6;cursor:default;}" +
+    ".wb-warn{margin-left:6px;color:#f59e0b;font-size:11px;}";
+  document.head.appendChild(style);
+  document.body.appendChild(host);
+
+  var status = null;
+  var busy = false;
+  var timer = null;
+
+  function fmtExpiry(expiresAt) {
+    if (!expiresAt) return "";
+    try { return new Date(expiresAt).toLocaleString(); }
+    catch (e) { return ""; }
+  }
+
+  function render() {
+    if (!status) {
+      host.innerHTML = '<div class="wb-pill wb-pill--bad">WorkBuddy · …</div>';
+      return;
+    }
+    var ok = status.authenticated && status.proxyUp;
+    var label = ok
+      ? "WorkBuddy · " + (status.account && (status.account.nickname || status.account.uid) || "已登录")
+      : "WorkBuddy · 未登录";
+    var html =
+      '<div class="wb-pill ' + (ok ? "wb-pill--ok" : "wb-pill--bad") + '">' +
+      '<span class="wb-dot"></span>' +
+      '<span class="wb-label">' + label + "</span>";
+    if (!ok) {
+      var disabled = busy || !status.loginScriptAvailable ? " disabled" : "";
+      html += '<button class="wb-btn" id="wb-login"' + disabled + ">" +
+        (busy ? "登录中…" : "登录") + "</button>";
+    }
+    if (!status.proxyUp) html += '<span class="wb-warn">代理未运行</span>';
+    html += "</div>";
+    host.innerHTML = html;
+    var btn = host.querySelector("#wb-login");
+    if (btn) btn.addEventListener("click", onLogin);
+  }
+
+  function refresh() {
+    return fetch("/api/workbuddy/status")
+      .then(function (r) { return r.ok ? r.json() : null; })
+      .then(function (data) {
+        if (data) { status = data; render(); }
+      })
+      .catch(function () { /* leave last known state on screen */ });
+  }
+
+  function onLogin() {
+    if (busy) return;
+    busy = true;
+    render();
+    fetch("/api/workbuddy/login", { method: "POST" })
+      .then(function (r) { return r.json(); })
+      .then(function (data) {
+        if (data && data.authUrl) {
+          window.open(data.authUrl, "_blank", "noopener,noreferrer");
+        }
+        var i = 0;
+        var tick = function () {
+          refresh().then(function () {
+            if ((status && status.authenticated) || i >= LOGIN_POLLS) {
+              busy = false;
+              render();
+              return;
+            }
+            i++;
+            setTimeout(tick, LOGIN_POLL_MS);
+          });
+        };
+        tick();
+      })
+      .catch(function () {
+        busy = false;
+        render();
+      });
+  }
+
+  refresh();
+  timer = setInterval(refresh, POLL_MS);
+}

package/lib/index.js

@@ -0,0 +1,835 @@
+/**
+ * dsh-llm-workbuddy
+ *
+ * WorkBuddy LLM provider adapter for DeepSeek Harness.
+ *
+ * Routes the `workbuddy` provider to the local workbuddy2api proxy
+ * (https://github.com/hawklithm/workbuddy2api), which converts CodeBuddy /
+ * WorkBuddy's proprietary protocol into standard OpenAI chat completions.
+ *
+ * The proxy authenticates with the locally stored CodeBuddy/WorkBuddy login
+ * session, so this adapter needs no API key: every request is sent without an
+ * `Authorization` header unless one is explicitly configured.
+ *
+ * The adapter is a plain fetch + SSE implementation over the OpenAI-compatible
+ * wire format; it emits the harness `StreamChunk` protocol. Model discovery
+ * queries the proxy's `/v1/models` endpoint (cached, short TTL) and falls back
+ * to a shipped static catalog when the proxy is not running.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import z from "@deepseek-ai/schemastery";
+import {
+  CONTEXT_WINDOW_EXCEEDED_CODE,
+  CallId,
+  EMPTY_RESPONSE_CODE,
+  LlmAdapter,
+  LlmError,
+  ProviderRequestId,
+  QUOTA_EXCEEDED_CODE,
+  attributionHeaders,
+  isContextWindowExceededError,
+  isQuotaExceededError,
+} from "@deepseek-ai/dsh-llm";
+import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
+import { MAX_TIMER_DELAY_MS, idleWatchdog, timeoutOf } from "@deepseek-ai/dsh-timeout";
+
+/** Plugin identity (Cordis convention). */
+export const name = "llm-workbuddy";
+export const inject = ["llm", "webServer"];
+
+/** The single provider route this plugin owns. */
+export const PROVIDER = "workbuddy";
+
+/** Settings namespace for the optional `llm-workbuddy:` user-settings section. */
+const NS = settingsNamespace("llm-workbuddy");
+
+/** Default local workbuddy2api proxy endpoint. */
+export const DEFAULT_BASE_URL = "http://127.0.0.1:8787/v1";
+
+/** Default maximum idle interval while an adapter stream read is outstanding. */
+const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000;
+const STREAM_IDLE_TIMEOUT_CODE = "LLM_STREAM_IDLE_TIMEOUT";
+
+/** Default combined request/response context capacity. */
+const DEFAULT_CONTEXT_WINDOW = 200_000;
+/** Default per-request output-token cap. */
+const DEFAULT_MAX_TOKENS = 32_000;
+
+/** Live `/v1/models` discovery cache window and request timeout. */
+const DISCOVERY_TTL_MS = 30_000;
+const DISCOVERY_TIMEOUT_MS = 2_000;
+
+/**
+ * Static catalog shipped with the plugin — the conversational models of the
+ * CodeBuddy/WorkBuddy platform (from workbuddy2api's models_config.json).
+ * It is advisory and replaced by the live `/v1/models` answer whenever the
+ * proxy is reachable; entries not announced by the proxy are still listed.
+ */
+const DEFAULT_MODELS = [
+  { id: "deepseek-v4-pro", name: "Deepseek-V4-Pro", contextWindow: 1_000_000, maxTokens: 50_000, inputModalities: ["text", "image"] },
+  { id: "deepseek-v4-flash", name: "Deepseek-V4-Flash", contextWindow: 1_000_000, maxTokens: 50_000, inputModalities: ["text", "image"] },
+  { id: "glm-5.2", name: "GLM-5.2", contextWindow: 1_000_000, maxTokens: 48_000, inputModalities: ["text", "image"] },
+  { id: "glm-5.1", name: "GLM-5.1", contextWindow: 200_000, maxTokens: 48_000 },
+  { id: "glm-5.0", name: "GLM-5.0", contextWindow: 200_000, maxTokens: 48_000 },
+  { id: "glm-4.7", name: "GLM-4.7", contextWindow: 200_000, maxTokens: 48_000 },
+  { id: "glm-4.6", name: "GLM-4.6", contextWindow: 168_000, maxTokens: 32_000 },
+  { id: "glm-5v-turbo", name: "GLM-5v-Turbo", contextWindow: 200_000, maxTokens: 64_000, inputModalities: ["text", "image"] },
+  { id: "kimi-k3-1", name: "Kimi-K3", contextWindow: 1_000_000, maxTokens: 32_000, inputModalities: ["text", "image"] },
+  { id: "kimi-k2.7", name: "Kimi-K2.7-Code", contextWindow: 256_000, maxTokens: 32_000, inputModalities: ["text", "image"] },
+  { id: "kimi-k2.6", name: "Kimi-K2.6", contextWindow: 256_000, maxTokens: 32_000, inputModalities: ["text", "image"] },
+  { id: "kimi-k2.5", name: "Kimi-K2.5", contextWindow: 164_000, maxTokens: 32_000, inputModalities: ["text", "image"] },
+  { id: "kimi-k2-thinking", name: "Kimi-K2-Thinking", contextWindow: 164_000, maxTokens: 32_000 },
+  { id: "minimax-m3", name: "MiniMax-M3", contextWindow: 512_000, maxTokens: 128_000, inputModalities: ["text", "image"] },
+  { id: "minimax-m2.5", name: "MiniMax-M2.5", contextWindow: 200_000, maxTokens: 48_000 },
+  { id: "hy3", name: "Hy3", contextWindow: 192_000, maxTokens: 64_000, inputModalities: ["text", "image"] },
+  { id: "hunyuan-2.0-thinking", name: "Hunyuan-2.0-Thinking", contextWindow: 128_000, maxTokens: 24_000 },
+  { id: "hunyuan-chat", name: "Hunyuan-Turbos", contextWindow: 200_000, maxTokens: 8_192 },
+  { id: "auto", name: "Auto", contextWindow: 168_000, maxTokens: 32_000, inputModalities: ["text", "image"] },
+  { id: "default", name: "Default", contextWindow: 200_000, maxTokens: 24_000 },
+];
+
+// #region serialize
+
+/** Join the text blocks of a message (used for user/tool-result content). */
+function flattenText(blocks) {
+  return blocks.filter((block) => block.type === "text").map((block) => block.text).join("");
+}
+
+/** Serialize one assistant message (text + tool calls). */
+function serializeAssistant(message) {
+  const text = flattenText(message.content);
+  const toolCalls = message.content.filter((block) => block.type === "tool-call").map((block) => ({
+    id: block.id,
+    type: "function",
+    function: { name: block.name, arguments: block.arguments },
+  }));
+  return {
+    role: "assistant",
+    content: text,
+    ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+  };
+}
+
+/**
+ * Serialize the harness conversation into OpenAI chat-completions wire
+ * messages. `tool-result` blocks become standalone `{role: 'tool'}` messages;
+ * image content is rejected (the initial version is text-only).
+ */
+function serializeMessages(messages) {
+  const wire = [];
+  for (const message of messages) {
+    if (message.content.some((block) => block.type === "image")) {
+      throw new LlmError("The WorkBuddy adapter does not support image content yet.", "UNSUPPORTED_CONTENT");
+    }
+    if (message.role === "system") {
+      wire.push({ role: "system", content: flattenText(message.content) });
+      continue;
+    }
+    if (message.role === "assistant") {
+      wire.push(serializeAssistant(message));
+      continue;
+    }
+    const toolResults = message.content.filter((block) => block.type === "tool-result");
+    const text = flattenText(message.content);
+    if (text.length > 0 || toolResults.length === 0) wire.push({ role: "user", content: text });
+    for (const result of toolResults) {
+      wire.push({ role: "tool", tool_call_id: result.toolCallId, content: flattenText(result.content) || "(no output)" });
+    }
+  }
+  return wire;
+}
+
+/** Build the full wire request. Always streaming with usage reporting on. */
+function serializeRequest(options) {
+  const messages = [];
+  if (options.system !== undefined) messages.push({ role: "system", content: options.system });
+  messages.push(...serializeMessages(options.messages));
+  const tools = options.tools?.map((tool) => ({
+    type: "function",
+    function: { name: tool.name, description: tool.description, parameters: tool.parameters },
+  }));
+  return {
+    model: options.model,
+    messages,
+    stream: true,
+    stream_options: { include_usage: true },
+    ...(tools !== undefined && tools.length > 0 ? { tools } : {}),
+    ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+    ...(options.maxTokens === undefined ? {} : { max_tokens: options.maxTokens }),
+    ...(options.stop !== undefined ? { stop: options.stop } : {}),
+  };
+}
+
+// #endregion
+
+// #region sse
+
+/**
+ * Parse one SSE event block (lines separated by \n, fields `field: value`).
+ * Returns the joined `data` payload, or `undefined` when the event carries no
+ * data field. Comment lines (starting with `:`) are transport activity.
+ */
+function parseEvent(raw) {
+  let data;
+  for (const line of raw.split("\n")) {
+    if (line.startsWith(":")) continue;
+    if (line.startsWith("data:")) {
+      const value = line.slice(5).replace(/^ /, "");
+      data = data === undefined ? value : `${data}\n${value}`;
+    }
+  }
+  return data;
+}
+
+/**
+ * Parse an SSE byte stream into data payloads. Yields `[DONE]` as the final
+ * value and returns; throws `LlmError('STREAM_CLOSED')` when the stream ends
+ * without it (truncated response — the model call cannot be trusted).
+ */
+async function* parseSse(stream, onComment) {
+  const decoder = new TextDecoder();
+  const reader = stream.getReader();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
+      let sep;
+      while ((sep = buffer.indexOf("\n\n")) !== -1) {
+        const raw = buffer.slice(0, sep);
+        buffer = buffer.slice(sep + 2);
+        const data = parseEvent(raw);
+        if (data !== undefined) {
+          if (onComment !== undefined) onComment();
+          yield data;
+          if (data === "[DONE]") return;
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  throw new LlmError("WorkBuddy SSE stream ended without [DONE]", "STREAM_CLOSED");
+}
+
+// #endregion
+
+// #region translate
+
+/** Map the wire finish_reason vocabulary to the harness FinishReason. */
+function mapFinishReason(reason) {
+  switch (reason) {
+    case "stop": return { kind: "stop" };
+    case "tool_calls": return { kind: "tool-calls" };
+    case "length": return { kind: "max-tokens" };
+    default: return {
+      kind: "error",
+      failure: { message: `model stopped: ${reason}`, code: reason.toUpperCase() },
+    };
+  }
+}
+
+/**
+ * Map wire usage fields to the harness DISJOINT TokenUsage convention
+ * (cache reads are subtracted out of `inputTokens`).
+ */
+function mapUsage(usage) {
+  const cacheRead = usage.prompt_tokens_details?.cached_tokens ?? usage.prompt_cache_hit_tokens;
+  const reasoning = usage.completion_tokens_details?.reasoning_tokens;
+  return {
+    inputTokens: usage.prompt_tokens - (cacheRead ?? 0),
+    outputTokens: usage.completion_tokens,
+    ...(cacheRead !== undefined ? { cacheReadTokens: cacheRead } : {}),
+    ...(reasoning !== undefined ? { reasoningTokens: reasoning } : {}),
+  };
+}
+
+/** Assemble the final ContentBlock for one open block. */
+function closeBlock(block) {
+  switch (block.kind) {
+    case "text": return { type: "text", text: block.text };
+    case "reasoning": return { type: "reasoning", text: block.text };
+    case "tool-call": return {
+      type: "tool-call",
+      id: CallId(block.callId ?? ""),
+      name: block.name ?? "",
+      arguments: block.text,
+    };
+  }
+}
+
+/**
+ * Consume SSE data payloads (ending with `[DONE]`) and yield StreamChunks.
+ * Handles standard OpenAI streaming: `delta.content`, `delta.reasoning_content`
+ * (DeepSeek-style thinking, surfaced by the proxy's DSML parsing) and
+ * `delta.tool_calls` keyed by `call.index`. `block-end`s, `usage`, and
+ * `finish` are all deferred to the `[DONE]` sentinel.
+ */
+async function* translate(payloads) {
+  let nextIndex = 0;
+  let textBlock;
+  let reasoningBlock;
+  const toolBlocks = new Map();
+  const order = [];
+  let pendingFinish;
+  let pendingUsage;
+
+  function open(kind) {
+    const block = { index: nextIndex++, kind, text: "" };
+    order.push(block);
+    return block;
+  }
+
+  for await (const payload of payloads) {
+    if (payload === "[DONE]") {
+      for (const block of order) yield { type: "block-end", index: block.index, block: closeBlock(block) };
+      if (pendingUsage) yield { type: "usage", usage: pendingUsage };
+      const reason = pendingFinish ?? { kind: "stop" };
+      yield {
+        type: "finish",
+        reason: reason.kind === "stop" && order.length === 0
+          ? { kind: "error", failure: { message: "model returned a completed response with no content", code: EMPTY_RESPONSE_CODE } }
+          : reason,
+      };
+      return;
+    }
+    let chunk;
+    try {
+      chunk = JSON.parse(payload);
+    } catch {
+      throw new LlmError(`malformed SSE payload: ${payload.slice(0, 120)}`, "MALFORMED_RESPONSE");
+    }
+    for (const choice of chunk.choices ?? []) {
+      const delta = choice.delta;
+      const reasoning = delta?.reasoning_content;
+      if (typeof reasoning === "string" && reasoning.length > 0) {
+        if (!reasoningBlock) {
+          reasoningBlock = open("reasoning");
+          yield { type: "block-start", index: reasoningBlock.index, blockType: "reasoning" };
+        }
+        reasoningBlock.text += reasoning;
+        yield { type: "reasoning-delta", index: reasoningBlock.index, text: reasoning };
+      }
+      const content = delta?.content;
+      if (typeof content === "string" && content.length > 0) {
+        if (!textBlock) {
+          textBlock = open("text");
+          yield { type: "block-start", index: textBlock.index, blockType: "text" };
+        }
+        textBlock.text += content;
+        yield { type: "text-delta", index: textBlock.index, text: content };
+      }
+      for (const call of delta?.tool_calls ?? []) {
+        let block = toolBlocks.get(call.index);
+        if (!block) {
+          block = open("tool-call");
+          toolBlocks.set(call.index, block);
+          yield { type: "block-start", index: block.index, blockType: "tool-call" };
+        }
+        // The CodeBuddy upstream repeats `function.name: ""` (and omits `id`)
+        // on every argument chunk after the first. Treat empty strings as
+        // absent so the first captured id/name is never clobbered.
+        if (typeof call.id === "string" && call.id.length > 0) block.callId = call.id;
+        const toolName = call.function?.name;
+        if (typeof toolName === "string" && toolName.length > 0) block.name = toolName;
+        const fragment = call.function?.arguments ?? "";
+        block.text += fragment;
+        yield {
+          type: "tool-call-delta",
+          index: block.index,
+          id: CallId(block.callId ?? ""),
+          ...(block.name !== undefined ? { name: block.name } : {}),
+          argumentsDelta: fragment,
+        };
+      }
+      if (typeof choice.finish_reason === "string") pendingFinish = mapFinishReason(choice.finish_reason);
+    }
+    if (chunk.usage) pendingUsage = mapUsage(chunk.usage);
+  }
+  throw new LlmError("WorkBuddy SSE payload stream ended without [DONE]", "STREAM_CLOSED");
+}
+
+// #endregion
+
+// #region adapter
+
+/** Display metadata for one catalog entry. */
+function modelInfo(provider, model) {
+  return {
+    provider,
+    id: model.id,
+    name: model.name ?? model.id,
+    ...(model.description === undefined ? {} : { description: model.description }),
+    inputModalities: model.inputModalities ?? ["text"],
+  };
+}
+
+/** Normalize a Retry-After header into milliseconds, when valid. */
+function providerRetryAfterMs(value) {
+  if (value === null) return undefined;
+  if (/^\d+$/.test(value)) {
+    const delay = Number(value) * 1000;
+    return Number.isFinite(delay) && delay > 0 ? delay : undefined;
+  }
+  const delay = Date.parse(value) - Date.now();
+  return Number.isFinite(delay) && delay > 0 ? delay : undefined;
+}
+
+/** Opaque provider request id from response headers, when present. */
+function requestId(headers) {
+  const value = headers.get("x-request-id") ?? headers.get("x-deepseek-request-id");
+  return value === null || value.length === 0 ? undefined : ProviderRequestId(value);
+}
+
+/** Map an HTTP status plus provider error detail to a stable LlmError code. */
+function httpErrorCode(status, error) {
+  if (status === 401 || status === 403) return "AUTH";
+  if (status === 413) return "INVALID_REQUEST";
+  const detail = [error?.code, error?.type, error?.message].filter(Boolean).join(" ");
+  if (isQuotaExceededError(detail)) return QUOTA_EXCEEDED_CODE;
+  if (status === 429) return "RATE_LIMIT";
+  if (status === 400) {
+    if (isContextWindowExceededError(detail)) return CONTEXT_WINDOW_EXCEEDED_CODE;
+    return "INVALID_REQUEST";
+  }
+  if (status >= 500) return "SERVER";
+  return `HTTP_${status}`;
+}
+
+/**
+ * The WorkBuddy adapter: fetch + SSE against the OpenAI-compatible
+ * workbuddy2api proxy, emitting harness StreamChunks. Connection facts arrive
+ * through a thunk resolved once per operation, so the registering plugin owns
+ * validation and layering.
+ */
+export class WorkBuddyAdapter extends LlmAdapter {
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+
+  providerInfo(provider) {
+    return { id: provider, name: "WorkBuddy" };
+  }
+
+  async listModels(provider) {
+    const connection = this.config.options();
+    if (!connection.discovery) return connection.models.map((model) => modelInfo(provider, model));
+    try {
+      const cached = this._cache;
+      const now = Date.now();
+      if (cached !== undefined && now - cached.at < DISCOVERY_TTL_MS) return cached.models;
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), DISCOVERY_TIMEOUT_MS);
+      let payload;
+      try {
+        const response = await fetch(`${connection.baseURL}/models`, { signal: controller.signal });
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        payload = await response.json();
+      } finally {
+        clearTimeout(timer);
+      }
+      const byId = new Map(connection.models.map((model) => [model.id, model]));
+      // The workbuddy2api proxy answers `{"models": [...]}` with `display_name`
+      // fields; plain OpenAI endpoints answer `{"data": [...]}` with `name`.
+      const list = payload?.data ?? payload?.models ?? [];
+      const live = list
+        .map((entry) => ({
+          id: String(entry.id),
+          name: typeof entry.name === "string"
+            ? entry.name
+            : typeof entry.display_name === "string"
+              ? entry.display_name
+              : undefined,
+        }))
+        .filter((entry) => entry.id.length > 0);
+      const merged = [];
+      const seen = new Set();
+      for (const entry of live) {
+        if (seen.has(entry.id)) continue;
+        seen.add(entry.id);
+        const catalog = byId.get(entry.id);
+        merged.push({
+          provider,
+          id: entry.id,
+          name: entry.name ?? catalog?.name ?? entry.id,
+          ...(catalog?.description !== undefined ? { description: catalog.description } : {}),
+          inputModalities: catalog?.inputModalities ?? ["text"],
+        });
+      }
+      // Catalog entries the proxy did not announce (e.g. unauthenticated or
+      // partial listing) stay selectable.
+      for (const model of connection.models) {
+        if (seen.has(model.id)) continue;
+        merged.push(modelInfo(provider, model));
+      }
+      const result = merged.length > 0 ? merged : connection.models.map((model) => modelInfo(provider, model));
+      this._cache = { at: now, models: result };
+      return result;
+    } catch {
+      return connection.models.map((model) => modelInfo(provider, model));
+    }
+  }
+
+  resolveModel(provider, model, _signal) {
+    const connection = this.config.options();
+    const configured = connection.models.find((entry) => entry.id === model);
+    return Promise.resolve({
+      ...(configured === undefined
+        ? { provider, id: model, name: model, inputModalities: ["text"] }
+        : modelInfo(provider, configured)),
+      context: { contextWindow: configured?.contextWindow ?? connection.defaultContextWindow },
+      defaultMaxTokens: configured?.maxTokens ?? connection.maxTokens,
+    });
+  }
+
+  async *stream(options) {
+    const connection = this.config.options();
+    const consumer = new AbortController();
+    const watchdog = idleWatchdog(
+      options.signal === undefined ? consumer.signal : AbortSignal.any([options.signal, consumer.signal]),
+      connection.streamIdleTimeoutMs,
+      STREAM_IDLE_TIMEOUT_CODE,
+    );
+    const iterator = this.request(options, watchdog.signal, connection, () => watchdog.pulse())[Symbol.asyncIterator]();
+    let exhausted = false;
+    try {
+      while (true) {
+        const result = await watchdog.next(iterator);
+        if (result.done) {
+          exhausted = true;
+          return;
+        }
+        yield result.value;
+      }
+    } catch (error) {
+      if (timeoutOf(watchdog.signal, STREAM_IDLE_TIMEOUT_CODE) !== undefined) {
+        throw new LlmError(`WorkBuddy stream idle timeout after ${connection.streamIdleTimeoutMs}ms`, "TIMEOUT", { cause: error });
+      }
+      if (options.signal?.aborted) throw new LlmError("WorkBuddy request aborted by caller", "ABORTED", { cause: error });
+      if (error instanceof LlmError) throw error;
+      throw new LlmError(`WorkBuddy proxy stream from ${connection.baseURL} failed`, "TRANSPORT", { cause: error });
+    } finally {
+      consumer.abort("WorkBuddy stream consumer stopped");
+      if (!exhausted && iterator.return !== undefined) {
+        try {
+          await iterator.return();
+        } catch (_abortedTransportTeardown) {
+          // transport teardown after abort is expected
+        }
+      }
+    }
+  }
+
+  async *request(options, signal, connection, onComment) {
+    const body = serializeRequest(options);
+    const headers = {
+      "content-type": "application/json",
+      "accept": "text/event-stream",
+      ...attributionHeaders(),
+      ...(connection.apiKey !== undefined && connection.apiKey.length > 0
+        ? { authorization: `Bearer ${connection.apiKey}` }
+        : {}),
+    };
+    let response;
+    try {
+      response = await fetch(`${connection.baseURL}/chat/completions`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal,
+      });
+    } catch (error) {
+      if (signal.aborted) throw error;
+      throw new LlmError(`WorkBuddy proxy request to ${connection.baseURL} failed`, "TRANSPORT", { cause: error });
+    }
+    if (!response.ok) {
+      let message = `WorkBuddy proxy error (HTTP ${response.status})`;
+      let providerError;
+      try {
+        providerError = (await response.json()).error;
+        if (providerError?.message) message = providerError.message;
+      } catch {
+        // non-JSON error body; keep the generic message
+      }
+      const delay = providerRetryAfterMs(response.headers.get("retry-after"));
+      const id = requestId(response.headers);
+      throw new LlmError(message, httpErrorCode(response.status, providerError), {
+        status: response.status,
+        ...(delay === undefined ? {} : { providerRetryAfterMs: delay }),
+        ...(id === undefined ? {} : { requestId: id }),
+      });
+    }
+    if (!response.body) throw new LlmError("WorkBuddy proxy returned no response body", "EMPTY_RESPONSE");
+    yield* translate(parseSse(response.body, onComment));
+  }
+}
+
+// #endregion
+
+// #region config
+
+const MODEL_MODALITIES = ["text", "image"];
+
+const catalogModel = z.object({
+  id: z.string().required(),
+  name: z.string(),
+  description: z.string(),
+  contextWindow: z.number().step(1).min(1),
+  maxTokens: z.number().step(1).min(1),
+  inputModalities: z.array(z.union(MODEL_MODALITIES)).min(1).default(["text"]),
+});
+
+export const Config = z.object({
+  baseURL: z.string().default(DEFAULT_BASE_URL),
+  apiKey: z.string(),
+  maxTokens: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_TOKENS),
+  defaultContextWindow: z.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW),
+  models: z.array(catalogModel).default(DEFAULT_MODELS),
+  streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+  discovery: z.boolean().default(true),
+});
+
+/** Resolve, validate, and detach the advisory model catalog. */
+function resolveModels(models) {
+  const seen = new Set();
+  return (models ?? DEFAULT_MODELS).map((model) => {
+    if (model.id.length === 0) throw new Error("dsh-llm-workbuddy: catalog model ids must be non-empty");
+    if (model.name !== undefined && model.name.length === 0) throw new Error(`dsh-llm-workbuddy: catalog model "${model.id}" has an empty name`);
+    if (model.contextWindow !== undefined && (!Number.isInteger(model.contextWindow) || model.contextWindow <= 0)) {
+      throw new Error(`dsh-llm-workbuddy: catalog model "${model.id}" contextWindow must be a positive integer`);
+    }
+    if (model.maxTokens !== undefined && (!Number.isInteger(model.maxTokens) || model.maxTokens <= 0)) {
+      throw new Error(`dsh-llm-workbuddy: catalog model "${model.id}" maxTokens must be a positive integer`);
+    }
+    const inputModalities = model.inputModalities ?? ["text"];
+    if (inputModalities.length === 0) throw new Error(`dsh-llm-workbuddy: catalog model "${model.id}" inputModalities must not be empty`);
+    if (inputModalities.some((modality) => !MODEL_MODALITIES.includes(modality))) {
+      throw new Error(`dsh-llm-workbuddy: catalog model "${model.id}" inputModalities must contain only "text" and "image"`);
+    }
+    if (new Set(inputModalities).size !== inputModalities.length) {
+      throw new Error(`dsh-llm-workbuddy: catalog model "${model.id}" inputModalities must not contain duplicates`);
+    }
+    if (seen.has(model.id)) throw new Error(`dsh-llm-workbuddy: duplicate catalog model "${model.id}"`);
+    seen.add(model.id);
+    return {
+      id: model.id,
+      ...(model.name === undefined ? {} : { name: model.name }),
+      ...(model.description === undefined ? {} : { description: model.description }),
+      ...(model.contextWindow === undefined ? {} : { contextWindow: model.contextWindow }),
+      ...(model.maxTokens === undefined ? {} : { maxTokens: model.maxTokens }),
+      inputModalities: [...inputModalities],
+    };
+  });
+}
+
+/**
+ * The one explicit resolve step from raw config to validated connection
+ * facts. Judged at load (fail loud) and for each settings snapshot.
+ */
+export function resolveAdapterOptions(config) {
+  const baseURL = config.baseURL ?? DEFAULT_BASE_URL;
+  if (typeof baseURL !== "string" || baseURL.length === 0) throw new Error("dsh-llm-workbuddy: baseURL must be a non-empty string");
+  if (config.defaultContextWindow !== undefined && (!Number.isInteger(config.defaultContextWindow) || config.defaultContextWindow <= 0)) {
+    throw new Error("dsh-llm-workbuddy: defaultContextWindow must be a positive integer");
+  }
+  if (config.maxTokens !== undefined && (!Number.isSafeInteger(config.maxTokens) || config.maxTokens <= 0)) {
+    throw new Error("dsh-llm-workbuddy: maxTokens must be a positive safe integer");
+  }
+  const streamIdleTimeoutMs = config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+  if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0 || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(`dsh-llm-workbuddy: streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+  }
+  return {
+    baseURL,
+    apiKey: config.apiKey,
+    maxTokens: config.maxTokens ?? DEFAULT_MAX_TOKENS,
+    defaultContextWindow: config.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW,
+    models: resolveModels(config.models),
+    streamIdleTimeoutMs,
+    discovery: config.discovery ?? true,
+  };
+}
+
+// #endregion
+
+// #region login status web API
+
+/** Resolve the repo root that holds `login_workbuddy.py` and `.workbuddy/`. */
+const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url));
+// dsh-llm-workbuddy/lib/index.js -> dsh-workbuddy/ (two levels up).
+const REPO_ROOT = resolve(PLUGIN_DIR, "..", "..");
+const SESSION_FILE = resolve(REPO_ROOT, ".workbuddy", "session.json");
+const LOGIN_SCRIPT = resolve(REPO_ROOT, "login_workbuddy.py");
+const WORKBUDDY_UV = resolve(REPO_ROOT, ".tools", "uv");
+
+/**
+ * Read the local WorkBuddy session file and derive its validity. Returns a
+ * normalized status object the Web widget polls. Never throws — missing or
+ * malformed state is reported as `authenticated: false` so the UI can prompt.
+ */
+function readSessionStatus() {
+  if (!existsSync(SESSION_FILE)) {
+    return { sessionFile: false, authenticated: false, expiresAt: null, account: null };
+  }
+  try {
+    const raw = JSON.parse(readFileSync(SESSION_FILE, "utf-8"));
+    const expiresAt = raw?.auth?.expiresAt ?? null;
+    const now = Date.now();
+    const expired = expiresAt !== null && expiresAt <= now;
+    return {
+      sessionFile: true,
+      authenticated: !expired && Boolean(raw?.auth?.accessToken),
+      expiresAt,
+      account: raw?.account ?? null,
+    };
+  } catch {
+    return { sessionFile: true, authenticated: false, expiresAt: null, account: null };
+  }
+}
+
+/**
+ * Probe the local workbuddy2api proxy health endpoint. Returns
+ * `{ proxyUp, tokenValid }`; a missing/unreachable proxy is reported as
+ * `proxyUp: false` without throwing, so the widget can show a clear state.
+ */
+async function probeProxy(baseURL) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 2000);
+  try {
+    const response = await fetch(`${baseURL.replace(/\/v1\/?$/, "")}/health`, {
+      signal: controller.signal,
+    });
+    if (!response.ok) return { proxyUp: true, tokenValid: false };
+    const body = await response.json().catch(() => ({}));
+    return { proxyUp: true, tokenValid: Boolean(body?.authenticated ?? body?.token_valid) };
+  } catch {
+    return { proxyUp: false, tokenValid: false };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Register `GET /api/workbuddy/status` and `POST /api/workbuddy/login` on the
+ * DSH web server. The login route spawns `login_workbuddy.py`, parses the
+ * device-flow `authUrl` it prints to stdout, and returns it so the browser
+ * can open it in a new tab. The widget then polls `/status` until the session
+ * file appears and reports `authenticated: true`.
+ */
+function registerWorkbuddyRoutes(ctx) {
+  if (ctx.webServer === undefined) return; // headless profile: no HTTP surface
+  const baseURL = config_baseURL();
+  ctx.webServer.register({
+    path: "/api/workbuddy/status",
+    exact: true,
+    methods: ["GET"],
+    async handler(_req, res) {
+      const session = readSessionStatus();
+      const proxy = await probeProxy(baseURL);
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({
+        ...session,
+        ...proxy,
+        loginScriptAvailable: existsSync(LOGIN_SCRIPT),
+      }));
+    },
+  });
+  ctx.webServer.register({
+    path: "/api/workbuddy/login",
+    exact: true,
+    methods: ["POST"],
+    async handler(_req, res) {
+      if (!existsSync(LOGIN_SCRIPT)) {
+        res.writeHead(503, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: "login_workbuddy.py not found" }));
+        return;
+      }
+      // Existing session is fine; no need to re-run the flow.
+      const existing = readSessionStatus();
+      if (existing.authenticated) {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ alreadyLoggedIn: true, authUrl: null, ...existing }));
+        return;
+      }
+      const args = ["run", "--python", "3.12", "python", "-u", LOGIN_SCRIPT, "--session-file", SESSION_FILE];
+      const child = spawn(WORKBUDDY_UV, args, { cwd: REPO_ROOT, env: { ...process.env, UV_PYTHON_INSTALL_DIR: resolve(REPO_ROOT, ".tools", "uv-python"), UV_CACHE_DIR: resolve(REPO_ROOT, ".tools", "uv-cache"), PYTHONUNBUFFERED: "1" } });
+      let stdout = "";
+      let authUrl = null;
+      child.stdout.on("data", (chunk) => {
+        stdout += chunk.toString();
+        const m = stdout.match(/https?:\/\/\S+/);
+        if (m && authUrl === null) authUrl = m[0];
+      });
+      child.stderr.on("data", () => {});
+      // The device flow blocks until login or timeout; we hand back the URL
+      // immediately and let the widget poll /status for completion.
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ authUrl, pending: true }));
+    },
+  });
+}
+
+/** Lazily resolve the configured proxy base URL for the health probe. */
+let _baseURL = DEFAULT_BASE_URL;
+function config_baseURL() {
+  return _baseURL;
+}
+
+// #endregion
+
+// #region plugin
+
+/**
+ * Register a {@link WorkBuddyAdapter} for the `workbuddy` provider route on
+ * `ctx.llm`. Connection facts resolve per request instead of freezing at
+ * load: the plugin layers its `cordis.yml` entry config under the optional
+ * `llm-workbuddy` user-settings section (`ctx.settings`), so a changed base
+ * URL or catalog reaches the very next request without restarting anything.
+ */
+export function apply(ctx, config) {
+  _baseURL = resolveAdapterOptions(config).baseURL;
+  let current = () => config;
+  let lastRaw;
+  let lastGood;
+  const options = () => {
+    const raw = current();
+    if (raw === lastRaw && lastGood !== undefined) return lastGood;
+    try {
+      const next = resolveAdapterOptions(raw);
+      lastRaw = raw;
+      lastGood = next;
+      return next;
+    } catch (error) {
+      if (lastGood === undefined) throw error;
+      lastRaw = raw;
+      ctx.logger.error("dsh-llm-workbuddy: keeping the last good configuration after an invalid settings section");
+      ctx.logger.error(error);
+      return lastGood;
+    }
+  };
+  options();
+  const adapter = new WorkBuddyAdapter({ options });
+  ctx.llm.registerConfigurableProviders([{
+    provider: PROVIDER,
+    displayName: "WorkBuddy",
+    settingsNs: NS,
+    settingsPath: [],
+  }]);
+  ctx.llm.registerAdapter([PROVIDER], adapter);
+  registerWorkbuddyRoutes(ctx);
+  installSettingsSection(ctx, NS, Config, config, {
+    setSource: (source) => {
+      current = source;
+    },
+    onChange: () => {
+      // no registration-level facts are derived from the source; nothing to re-judge
+    },
+  });
+}
+
+// #endregion

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "dsh-llm-workbuddy",
+  "version": "0.1.0",
+  "description": "WorkBuddy (via the local workbuddy2api proxy) LLM provider adapter for DeepSeek Harness, with a Web login-status widget",
+  "type": "module",
+  "main": "lib/index.js",
+  "license": "MIT",
+  "author": "dengkun.zhang",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "llm",
+    "workbuddy",
+    "codebuddy",
+    "provider"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.8",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  }
+}