dsh-deeptutor 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# dsh-deeptutor
+
+DeepTutor bridge **bundle** for **DeepSeek Harness (dsh)**, migrated from the
+pi coding-agent extension (`TecFancy/pi-extensions`, `extensions/deeptutor` +
+`skills/deeptutor`).
+
+Registers three model-facing tools that drive the
+[HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) tutoring service:
+
+| Tool | Purpose |
+|---|---|
+| `deeptutor_run` | Run a learning capability: `deep_solve` / `deep_question` / `deep_research` / `chat` / `mastery_path` / `visualize` / `math_animator` (HTTP/WS first, CLI fallback) |
+| `deeptutor_kb` | List / search / info the user's personal knowledge bases (RAG) |
+| `deeptutor_note` | Archive Markdown learning notes to a server notebook |
+
+Deployment auto-detects local vs. remote: local `serve` (or local CLI) on this
+machine, or a server reached through an auto-started SSH tunnel (with SSH CLI
+fallback).
+
+## Install into a profile (bundle)
+
+Publish it (or point `dependencies` at a registry you control), then either:
+
+```sh
+# one-shot: install the package into the profile and add it to the bundle list
+dsh plugin --profile web add dsh-deeptutor
+```
+
+or add it manually to the profile manifest
+(`~/.dsh/profiles/<name>/package.json`):
+
+```json
+{
+  "dependencies": { "dsh-deeptutor": "^0.1.0" },
+  "dsh": {
+    "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deeptutor"] }
+  }
+}
+```
+
+The bundle manifest (`dsh.bundle.patch → cordis.patch.yml`) inserts the plugin
+row; later patch layers can override or disable it by id.
+
+## Develop against a checkout (no publish needed)
+
+```sh
+dsh web --patch /path/to/dsh-deeptutor/cordis.yml
+```
+
+## Build & publish
+
+```sh
+npm install
+npm run build        # tsc → lib/ (relative .ts imports rewritten to .js)
+npm run typecheck
+npm pack             # inspect dsh-deeptutor-0.1.0.tgz
+npm publish          # set a scope/registry of your choice first
+```
+
+Node ≥ 22.6 (type stripping) is needed to load the raw `src/*.ts` via
+`--patch`; the published bundle ships compiled `lib/`, so installed profiles
+run on plain Node ≥ 20 ESM.
+
+## Skills
+
+The agent-facing workflow lives in the `deeptutor` skill, installed at
+`~/.dsh/skills/deeptutor/SKILL.md` (auto-discovered by dsh). The companion
+`html-doc` skill (`~/.dsh/skills/html-doc/`) renders study answers to
+self-contained HTML pages; this plugin bundles the same converter under
+`scripts/md-to-html.js` and uses it when `deeptutor_run` gets an `html` path.
+
+## Configuration (env vars, agent-agnostic)
+
+```bash
+# Remote deployment (DeepTutor on a server, reached through an SSH tunnel)
+export DEEPTUTOR_SSH_HOST="tencent-cloud"           # SSH host alias (set = remote mode)
+export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"   # local tunnel address
+export DEEPTUTOR_REMOTE_BIN="/home/ubuntu/my-deeptutor/.venv/bin/deeptutor"
+export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
+
+# Local deployment — leave DEEPTUTOR_SSH_HOST unset
+# export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"  # local serve port
+# export DEEPTUTOR_LOCAL_BIN="deeptutor"             # local CLI path (default: deeptutor on PATH)
+```
+
+Restart dsh after changing env vars.
+
+## Layout
+
+```
+src/                 # TypeScript sources (dev loading, typecheck)
+lib/                 # compiled ESM (published entry, from `npm run build`)
+scripts/md-to-html.js  # zero-dependency Markdown → HTML converter
+cordis.yml           # dev overlay: insert src/index.ts by absolute path
+cordis.patch.yml     # bundle patch: insert the package by name
+```
+
+`src/index.ts` registers the tools; `config.ts` holds env config;
+`cli-exec.ts` local/SSH CLI execution; `http-api.ts` API probing + SSH tunnel;
+`turn.ts` one learning turn (WebSocket / CLI event folding + formatting);
+`html-render.ts` answer → self-contained HTML.

package/README.zh.md

@@ -0,0 +1,85 @@
+# dsh-deeptutor
+
+面向 **DeepSeek Harness (dsh)** 的 DeepTutor 桥接 **bundle**,从 pi 编码 agent 扩展迁移而来(`TecFancy/pi-extensions`,`extensions/deeptutor` + `skills/deeptutor`)。
+
+注册三个模型可见工具,驱动 [HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) 辅导服务:
+
+| 工具 | 用途 |
+|---|---|
+| `deeptutor_run` | 运行学习能力: `deep_solve` / `deep_question` / `deep_research` / `chat` / `mastery_path` / `visualize` / `math_animator`(优先 HTTP/WS,CLI 回退) |
+| `deeptutor_kb` | 列出 / 搜索 / 查看个人知识库(RAG)信息 |
+| `deeptutor_note` | 将 Markdown 学习笔记归档到服务端 notebook |
+
+部署模式自动适配:本机本地 `serve`(或本地 CLI),或通过自动建立的 SSH 隧道访问服务器(含 SSH CLI 回退)。
+
+## 安装到 profile(bundle 方式)
+
+发布后(或指向你控制的 registry),任选其一:
+
+```sh
+# 一键:将包安装进 profile 并加入 bundle 列表
+dsh plugin --profile web add dsh-deeptutor
+```
+
+或手动编辑 profile 清单(`~/.dsh/profiles/<name>/package.json`):
+
+```json
+{
+  "dependencies": { "dsh-deeptutor": "^0.1.0" },
+  "dsh": {
+    "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deeptutor"] }
+  }
+}
+```
+
+bundle 清单(`dsh.bundle.patch → cordis.patch.yml`)负责插入插件行;上层 patch 层可按 id 覆盖或禁用。
+
+## 源码开发(无需发布)
+
+```sh
+dsh web --patch /path/to/dsh-deeptutor/cordis.yml
+```
+
+## 构建与发布
+
+```sh
+npm install
+npm run build        # tsc → lib/(相对 .ts import 改写为 .js)
+npm run typecheck
+npm pack             # 检查 dsh-deeptutor-0.1.0.tgz
+npm publish
+```
+
+通过 `--patch` 直接加载 `src/*.ts` 需要 Node ≥ 22.6(type stripping);发布的 bundle 自带编译后的 `lib/`,安装到 profile 后仅需普通 Node ≥ 20 ESM。
+
+## Skills
+
+面向 agent 的工作流位于 `deeptutor` skill,安装于 `~/.dsh/skills/deeptutor/SKILL.md`(dsh 自动发现)。配套的 `html-doc` skill(`~/.dsh/skills/html-doc/`)将学习内容渲染为自包含 HTML 页面;本插件内置同一转换器(`scripts/md-to-html.js`),当 `deeptutor_run` 传入 `html` 路径时自动使用。
+
+## 配置(环境变量,与 agent 无关)
+
+```bash
+# 远程部署(DeepTutor 在服务器上,通过 SSH 隧道访问)
+export DEEPTUTOR_SSH_HOST="tencent-cloud"           # SSH 主机别名(设置 = 远程模式)
+export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"   # 本地隧道地址
+export DEEPTUTOR_REMOTE_BIN="/home/ubuntu/my-deeptutor/.venv/bin/deeptutor"
+export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
+
+# 本地部署 —— 不要设置 DEEPTUTOR_SSH_HOST
+# export DEEPTUTOR_API_BASE="http://127.0.0.1:8001"  # 本地 serve 端口
+# export DEEPTUTOR_LOCAL_BIN="deeptutor"             # 本地 CLI 路径(默认: PATH 上的 deeptutor)
+```
+
+修改环境变量后需重启 dsh。
+
+## 目录结构
+
+```
+src/                 # TypeScript 源码(开发加载、类型检查)
+lib/                 # 编译产物(发布入口,由 npm run build 生成)
+scripts/md-to-html.js  # 零依赖 Markdown → HTML 转换器
+cordis.yml           # 开发 overlay:按绝对路径插入 src/index.ts
+cordis.patch.yml     # bundle patch:按包名插入插件
+```
+
+`src/index.ts` 注册工具;`config.ts` 环境配置;`cli-exec.ts` 本地/SSH CLI 执行;`http-api.ts` API 探测 + SSH 隧道;`turn.ts` 单次学习回合(WebSocket / CLI 事件折叠与格式化);`html-render.ts` 答案 → 自包含 HTML。

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# dsh-deeptutor bundle patch: inserts the DeepTutor bridge plugin.
+#
+# Mount into a profile either by adding "dsh-deeptutor" to the profile's
+# `dsh.profile.bundles` list (recommended), or by inserting the same row
+# through a user patch layer:
+#
+#   - insert:
+#       - id: dsh-deeptutor
+#         name: 'dsh-deeptutor'
+#
+# The `name` is the npm package itself; the loader resolves it from the
+# profile's node_modules (installed via `dsh plugin` or the profile's own
+# package manager).
+
+- insert:
+    - id: dsh-deeptutor
+      name: 'dsh-deeptutor'

package/lib/cli-exec.d.ts

@@ -0,0 +1,28 @@
+export interface CliResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+    killed: boolean;
+}
+/**
+ * Unified CLI entry:
+ *   - Remote deployment (SSH_HOST set) → execute on the server over SSH;
+ *   - Local deployment (SSH_HOST empty) → execute DEEPTUTOR_LOCAL_BIN locally.
+ * args are deeptutor subcommand args (without the program name).
+ */
+export declare function runCli(args: string[], opts?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<CliResult>;
+/** Local-deployment notebook archiver: list → parse ID → create → add-md */
+export declare function cliNoteLocal(nbName: string, title: string, recordType: string, content: string, signal?: AbortSignal): Promise<{
+    stdout: string;
+    stderr: string;
+    code: number;
+}>;
+/** Remote-deployment notebook archiver (SSH CLI fallback): runs PY_NOTE on the server. */
+export declare function cliNoteRemote(nbName: string, title: string, recordType: string, content: string, signal?: AbortSignal): Promise<{
+    stdout: string;
+    stderr: string;
+    code: number;
+}>;

package/lib/cli-exec.js

@@ -0,0 +1,188 @@
+/**
+ * DeepTutor bridge: CLI execution (local process or SSH), including the notebook
+ * archiver's remote/local script plumbing.
+ */
+import { execFile, spawn } from "node:child_process";
+import { rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEEPTUTOR_BIN, DEEPTUTOR_HOME, LOCAL_BIN, SSH_HOST } from "./config.js";
+// Remote runner: reads argv from a JSON file and executes without a shell (avoids all quoting/escaping).
+const PY_RUNNER = [
+    "import json, subprocess, sys",
+    "a = json.load(open(sys.argv[1]))",
+    "r = subprocess.run(a['argv'], capture_output=True, text=True, cwd=a.get('cwd'))",
+    "sys.stdout.write(r.stdout)",
+    "if r.stderr.strip():",
+    "    sys.stdout.write('__DT_STDERR__' + r.stderr[-3000:])",
+    "sys.exit(0 if r.returncode == 0 else 1)",
+].join("\n");
+// Remote notebook archiver (CLI fallback): ensure notebook exists → write temp md → add-md.
+// NOTE: add-md takes the notebook ID as its first arg (passing a name silently "succeeds" without writing).
+const PY_NOTE = [
+    "import json, subprocess, sys",
+    "a = json.load(open(sys.argv[1]))",
+    "dt = a['dt']",
+    "nb_id = None",
+    "r = subprocess.run([dt, 'notebook', 'list'], capture_output=True, text=True)",
+    "for line in r.stdout.splitlines():",
+    "    parts = line.split('│')",
+    "    if len(parts) >= 3 and parts[2].strip() == a['notebook']:",
+    "        nb_id = parts[1].strip()",
+    "        break",
+    "if not nb_id:",
+    "    r = subprocess.run([dt, 'notebook', 'create', a['notebook'], '--description', a['description']], capture_output=True, text=True)",
+    "    try:",
+    "        nb_id = json.loads(r.stdout)['id']",
+    "    except Exception:",
+    "        sys.stdout.write(r.stdout)",
+    "        sys.exit(1)",
+    "open(a['path'], 'w').write(a['content'])",
+    "r = subprocess.run([dt, 'notebook', 'add-md', nb_id, a['path'], '--title', a['title'], '--type', a['type']], capture_output=True, text=True)",
+    "sys.stdout.write(r.stdout)",
+    "if r.stderr.strip():",
+    "    sys.stdout.write('__DT_STDERR__' + r.stderr[-2000:])",
+    "sys.exit(0 if r.returncode == 0 else 1)",
+].join("\n");
+const b64 = (s) => Buffer.from(s, "utf8").toString("base64");
+/** Timeout for each notebook-archiver CLI step (list / create / add-md). */
+const NOTE_STEP_TIMEOUT_MS = 30_000;
+/** Exec one command with optional abort + timeout, resolving instead of throwing. */
+function execFileResolved(file, args, opts = {}) {
+    return new Promise((resolve) => {
+        const child = execFile(file, args, {
+            env: opts.env ? { ...process.env, ...opts.env } : process.env,
+            windowsHide: true,
+            timeout: opts.timeoutMs,
+        }, (err, stdout, stderr) => {
+            const e = err;
+            resolve({
+                stdout: stdout ?? "",
+                stderr: stderr ?? "",
+                code: e ? (typeof e.code === "number" ? e.code : e.code === "ENOENT" ? 127 : 1) : 0,
+                killed: e?.killed ?? false,
+            });
+        });
+        opts.signal?.addEventListener("abort", () => {
+            if (process.platform === "win32") {
+                // child.kill() on Windows only kills the shell, not the process tree
+                // (deeptutor CLI is a Python app; its subprocesses would linger)
+                spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+            }
+            else {
+                child.kill();
+            }
+        }, { once: true });
+    });
+}
+async function sshExec(argv, opts = {}) {
+    const payload = JSON.stringify({ argv, cwd: DEEPTUTOR_HOME });
+    const script = [
+        `export DEEPTUTOR_HOME=${DEEPTUTOR_HOME}`,
+        "export DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=1",
+        "F=/tmp/dt_pi_$$",
+        `echo '${b64(payload)}' | base64 -d > "$F.json"`,
+        `echo '${b64(PY_RUNNER)}' | base64 -d > "$F.py"`,
+        `python3 "$F.py" "$F.json"`,
+        "rc=$?",
+        'rm -f "$F.json" "$F.py"',
+        "exit $rc",
+    ].join("\n");
+    const remote = `echo '${b64(script)}' | base64 -d | bash`;
+    const res = await execFileResolved("ssh", ["-o", "BatchMode=yes", "-o", "ConnectTimeout=10", SSH_HOST, remote], { signal: opts.signal, timeoutMs: opts.timeoutMs ?? 600_000 });
+    const out = res.stdout ?? "";
+    const [stdout, stderr] = out.split("__DT_STDERR__");
+    return {
+        stdout: stdout ?? "",
+        stderr: (stderr ?? "").trim(),
+        code: res.code ?? -1,
+        killed: res.killed,
+    };
+}
+/**
+ * Unified CLI entry:
+ *   - Remote deployment (SSH_HOST set) → execute on the server over SSH;
+ *   - Local deployment (SSH_HOST empty) → execute DEEPTUTOR_LOCAL_BIN locally.
+ * args are deeptutor subcommand args (without the program name).
+ */
+export async function runCli(args, opts = {}) {
+    if (SSH_HOST) {
+        return sshExec([DEEPTUTOR_BIN, ...args], opts);
+    }
+    // Local mode: execute directly (force UTF-8 output to avoid Windows cp1252 console crashes)
+    const res = await execFileResolved(LOCAL_BIN, args, { signal: opts.signal, timeoutMs: opts.timeoutMs, env: { PYTHONUTF8: "1", PYTHONIOENCODING: "utf-8" } });
+    const out = res.stdout ?? "";
+    const [stdout, stderr] = out.split("__DT_STDERR__");
+    return {
+        stdout: stdout ?? "",
+        stderr: (stderr ?? "").trim(),
+        code: res.code,
+        killed: res.killed,
+    };
+}
+/** Local-deployment notebook archiver: list → parse ID → create → add-md */
+export async function cliNoteLocal(nbName, title, recordType, content, signal) {
+    const list = await runCli(["notebook", "list"], { signal, timeoutMs: NOTE_STEP_TIMEOUT_MS });
+    let nbId;
+    for (const line of (list.stdout ?? "").split("\n")) {
+        const parts = line.split("│");
+        if (parts.length >= 3 && parts[2].trim() === nbName) {
+            nbId = parts[1].trim();
+            break;
+        }
+    }
+    if (!nbId) {
+        const created = await runCli([
+            "notebook",
+            "create",
+            nbName,
+            "--description",
+            `Archived by dsh agent (${new Date().toISOString().slice(0, 10)})`,
+        ], { signal, timeoutMs: NOTE_STEP_TIMEOUT_MS });
+        let parsedId;
+        try {
+            parsedId = JSON.parse(created.stdout ?? "{}").id;
+        }
+        catch {
+            return { stdout: created.stdout ?? "", stderr: created.stderr, code: created.code };
+        }
+        if (typeof parsedId !== "string") {
+            return { stdout: created.stdout ?? "", stderr: created.stderr, code: created.code };
+        }
+        nbId = parsedId;
+    }
+    const tmp = join(tmpdir(), `dt_pi_note_${Date.now()}.md`);
+    writeFileSync(tmp, content, "utf8");
+    const add = await runCli(["notebook", "add-md", nbId, tmp, "--title", title, "--type", recordType], { signal, timeoutMs: NOTE_STEP_TIMEOUT_MS });
+    rmSync(tmp, { force: true });
+    return { stdout: add.stdout ?? "", stderr: add.stderr, code: add.code };
+}
+/** Remote-deployment notebook archiver (SSH CLI fallback): runs PY_NOTE on the server. */
+export async function cliNoteRemote(nbName, title, recordType, content, signal) {
+    const path = `/tmp/dt_pi_note_${Date.now()}.md`;
+    const payload = JSON.stringify({
+        dt: DEEPTUTOR_BIN,
+        notebook: nbName,
+        description: `Archived by dsh agent (${new Date().toISOString().slice(0, 10)})`,
+        title,
+        type: recordType,
+        content,
+        path,
+    });
+    const script = [
+        `export DEEPTUTOR_HOME=${DEEPTUTOR_HOME}`,
+        "export DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=1",
+        "F=/tmp/dt_pi_note_$$",
+        `echo '${b64(payload)}' | base64 -d > "$F.json"`,
+        `echo '${b64(PY_NOTE)}' | base64 -d > "$F.py"`,
+        `python3 "$F.py" "$F.json"`,
+        "rc=$?",
+        'rm -f "$F.json" "$F.py"',
+        "exit $rc",
+    ].join("\n");
+    const remote = `echo '${b64(script)}' | base64 -d | bash`;
+    const res = await execFileResolved("ssh", ["-o", "BatchMode=yes", "-o", "ConnectTimeout=10", SSH_HOST, remote], { signal, timeoutMs: 60_000 });
+    const out = res.stdout ?? "";
+    const [stdout, stderr] = out.split("__DT_STDERR__");
+    return { stdout: stdout ?? "", stderr: (stderr ?? "").trim(), code: res.code ?? -1 };
+}

package/lib/config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * DeepTutor bridge: shared configuration (env vars) and small helpers.
+ *
+ * Config (optional env vars, agent-agnostic):
+ *   DEEPTUTOR_SSH_HOST    SSH host alias (remote deployment; unset/empty = local deployment)
+ *   DEEPTUTOR_API_BASE    API base URL (default http://127.0.0.1:8001, local or tunnel port)
+ *   DEEPTUTOR_LOCAL_BIN   local deeptutor executable (local CLI fallback; default: deeptutor on PATH)
+ *   DEEPTUTOR_REMOTE_BIN  remote deeptutor binary path (remote CLI fallback)
+ *   DEEPTUTOR_REMOTE_HOME remote DEEPTUTOR_HOME workspace (remote)
+ */
+export declare const SSH_HOST: string;
+export declare const API_BASE: string;
+export declare const TUNNEL_PORT: number;
+export declare const LOCAL_BIN: string;
+export declare const DEEPTUTOR_BIN: string;
+export declare const DEEPTUTOR_HOME: string;
+export declare function configHint(): string;
+export declare function configGuide(): string;
+export declare const CAPABILITIES: readonly ["chat", "deep_solve", "deep_question", "deep_research", "visualize", "math_animator", "mastery_path"];
+export declare const truncate: (s: string, n: number) => string;

package/lib/config.js

@@ -0,0 +1,58 @@
+/**
+ * DeepTutor bridge: shared configuration (env vars) and small helpers.
+ *
+ * Config (optional env vars, agent-agnostic):
+ *   DEEPTUTOR_SSH_HOST    SSH host alias (remote deployment; unset/empty = local deployment)
+ *   DEEPTUTOR_API_BASE    API base URL (default http://127.0.0.1:8001, local or tunnel port)
+ *   DEEPTUTOR_LOCAL_BIN   local deeptutor executable (local CLI fallback; default: deeptutor on PATH)
+ *   DEEPTUTOR_REMOTE_BIN  remote deeptutor binary path (remote CLI fallback)
+ *   DEEPTUTOR_REMOTE_HOME remote DEEPTUTOR_HOME workspace (remote)
+ */
+export const SSH_HOST = process.env.DEEPTUTOR_SSH_HOST ?? "";
+export const API_BASE = process.env.DEEPTUTOR_API_BASE ?? "http://127.0.0.1:8001";
+export const TUNNEL_PORT = Number(new URL(API_BASE).port || 8001);
+export const LOCAL_BIN = process.env.DEEPTUTOR_LOCAL_BIN ?? "deeptutor";
+export const DEEPTUTOR_BIN = process.env.DEEPTUTOR_REMOTE_BIN ?? "/home/ubuntu/my-deeptutor/.venv/bin/deeptutor";
+export const DEEPTUTOR_HOME = process.env.DEEPTUTOR_REMOTE_HOME ?? "/home/ubuntu/my-deeptutor";
+// Whether the user explicitly configured anything (show a one-time hint when not)
+const IS_CONFIGURED = Boolean(process.env.DEEPTUTOR_SSH_HOST ||
+    process.env.DEEPTUTOR_API_BASE ||
+    process.env.DEEPTUTOR_LOCAL_BIN ||
+    process.env.DEEPTUTOR_REMOTE_BIN ||
+    process.env.DEEPTUTOR_REMOTE_HOME);
+let configHintShown = false;
+export function configHint() {
+    if (IS_CONFIGURED || configHintShown)
+        return "";
+    configHintShown = true;
+    return ("⚠️ No DEEPTUTOR_* env vars detected; running in local-deployment mode (local serve / local CLI).\n" +
+        '   Local deployment: export DEEPTUTOR_API_BASE="http://127.0.0.1:8001" (serve port; optional DEEPTUTOR_LOCAL_BIN)\n' +
+        '   Remote deployment: export DEEPTUTOR_SSH_HOST="your-ssh-alias" plus DEEPTUTOR_API_BASE\n' +
+        "   (See the SKILL's Configuration section; changing server/port only requires env vars)\n");
+}
+export function configGuide() {
+    return ("\n--- Configuration troubleshooting ---\n" +
+        "Local deployment (deeptutor runs on this machine):\n" +
+        '   export DEEPTUTOR_API_BASE="http://127.0.0.1:8001" (serve port)\n' +
+        '   export DEEPTUTOR_LOCAL_BIN="deeptutor" (local CLI path, optional)\n' +
+        "   Note: do NOT set DEEPTUTOR_SSH_HOST (empty = local mode)\n" +
+        "   Verify serve is running: curl http://127.0.0.1:8001/api/v1/system/status\n" +
+        "Remote deployment (deeptutor on a server):\n" +
+        '   export DEEPTUTOR_SSH_HOST="your-ssh-alias"\n' +
+        '   export DEEPTUTOR_API_BASE="http://127.0.0.1:8001" (local tunnel address; port must match the server\'s serve)\n' +
+        '   export DEEPTUTOR_REMOTE_BIN="remote-deeptutor-binary-path"\n' +
+        '   export DEEPTUTOR_REMOTE_HOME="remote-DEEPTUTOR_HOME-workspace"\n' +
+        "   Verify serve is running on the server (ssh to it: curl http://127.0.0.1:8001/api/v1/system/status)\n" +
+        "   Verify passwordless SSH login works (ssh alias + BatchMode)\n" +
+        "Restart the agent after configuring.\n");
+}
+export const CAPABILITIES = [
+    "chat",
+    "deep_solve",
+    "deep_question",
+    "deep_research",
+    "visualize",
+    "math_animator",
+    "mastery_path",
+];
+export const truncate = (s, n) => s.length > n ? s.slice(0, n) + `\n…[truncated, ${s.length} chars total]` : s;

package/lib/html-render.d.ts

@@ -0,0 +1,14 @@
+/** Absolute path to the bundled md-to-html converter script. */
+export declare const HTML_DOC_SCRIPT: string;
+/**
+ * Render a learning answer to a self-contained local HTML file (dark/light toggle,
+ * TOC, collapsible quiz answers, print-friendly). Also writes the companion .md
+ * source next to the html file.
+ *
+ * Returns a short status note to append to the tool result ("" when no html path
+ * given; "[html] ✗ …" note when rendering fails — never throws).
+ */
+export declare function renderHtml(params: {
+    html?: string;
+    html_title?: string;
+}, answer: string): Promise<string>;

package/lib/html-render.js

@@ -0,0 +1,41 @@
+/**
+ * DeepTutor bridge: render a learning answer to a self-contained local HTML file
+ * via the bundled zero-dependency Node converter (scripts/md-to-html.js, from
+ * the html-doc skill). Kept as a standalone module (node built-ins only).
+ */
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Absolute path to the bundled md-to-html converter script. */
+export const HTML_DOC_SCRIPT = join(fileURLToPath(new URL("..", import.meta.url)), "scripts", "md-to-html.js");
+/**
+ * Render a learning answer to a self-contained local HTML file (dark/light toggle,
+ * TOC, collapsible quiz answers, print-friendly). Also writes the companion .md
+ * source next to the html file.
+ *
+ * Returns a short status note to append to the tool result ("" when no html path
+ * given; "[html] ✗ …" note when rendering fails — never throws).
+ */
+export async function renderHtml(params, answer) {
+    const out = params.html;
+    if (!out)
+        return "";
+    const htmlPath = extname(out).toLowerCase() === ".html" ? resolve(out) : resolve(out + ".html");
+    const mdPath = htmlPath.slice(0, -extname(htmlPath).length) + ".md";
+    const title = params.html_title || basename(htmlPath, extname(htmlPath));
+    try {
+        if (!existsSync(HTML_DOC_SCRIPT)) {
+            return `\n[html] ✗ html-doc converter not found: ${HTML_DOC_SCRIPT}`;
+        }
+        mkdirSync(dirname(htmlPath), { recursive: true });
+        writeFileSync(mdPath, answer || "(no answer)", "utf8");
+        await new Promise((res, rej) => {
+            execFile(process.execPath, [HTML_DOC_SCRIPT, mdPath, "--out", htmlPath, "--title", title, "--toc"], { windowsHide: true, timeout: 60_000 }, (err, _stdout, stderr) => (err ? rej(new Error(stderr || err.message)) : res()));
+        });
+        return `\n[html] ✓ rendered (html-doc skill)\n[html]   page: ${htmlPath}\n[html]   source: ${mdPath}`;
+    }
+    catch (err) {
+        return `\n[html] ✗ rendering failed: ${err?.message ?? String(err)}`;
+    }
+}

package/lib/http-api.d.ts

@@ -0,0 +1,10 @@
+/** Kill the SSH tunnel process, if one is running (call on plugin disposal). */
+export declare function killTunnel(): void;
+export declare function apiProbe(timeoutMs?: number): Promise<boolean>;
+/** Ensure the local API is reachable: probe → start SSH tunnel if needed (remote only) → wait. */
+export declare function ensureApi(): Promise<boolean>;
+/** JSON fetch against the DeepTutor API. Combines a fixed timeout with an optional caller-supplied abort signal. */
+export declare function apiJson(path: string, init?: RequestInit, opts?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<any>;

package/lib/http-api.js

@@ -0,0 +1,77 @@
+/**
+ * DeepTutor bridge: HTTP/WS transport (API probing, SSH tunnel management, JSON calls).
+ */
+import { spawn } from "node:child_process";
+import { API_BASE, SSH_HOST, TUNNEL_PORT } from "./config.js";
+let tunnelProc = null;
+/** Kill the SSH tunnel process, if one is running (call on plugin disposal). */
+export function killTunnel() {
+    if (tunnelProc && tunnelProc.exitCode === null) {
+        try {
+            tunnelProc.kill();
+        }
+        catch { }
+        tunnelProc = null;
+    }
+}
+export async function apiProbe(timeoutMs = 1500) {
+    try {
+        const res = await fetch(`${API_BASE}/api/v1/system/status`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** Ensure the local API is reachable: probe → start SSH tunnel if needed (remote only) → wait. */
+export async function ensureApi() {
+    if (await apiProbe(1200))
+        return true;
+    if (!SSH_HOST)
+        return false; // Local deployment: fall back to local CLI when serve is down, no tunnel needed
+    if (!tunnelProc || tunnelProc.exitCode !== null) {
+        tunnelProc = spawn("ssh", [
+            "-N",
+            "-L",
+            `${TUNNEL_PORT}:127.0.0.1:${TUNNEL_PORT}`,
+            "-o",
+            "BatchMode=yes",
+            "-o",
+            "ExitOnForwardFailure=yes",
+            "-o",
+            "ServerAliveInterval=30",
+            "-o",
+            "ServerAliveCountMax=3",
+            "-o",
+            "ConnectTimeout=10",
+            SSH_HOST,
+        ], { stdio: "ignore", windowsHide: true });
+        tunnelProc.unref();
+    }
+    for (let i = 0; i < 20; i++) {
+        if (await apiProbe(1000))
+            return true;
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    return false;
+}
+/** JSON fetch against the DeepTutor API. Combines a fixed timeout with an optional caller-supplied abort signal. */
+export async function apiJson(path, init, opts = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 60_000);
+    const onAbort = () => controller.abort();
+    opts.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        const res = await fetch(`${API_BASE}${path}`, { ...init, signal: controller.signal });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status} ${res.statusText}`);
+        const text = await res.text();
+        return text ? JSON.parse(text) : null;
+    }
+    finally {
+        clearTimeout(timer);
+        opts.signal?.removeEventListener("abort", onAbort);
+    }
+}