dsh-deeptutor 0.1.11 → 0.2.1

package/lib/index.js

@@ -1,9 +1,8 @@
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { CAPABILITIES, configGuide, configHint, SSH_HOST, truncate } from "./config.js";
 import { cliNoteLocal, cliNoteRemote, runCli } from "./cli-exec.js";
-import { apiJson, ensureApi, killTunnel } from "./http-api.js";
 import { renderHtml } from "./html-render.js";
-import { cliRunTurn, fmtTurnResult, wsRunTurn } from "./turn.js";
+import { cliRunTurn, fmtTurnResult } from "./turn.js";
 import { HTML_DOC_SCRIPT } from "./html-render.js";
 export const name = "dsh-deeptutor";
 export const inject = ["tools"];
@@ -16,10 +15,6 @@ function json(o) {
 }
 export function apply(ctx) {
     console.log(`[dsh-deeptutor] plugin loaded (html script: ${HTML_DOC_SCRIPT})`);
-    // Kill the SSH tunnel process when the plugin unloads.
-    ctx.effect(() => {
-        return () => killTunnel();
-    });
     // ---------- Tool 1: run a DeepTutor learning capability ----------
     ctx.tools.register(defineTool({
         name: "deeptutor_run",
@@ -94,27 +89,6 @@ export function apply(ctx) {
         async execute(args, exec) {
             const timeoutMs = (args.timeout ?? 600) * 1000;
             const maxChars = args.max_chars ?? 30000;
-            try {
-                if (await ensureApi()) {
-                    const r = await wsRunTurn(args, timeoutMs, exec.signal);
-                    const htmlNote = await renderHtml(args, r.answer);
-                    return json({
-                        mode: "http",
-                        sessionId: r.sessionId,
-                        toolCalls: r.toolCalls,
-                        errors: r.errors,
-                        text: configHint() + fmtTurnResult(args.capability, r, maxChars) + htmlNote,
-                    });
-                }
-            }
-            catch (err) {
-                if (exec.signal.aborted) {
-                    // user cancelled mid-flight: don't start a fresh CLI run behind their back
-                    throw new Error("[deeptutor_run cancelled]");
-                }
-                console.log(`[deeptutor] HTTP/WS failed, falling back to CLI: ${err?.message}`);
-            }
-            // fallback: local/SSH CLI
             try {
                 const r = await cliRunTurn(args, timeoutMs, exec.signal);
                 const htmlNote = await renderHtml(args, r.answer);
@@ -132,7 +106,7 @@ export function apply(ctx) {
                     throw new Error("[deeptutor_run cancelled]");
                 }
                 throw new Error(configGuide() +
-                    `[deeptutor_run failed (HTTP and CLI both unavailable)] ${err?.message ?? String(err)}`);
+                    `[deeptutor_run failed] ${err?.message ?? String(err)}`);
             }
         },
     }));
@@ -185,41 +159,7 @@ export function apply(ctx) {
         },
         async execute(args, exec) {
             const maxChars = args.max_chars ?? 30000;
-            // search goes through the CLI (REST has no dedicated search route);
-            // list/info prefer HTTP, fall back to CLI
-            if (args.action !== "search") {
-                try {
-                    if (await ensureApi()) {
-                        if (args.action === "list") {
-                            const arr = await apiJson("/api/v1/knowledge/list", undefined, {
-                                signal: exec.signal,
-                            });
-                            const body = Array.isArray(arr)
-                                ? arr
-                                    .map((kb) => `- ${kb.name} (status=${kb.status ?? "?"}, ${kb.statistics ? JSON.stringify(kb.statistics) : "no stats"}${kb.is_default ? ", default" : ""})`)
-                                    .join("\n")
-                                : JSON.stringify(arr);
-                            return json({
-                                action: "list",
-                                mode: "http",
-                                text: configHint() +
-                                    `Knowledge bases (${Array.isArray(arr) ? arr.length : "?"}):\n${body}`,
-                            });
-                        }
-                        const kb = await apiJson(`/api/v1/knowledge/${encodeURIComponent(args.kb ?? "")}`, undefined, { signal: exec.signal });
-                        return json({
-                            action: "info",
-                            mode: "http",
-                            kb: args.kb,
-                            text: truncate(JSON.stringify(kb, null, 2), maxChars),
-                        });
-                    }
-                }
-                catch (err) {
-                    console.log(`[deeptutor] kb ${args.action} HTTP failed, falling back to CLI: ${err?.message}`);
-                }
-            }
-            // CLI fallback (local or SSH). NOTE: `kb search` has no --top-k flag
+            // Local or SSH CLI. NOTE: `kb search` has no --top-k flag
             // (verified on deeptutor CLI 1.5.x); top_k is applied locally below.
             let argv;
             if (args.action === "list") {
@@ -337,53 +277,7 @@ export function apply(ctx) {
         async execute(args, exec) {
             const recordType = (args.type ?? "chat");
             const nbName = args.notebook.trim();
-            // HTTP first
-            try {
-                if (await ensureApi()) {
-                    const list = await apiJson("/api/v1/notebook/list", undefined, {
-                        signal: exec.signal,
-                    });
-                    const notebooks = list?.notebooks ?? [];
-                    let nb = notebooks.find((n) => n.name?.trim() === nbName);
-                    if (!nb) {
-                        const created = await apiJson("/api/v1/notebook/create", {
-                            method: "POST",
-                            headers: { "Content-Type": "application/json" },
-                            body: JSON.stringify({
-                                name: nbName,
-                                description: `Archived by dsh agent (${new Date().toISOString().slice(0, 10)})`,
-                            }),
-                        }, { signal: exec.signal });
-                        nb = created?.notebook ?? created;
-                    }
-                    const nbId = nb?.id ?? (typeof nb === "string" ? nb : undefined);
-                    if (!nbId)
-                        throw new Error("cannot resolve notebook id");
-                    const added = await apiJson("/api/v1/notebook/add_record", {
-                        method: "POST",
-                        headers: { "Content-Type": "application/json" },
-                        body: JSON.stringify({
-                            notebook_ids: [nbId],
-                            record_type: recordType,
-                            title: args.title,
-                            user_query: args.title,
-                            output: args.content,
-                        }),
-                    }, { signal: exec.signal });
-                    return json({
-                        notebook: nbName,
-                        nbId: String(nbId),
-                        title: args.title,
-                        mode: "http",
-                        text: configHint() +
-                            `[note archived (HTTP)] notebook=${nbName} (${nbId}), title=${args.title}, type=${recordType}\n${truncate(JSON.stringify(added ?? {}), 800)}`,
-                    });
-                }
-            }
-            catch (err) {
-                console.log(`[deeptutor] note HTTP failed, falling back to CLI: ${err?.message}`);
-            }
-            // CLI fallback: remote deployment uses the remote PY_NOTE script; local deployment runs locally
+            // Remote deployment runs the PY_NOTE script on the server; local deployment runs locally
             const { stdout, stderr, code } = SSH_HOST
                 ? await cliNoteRemote(nbName, args.title, recordType, args.content, exec.signal)
                 : await cliNoteLocal(nbName, args.title, recordType, args.content, exec.signal);
@@ -396,7 +290,7 @@ export function apply(ctx) {
                 title: args.title,
                 mode: "cli",
                 text: configHint() +
-                    `[note archived (CLI)] notebook=${nbName}, title=${args.title}, type=${recordType}\n${truncate((stdout ?? "").trim(), 2000)}`,
+                    `[note archived] notebook=${nbName}, title=${args.title}, type=${recordType}\n${truncate((stdout ?? "").trim(), 2000)}`,
             });
         },
     }));

package/lib/turn.d.ts

@@ -6,7 +6,7 @@ export interface TurnResult {
     sessionId?: string;
     title?: string;
 }
-/** Fields both wsRunTurn and cliRunTurn read off the deeptutor_run tool params. */
+/** Fields cliRunTurn reads off the deeptutor_run tool params. */
 export interface RunParams {
     prompt: string;
     capability: string;
@@ -16,10 +16,8 @@ export interface RunParams {
     language?: string;
     config?: Record<string, unknown>;
 }
-/** Fold one event (WS or CLI JSONL) into the running turn state. Exported for unit tests. */
+/** Fold one CLI JSONL event into the running turn state. Exported for unit tests. */
 export declare function collectEvent(state: TurnResult, e: any): void;
-/** Execute one turn over WebSocket (streaming). */
-export declare function wsRunTurn(params: RunParams, timeoutMs: number, signal?: AbortSignal): Promise<TurnResult>;
 /**
  * Build the `deeptutor run` argv for a capability turn (pure, unit-tested).
  * Scalar config values go as repeatable --config k=v; object/array values are

package/lib/turn.js

@@ -1,10 +1,10 @@
 /**
- * DeepTutor bridge: one learning "turn" — running a capability over WebSocket (HTTP mode)
- * or the CLI (fallback), and shared JSONL/WS event parsing + result formatting.
+ * DeepTutor bridge: one learning "turn" — running a capability through the deeptutor CLI
+ * (local or over SSH), JSONL event parsing and result formatting.
  */
-import { API_BASE, truncate } from "./config.js";
+import { truncate } from "./config.js";
 import { runCli } from "./cli-exec.js";
-/** Fold one event (WS or CLI JSONL) into the running turn state. Exported for unit tests. */
+/** Fold one CLI JSONL event into the running turn state. Exported for unit tests. */
 export function collectEvent(state, e) {
     if (e.type === "content" && typeof e.content === "string")
         state.answer += e.content;
@@ -19,97 +19,6 @@ export function collectEvent(state, e) {
     if (!state.sessionId && typeof e.session_id === "string")
         state.sessionId = e.session_id;
 }
-/** Execute one turn over WebSocket (streaming). */
-export function wsRunTurn(params, timeoutMs, signal) {
-    return new Promise((resolve, reject) => {
-        if (signal?.aborted)
-            return reject(new Error("Aborted"));
-        const WSImpl = globalThis.WebSocket;
-        if (!WSImpl)
-            return reject(new Error("WebSocket is not available in this environment"));
-        const ws = new WSImpl(`${API_BASE.replace(/^http/, "ws")}/api/v1/ws`);
-        let settled = false;
-        const state = { answer: "", errors: [], toolCalls: [] };
-        let timer;
-        const finish = (fn) => {
-            if (settled)
-                return;
-            settled = true;
-            if (timer)
-                clearTimeout(timer);
-            signal?.removeEventListener("abort", onAbort);
-            fn();
-        };
-        timer = setTimeout(() => {
-            finish(() => {
-                try {
-                    ws.close();
-                }
-                catch { }
-                reject(new Error(`WebSocket timeout (${Math.round(timeoutMs / 1000)}s)`));
-            });
-        }, timeoutMs);
-        const onAbort = () => {
-            finish(() => {
-                try {
-                    ws.close();
-                }
-                catch { }
-                reject(new Error("Aborted"));
-            });
-        };
-        signal?.addEventListener("abort", onAbort, { once: true });
-        ws.onopen = () => {
-            ws.send(JSON.stringify({
-                type: "start_turn",
-                content: params.prompt,
-                capability: params.capability,
-                session_id: params.session_id ?? null,
-                tools: params.tools ?? [],
-                knowledge_bases: params.kbs ?? [],
-                language: params.language ?? "en",
-                config: params.config ?? {},
-                notebook_references: [],
-                history_references: [],
-                attachments: [],
-                skills: [],
-            }));
-        };
-        ws.onmessage = (ev) => {
-            let e;
-            try {
-                e = JSON.parse(ev.data);
-            }
-            catch {
-                return;
-            }
-            collectEvent(state, e);
-            if (e.type === "done") {
-                finish(() => {
-                    try {
-                        ws.close();
-                    }
-                    catch { }
-                    resolve(state);
-                });
-            }
-        };
-        ws.onerror = () => {
-            finish(() => {
-                try {
-                    ws.close();
-                }
-                catch { }
-                reject(new Error("WebSocket connection error (server not running or tunnel down)"));
-            });
-        };
-        ws.onclose = () => {
-            finish(() => {
-                reject(new Error("WebSocket closed unexpectedly"));
-            });
-        };
-    });
-}
 /**
  * Build the `deeptutor run` argv for a capability turn (pure, unit-tested).
  * Scalar config values go as repeatable --config k=v; object/array values are

package/lib/win-cmd.d.ts

@@ -0,0 +1,27 @@
+export interface LocalCommand {
+    file: string;
+    args: string[];
+    /** Pass the args to CreateProcess unchanged (needed for the cmd.exe command line). */
+    windowsVerbatimArguments?: boolean;
+    /** Set when the command cannot be run as requested; nothing should be spawned. */
+    error?: string;
+}
+/** Quote one argument for a cmd.exe command line (cross-spawn's escapeArgument). */
+export declare function escapeCmdArgument(arg: string, doubleEscapeMetaChars: boolean): string;
+/** Escape the command path itself for a cmd.exe command line. */
+export declare function escapeCmdCommand(command: string): string;
+/**
+ * Build the `cmd.exe /d /s /c "..."` invocation for a batch file. Arguments are escaped
+ * twice because a batch file that forwards `%*` makes cmd.exe parse them a second time.
+ */
+export declare function buildCmdInvocation(batchFile: string, args: string[], comSpec?: string): LocalCommand;
+/**
+ * If a .cmd/.bat wrapper does nothing but forward its arguments to an executable, return
+ * that executable's path. Accepts `@echo off`, `rem`/`::` comments and `setlocal`/`endlocal`
+ * around a single `["]<path>.exe["] %*` line; `%~dp0` is expanded to the wrapper's folder.
+ */
+export declare function parseCmdWrapper(text: string, wrapperPath: string): string | undefined;
+/** Find a bare command name on PATH, trying each PATHEXT extension (Windows search order). */
+export declare function findOnPath(name: string, env?: NodeJS.ProcessEnv, exists?: (p: string) => boolean): string | undefined;
+/** Turn a local CLI path plus argv into something execFile can start on this platform. */
+export declare function resolveLocalCommand(file: string, args: string[], platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): LocalCommand;

package/lib/win-cmd.js

@@ -0,0 +1,108 @@
+/**
+ * DeepTutor bridge: launching the local deeptutor CLI on Windows.
+ *
+ * Node's execFile cannot start a .cmd/.bat file directly on Windows (spawn EINVAL, see
+ * issue #8), and it does not search PATHEXT for a bare command name. resolveLocalCommand
+ * turns DEEPTUTOR_LOCAL_BIN into something execFile can run:
+ *   1. a bare name is looked up on PATH using PATHEXT;
+ *   2. a .cmd/.bat that only forwards its arguments to an .exe (`"C:\...\deeptutor.exe" %*`)
+ *      is replaced by that .exe, so no shell is involved;
+ *   3. any other .cmd/.bat runs through `cmd.exe /d /s /c` with every argument quoted and
+ *      its metacharacters escaped (the same scheme as cross-spawn).
+ * cmd.exe ends a command line at a newline, so case 3 cannot pass multi-line arguments;
+ * resolveLocalCommand reports that instead of silently truncating the prompt.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { extname, win32 } from "node:path";
+const META_CHARS = /([()\][%!^"`<>&|;, *?])/g;
+/** Quote one argument for a cmd.exe command line (cross-spawn's escapeArgument). */
+export function escapeCmdArgument(arg, doubleEscapeMetaChars) {
+    let out = arg.replace(/(\\*)"/g, '$1$1\\"');
+    out = out.replace(/(\\*)$/, "$1$1");
+    out = `"${out}"`;
+    out = out.replace(META_CHARS, "^$1");
+    if (doubleEscapeMetaChars)
+        out = out.replace(META_CHARS, "^$1");
+    return out;
+}
+/** Escape the command path itself for a cmd.exe command line. */
+export function escapeCmdCommand(command) {
+    return command.replace(META_CHARS, "^$1");
+}
+/**
+ * Build the `cmd.exe /d /s /c "..."` invocation for a batch file. Arguments are escaped
+ * twice because a batch file that forwards `%*` makes cmd.exe parse them a second time.
+ */
+export function buildCmdInvocation(batchFile, args, comSpec = "cmd.exe") {
+    const line = [escapeCmdCommand(batchFile), ...args.map((a) => escapeCmdArgument(a, true))].join(" ");
+    return { file: comSpec, args: ["/d", "/s", "/c", `"${line}"`], windowsVerbatimArguments: true };
+}
+/**
+ * If a .cmd/.bat wrapper does nothing but forward its arguments to an executable, return
+ * that executable's path. Accepts `@echo off`, `rem`/`::` comments and `setlocal`/`endlocal`
+ * around a single `["]<path>.exe["] %*` line; `%~dp0` is expanded to the wrapper's folder.
+ */
+export function parseCmdWrapper(text, wrapperPath) {
+    const lines = text
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l !== "" &&
+        !/^@?echo\s+off$/i.test(l) &&
+        !/^@?(rem(\s|$)|::)/i.test(l) &&
+        !/^@?(setlocal|endlocal)(\s|$)/i.test(l));
+    if (lines.length !== 1)
+        return undefined;
+    const m = /^@?(?:"([^"]+\.(?:exe|com))"|([^\s"]+\.(?:exe|com)))\s+%\*$/i.exec(lines[0]);
+    if (!m)
+        return undefined;
+    // Windows path rules regardless of the host, so this also behaves the same in Linux CI.
+    const dir = win32.dirname(wrapperPath);
+    const target = (m[1] ?? m[2]).replace(/%~dp0/gi, dir + "\\");
+    if (/%/.test(target))
+        return undefined; // other variables: let cmd.exe expand them
+    return win32.resolve(dir, target);
+}
+/** Find a bare command name on PATH, trying each PATHEXT extension (Windows search order). */
+export function findOnPath(name, env = process.env, exists = existsSync) {
+    const exts = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+    // Windows path rules regardless of the host, so this also behaves the same in Linux CI.
+    const dirs = (env.PATH ?? env.Path ?? "").split(win32.delimiter).filter(Boolean);
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            const candidate = win32.join(dir.replace(/^"|"$/g, ""), name + ext.toLowerCase());
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/** Turn a local CLI path plus argv into something execFile can start on this platform. */
+export function resolveLocalCommand(file, args, platform = process.platform, env = process.env) {
+    if (platform !== "win32")
+        return { file, args };
+    let target = file;
+    const isBareName = !/[\\/]/.test(target) && extname(target) === "";
+    if (isBareName)
+        target = findOnPath(target, env) ?? target;
+    if (!/\.(cmd|bat)$/i.test(target))
+        return { file: target, args };
+    let wrapped;
+    try {
+        wrapped = parseCmdWrapper(readFileSync(target, "utf8"), target);
+    }
+    catch {
+        wrapped = undefined;
+    }
+    if (wrapped && existsSync(wrapped))
+        return { file: wrapped, args };
+    if (args.some((a) => /[\r\n]/.test(a))) {
+        return {
+            file: target,
+            args,
+            error: `${target} is a batch file, and cmd.exe cannot pass arguments that contain line breaks. ` +
+                "Point DEEPTUTOR_LOCAL_BIN at deeptutor.exe instead (in a pip/venv install it is " +
+                "<venv>\\Scripts\\deeptutor.exe).",
+        };
+    }
+    return buildCmdInvocation(target, args, env.ComSpec ?? env.COMSPEC ?? "cmd.exe");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-deeptutor",
-  "version": "0.1.11",
-  "description": "Learning assistant extension for DeepSeek Harness (dsh): DeepTutor tutoring for your agent — deep explanations, self-test questions, learning paths, personal knowledge-base search (RAG), and note archiving (HTTP/WS first, CLI fallback; auto-adapts local/remote deployment).",
+  "version": "0.2.1",
+  "description": "Learning assistant extension for DeepSeek Harness (dsh): DeepTutor tutoring for your agent — deep explanations, self-test questions, learning paths, personal knowledge-base search (RAG), and note archiving (drives the DeepTutor CLI locally or over SSH).",
   "keywords": [
     "dsh",
     "dsh-plugin",

package/scripts/md-to-html.js

@@ -360,13 +360,22 @@ function main() {
     fail(`template.html not found (looked in: ${templateCandidates.join(", ")})`);
   }
   let template = fs.readFileSync(templatePath, "utf8");
-  template = template
-    .replace(/\{\{TITLE\}\}/g, esc(title))
-    .replace(/\{\{BODY\}\}/g, html)
-    .replace(/\{\{TOC\}\}/g, tocHtml)
-    .replace(/\{\{THEME\}\}/g, opts.theme)
-    .replace(/\{\{LANG\}\}/g, opts.lang)
-    .replace(/\{\{GENERATED\}\}/g, generated);
+  // One pass over the template with a replacer function: the inserted text is
+  // used verbatim (a replacement *string* would expand `$$`, `$&`, `` $` ``,
+  // `$'`), and text already inserted (e.g. a literal `{{TOC}}` in the body)
+  // is never scanned for placeholders again.
+  const values = {
+    TITLE: esc(title),
+    BODY: html,
+    TOC: tocHtml,
+    THEME: opts.theme,
+    LANG: opts.lang,
+    GENERATED: generated,
+  };
+  template = template.replace(
+    /\{\{(TITLE|BODY|TOC|THEME|LANG|GENERATED)\}\}/g,
+    (_, key) => values[key],
+  );
 
   if (opts.out) {
     fs.writeFileSync(opts.out, template, "utf8");

package/src/cli-exec.ts

@@ -7,6 +7,7 @@ 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.ts";
+import { resolveLocalCommand } from "./win-cmd.ts";
 
 export interface CliResult {
   stdout: string;
@@ -63,7 +64,12 @@ const NOTE_STEP_TIMEOUT_MS = 30_000;
 function execFileResolved(
   file: string,
   args: string[],
-  opts: { signal?: AbortSignal; timeoutMs?: number; env?: Record<string, string> } = {},
+  opts: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    windowsVerbatimArguments?: boolean;
+  } = {},
 ): Promise<CliResult> {
   return new Promise((resolve) => {
     const child = execFile(
@@ -72,6 +78,7 @@ function execFileResolved(
       {
         env: opts.env ? { ...process.env, ...opts.env } : process.env,
         windowsHide: true,
+        windowsVerbatimArguments: opts.windowsVerbatimArguments,
         timeout: opts.timeoutMs,
       },
       (err, stdout, stderr) => {
@@ -145,12 +152,16 @@ export async function runCli(
   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" } },
-  );
+  // Local mode: execute directly (force UTF-8 output to avoid Windows cp1252 console crashes).
+  // On Windows a .cmd/.bat LOCAL_BIN needs special handling (spawn EINVAL otherwise, issue #8).
+  const cmd = resolveLocalCommand(LOCAL_BIN, args);
+  if (cmd.error) return { stdout: "", stderr: cmd.error, code: 1, killed: false };
+  const res = await execFileResolved(cmd.file, cmd.args, {
+    signal: opts.signal,
+    timeoutMs: opts.timeoutMs,
+    env: { PYTHONUTF8: "1", PYTHONIOENCODING: "utf-8" },
+    windowsVerbatimArguments: cmd.windowsVerbatimArguments,
+  });
   const out = res.stdout ?? "";
   const [stdout, stderr] = out.split("__DT_STDERR__");
   return {

package/src/config.ts

@@ -1,16 +1,16 @@
 /**
  * DeepTutor bridge: shared configuration (env vars) and small helpers.
  *
+ * Every call goes through the deeptutor CLI. DeepTutor 1.7 moved its HTTP/WS routes off
+ * /api/v1 and put them behind a login, so the plugin no longer talks to `deeptutor serve`.
+ *
  * 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)
+ *   DEEPTUTOR_LOCAL_BIN   local deeptutor executable (default: deeptutor on PATH)
+ *   DEEPTUTOR_REMOTE_BIN  remote deeptutor binary path (remote deployment)
+ *   DEEPTUTOR_REMOTE_HOME remote DEEPTUTOR_HOME workspace (remote deployment)
  */
 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";
@@ -19,7 +19,6 @@ export const DEEPTUTOR_HOME = process.env.DEEPTUTOR_REMOTE_HOME ?? "/home/ubuntu
 // 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,
@@ -30,28 +29,28 @@ export function configHint(): string {
   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"
+    "⚠️ No DEEPTUTOR_* env vars detected; running in local-deployment mode (deeptutor CLI on PATH).\n" +
+    '   Local deployment: optionally export DEEPTUTOR_LOCAL_BIN="/path/to/deeptutor"\n' +
+    '   Remote deployment: export DEEPTUTOR_SSH_HOST="your-ssh-alias" plus DEEPTUTOR_REMOTE_BIN / DEEPTUTOR_REMOTE_HOME\n' +
+    "   (See the SKILL's Configuration section; changing server only requires env vars)\n"
   );
 }
 
 export function configGuide(): string {
   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' +
+    "Local deployment (deeptutor installed on this machine):\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" +
+    "   Verify the CLI works: deeptutor kb list --format json\n" +
+    "Remote deployment (deeptutor on a server, driven over SSH):\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" +
+    "   Verify the remote CLI works: ssh <alias> <DEEPTUTOR_REMOTE_BIN> kb list --format json\n" +
+    "DeepTutor 1.7+: the kb / notebook commands and most capabilities need their modules\n" +
+    "   installed and enabled (check with: deeptutor module list).\n" +
     'PowerShell users: use $env:VAR="value" instead of export VAR=value.\n' +
     "Restart the agent after configuring.\n"
   );