dsh-deeptutor 0.1.0

package/lib/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DeepTutor bridge plugin for DeepSeek Harness (dsh).
+ *
+ * Migrated from the pi coding-agent extension (TecFancy/pi-extensions,
+ * extensions/deeptutor + skills/deeptutor). Registers three model-facing tools:
+ *   - deeptutor_run  — execute a DeepTutor learning capability (HTTP/WS first, CLI fallback)
+ *   - deeptutor_kb   — list / search / info knowledge bases
+ *   - deeptutor_note — archive a Markdown learning note to a server notebook
+ *
+ * Deployment auto-detection:
+ *   - Local: deeptutor serve runs on this machine → API probe succeeds directly; if serve is
+ *     not running, falls back to the local CLI (DEEPTUTOR_LOCAL_BIN).
+ *   - Remote: serve runs on a server (listening on 127.0.0.1 only) → an SSH tunnel is started
+ *     automatically to reach the API; if the tunnel is unavailable, falls back to the SSH CLI.
+ *
+ * Env config (agent-agnostic): DEEPTUTOR_SSH_HOST / DEEPTUTOR_API_BASE / DEEPTUTOR_LOCAL_BIN /
+ * DEEPTUTOR_REMOTE_BIN / DEEPTUTOR_REMOTE_HOME — see src/config.ts and skills/deeptutor/SKILL.md.
+ */
+import type { Context } from "@deepseek-ai/cordis";
+export declare const name = "dsh-deeptutor";
+export declare const inject: readonly ["tools"];
+export declare function apply(ctx: Context): void;

package/lib/index.js

@@ -0,0 +1,384 @@
+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 { HTML_DOC_SCRIPT } from "./html-render.js";
+export const name = "dsh-deeptutor";
+export const inject = ["tools"];
+function json(o) {
+    const out = {};
+    for (const [k, v] of Object.entries(o))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+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",
+        description: "Execute one learning call on the DeepTutor service: deep_solve (in-depth explanation), deep_question (generate self-test questions), deep_research (deep research), chat (conversation), mastery_path (learning path planning), visualize / math_animator (visualization). Can mount knowledge bases (kbs) and tools (tools like rag / web_search). Returns the final answer plus session_id; pass session_id in later turns to continue the context (inherits chat history, knowledge bases and tools).",
+        parameters: {
+            capability: {
+                type: "string",
+                enum: [...CAPABILITIES],
+                required: true,
+                description: "The learning capability to run",
+            },
+            prompt: {
+                type: "string",
+                required: true,
+                description: "The learning question or instruction for this turn (e.g. explain the async/await state machine)",
+            },
+            kbs: {
+                type: "array",
+                items: { type: "string" },
+                description: "Knowledge base names (check deeptutor_kb list for available ones, e.g. the user's dotnet/sqlserver bases)",
+            },
+            tools: {
+                type: "array",
+                items: { type: "string" },
+                description: "Tools to enable: rag (KB retrieval), web_search, reason, brainstorm, paper_search, code_execution, read_source, etc.",
+            },
+            session_id: {
+                type: "string",
+                description: "Session ID from a previous deeptutor_run call to continue that context",
+            },
+            config: {
+                type: "object",
+                additionalProperties: true,
+                description: "Capability config key-values, e.g. num_questions=5 for deep_question, mode=report / depth=standard for deep_research",
+            },
+            language: {
+                type: "string",
+                description: "Response language code, default en; use zh for Chinese",
+            },
+            timeout: {
+                type: "number",
+                description: "Timeout in seconds, default 600; use 900+ for deep_research",
+            },
+            max_chars: {
+                type: "number",
+                description: "Max characters of the answer returned to the model, default 30000",
+            },
+            html: {
+                type: "string",
+                description: "Optional output path for a self-contained local HTML render of the answer (bundled md-to-html converter; also writes the companion .md source next to it). e.g. data/study/abstract-class/knowledge.html — open the HTML in a browser to read comfortably. Set it when the user wants browsable/printable study material.",
+            },
+            html_title: {
+                type: "string",
+                description: "HTML page title (default: derived from the html output file name)",
+            },
+        },
+        output: {
+            schema: {
+                type: "object",
+                properties: {
+                    mode: { type: "string" },
+                    sessionId: { type: "string" },
+                    answer: { type: "string" },
+                    toolCalls: { type: "array", items: { type: "string" } },
+                    errors: { type: "array", items: { type: "string" } },
+                    text: { type: "string" },
+                },
+                additionalProperties: true,
+            },
+            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
+        },
+        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);
+                return json({
+                    mode: "cli",
+                    sessionId: r.sessionId,
+                    toolCalls: r.toolCalls,
+                    errors: r.errors,
+                    text: configHint() + fmtTurnResult(args.capability, r, maxChars) + htmlNote,
+                });
+            }
+            catch (err) {
+                throw new Error(configGuide() +
+                    `[deeptutor_run failed (HTTP and CLI both unavailable)] ${err?.message ?? String(err)}`);
+            }
+        },
+    }));
+    // ---------- Tool 2: knowledge base operations ----------
+    ctx.tools.register(defineTool({
+        name: "deeptutor_kb",
+        description: "Manage/search DeepTutor knowledge bases: list all bases, search inside a base (RAG hit snippets), info for details. Works in both local and remote deployments. Search the user's personal knowledge bases before generating learning content and combine the hits with authoritative sources.",
+        parameters: {
+            action: {
+                type: "string",
+                enum: ["list", "search", "info"],
+                required: true,
+                description: "What to do with the knowledge bases",
+            },
+            kb: {
+                type: "string",
+                description: "Knowledge base name (required for search/info)",
+            },
+            query: {
+                type: "string",
+                description: "Search question (required for search, e.g. C# generics covariance/contravariance)",
+            },
+            mode: {
+                type: "string",
+                enum: ["hybrid", "dense", "sparse"],
+                description: "Retrieval mode, default hybrid",
+            },
+            top_k: {
+                type: "number",
+                description: "Number of hits to return, default 5",
+            },
+            max_chars: {
+                type: "number",
+                description: "Max characters of the returned content, default 30000",
+            },
+        },
+        output: {
+            schema: {
+                type: "object",
+                properties: {
+                    action: { type: "string" },
+                    mode: { type: "string" },
+                    kb: { type: "string" },
+                    query: { type: "string" },
+                    text: { type: "string" },
+                },
+                additionalProperties: true,
+            },
+            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
+        },
+        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)
+            let argv;
+            if (args.action === "list") {
+                argv = ["kb", "list", "--format", "json"];
+            }
+            else if (args.action === "info") {
+                argv = ["kb", "info", args.kb ?? ""];
+            }
+            else {
+                argv = [
+                    "kb",
+                    "search",
+                    args.kb ?? "",
+                    args.query ?? "",
+                    "--format",
+                    "json",
+                    "--mode",
+                    args.mode ?? "hybrid",
+                ];
+                if (args.top_k)
+                    argv.push("--top-k", String(args.top_k));
+            }
+            const { stdout, stderr, code, killed } = await runCli(argv, {
+                signal: exec.signal,
+                timeoutMs: 90_000,
+            });
+            if (killed)
+                throw new Error(configGuide() + "[deeptutor_kb timed out]");
+            if (code !== 0) {
+                throw new Error(`[deeptutor_kb failed] exit=${code}\nstderr: ${truncate(stderr || "(none)", 2000)}` +
+                    configGuide());
+            }
+            let body = stdout.trim() || "(empty result)";
+            if (args.action === "search") {
+                try {
+                    const arr = JSON.parse(stdout);
+                    if (Array.isArray(arr)) {
+                        body = arr
+                            .map((s, i) => {
+                            const text = s.text ?? s.content ?? s.snippet ?? JSON.stringify(s);
+                            const src = s.source ?? s.doc_name ?? s.file ?? "";
+                            return `[${i + 1}]${src ? `  source: ${src}` : ""}\n${typeof text === "string" ? text : JSON.stringify(text)}`;
+                        })
+                            .join("\n\n");
+                        body = `${arr.length} hits:\n\n` + body;
+                    }
+                }
+                catch {
+                    /* non-JSON output returned as-is */
+                }
+            }
+            return json({
+                action: args.action,
+                mode: "cli",
+                kb: args.kb,
+                query: args.query,
+                text: truncate(body, maxChars),
+            });
+        },
+    }));
+    // ---------- Tool 3: archive learning notes to a server notebook ----------
+    ctx.tools.register(defineTool({
+        name: "deeptutor_note",
+        description: "Archive a Markdown learning note (study plan, deep-solve summary, wrong answers, etc.) to a DeepTutor notebook (auto-creates the notebook if missing). Record type: chat / question / research / solve.",
+        parameters: {
+            notebook: {
+                type: "string",
+                required: true,
+                description: "Notebook name, e.g. dotnet-learning (auto-created if missing)",
+            },
+            title: {
+                type: "string",
+                required: true,
+                description: "Record title, e.g. async/await state machine deep-dive notes",
+            },
+            type: {
+                type: "string",
+                enum: ["chat", "question", "research", "solve"],
+                description: "Record type, default chat",
+            },
+            content: {
+                type: "string",
+                required: true,
+                description: "Learning note content in Markdown",
+            },
+        },
+        output: {
+            schema: {
+                type: "object",
+                properties: {
+                    notebook: { type: "string" },
+                    nbId: { type: "string" },
+                    title: { type: "string" },
+                    mode: { type: "string" },
+                    text: { type: "string" },
+                },
+                additionalProperties: true,
+            },
+            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
+        },
+        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
+            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);
+            if (code !== 0) {
+                throw new Error(`[deeptutor_note failed] exit=${code}\n${truncate(stderr || stdout, 2000)}` +
+                    configGuide());
+            }
+            return json({
+                notebook: nbName,
+                title: args.title,
+                mode: "cli",
+                text: configHint() +
+                    `[note archived (CLI)] notebook=${nbName}, title=${args.title}, type=${recordType}\n${truncate((stdout ?? "").trim(), 2000)}`,
+            });
+        },
+    }));
+}

package/lib/turn.d.ts

@@ -0,0 +1,24 @@
+export interface TurnResult {
+    answer: string;
+    errors: string[];
+    toolCalls: string[];
+    sessionId?: string;
+    title?: string;
+}
+/** Fields both wsRunTurn and cliRunTurn read off the deeptutor_run tool params. */
+export interface RunParams {
+    prompt: string;
+    capability: string;
+    kbs?: string[];
+    tools?: string[];
+    session_id?: string;
+    language?: string;
+    config?: Record<string, unknown>;
+}
+/** Fold one event (WS or CLI JSONL) 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>;
+/** Execute one turn via the CLI (local or SSH). */
+export declare function cliRunTurn(params: RunParams, timeoutMs: number, signal?: AbortSignal): Promise<TurnResult>;
+export declare const fmtTurnResult: (capability: string, r: TurnResult, maxChars: number) => string;

package/lib/turn.js

@@ -0,0 +1,159 @@
+/**
+ * DeepTutor bridge: one learning "turn" — running a capability over WebSocket (HTTP mode)
+ * or the CLI (fallback), and shared JSONL/WS event parsing + result formatting.
+ */
+import { API_BASE, 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. */
+export function collectEvent(state, e) {
+    if (e.type === "content" && typeof e.content === "string")
+        state.answer += e.content;
+    else if (e.type === "result" && typeof e.metadata?.response === "string")
+        state.answer = e.metadata.response;
+    else if (e.type === "error")
+        state.errors.push(typeof e.content === "string" ? e.content : JSON.stringify(e.metadata ?? ""));
+    else if (e.type === "tool_call")
+        state.toolCalls.push(typeof e.content === "string" ? e.content : String(e.metadata?.name ?? ""));
+    else if (e.type === "session_meta" && e.metadata?.title)
+        state.title = e.metadata.title;
+    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"));
+            });
+        };
+    });
+}
+/** Execute one turn via the CLI (local or SSH). */
+export async function cliRunTurn(params, timeoutMs, signal) {
+    const argv = ["run", params.capability, params.prompt, "--format", "json"];
+    for (const kb of params.kbs ?? [])
+        argv.push("--kb", kb);
+    for (const t of params.tools ?? [])
+        argv.push("--tool", t);
+    if (params.session_id)
+        argv.push("--session", params.session_id);
+    if (params.language)
+        argv.push("--language", params.language);
+    for (const [k, v] of Object.entries(params.config ?? {}))
+        argv.push("--config", `${k}=${typeof v === "object" ? JSON.stringify(v) : v}`);
+    const { stdout, stderr, code, killed } = await runCli(argv, { signal, timeoutMs });
+    if (killed)
+        throw new Error(`CLI execution timed out (${Math.round(timeoutMs / 1000)}s)`);
+    if (code !== 0)
+        throw new Error(`CLI exit=${code}: ${stderr || "(no stderr)"}`);
+    const state = { answer: "", errors: [], toolCalls: [] };
+    for (const line of stdout.split("\n")) {
+        if (!line.trim())
+            continue;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        collectEvent(state, e);
+    }
+    return state;
+}
+export const fmtTurnResult = (capability, r, maxChars) => {
+    const parts = [];
+    parts.push(`[deeptutor ${capability} done]`);
+    if (r.sessionId)
+        parts.push(`- session_id: ${r.sessionId} (pass session_id in later turns to continue this context)`);
+    if (r.title)
+        parts.push(`- session title: ${r.title}`);
+    if (r.toolCalls.length)
+        parts.push(`- tools used: ${[...new Set(r.toolCalls)].join(", ")}`);
+    if (r.errors.length)
+        parts.push(`- note (some steps failed): ${r.errors.slice(0, 3).join(" | ")}`);
+    parts.push(`\n===== Answer =====\n${truncate(r.answer || "(no answer)", maxChars)}`);
+    return parts.join("\n");
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "dsh-deeptutor",
+  "version": "0.1.0",
+  "description": "DeepTutor bridge bundle for DeepSeek Harness: learning capabilities, knowledge bases, and note archiving (HTTP/WS first, CLI fallback; auto-adapts local/remote deployment).",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "dsh-bundle",
+    "deeptutor",
+    "tutoring",
+    "rag",
+    "agent"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "scripts",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build && npm run typecheck",
+    "pack:check": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3"
+  }
+}