dsh-deeptutor 0.2.0 → 0.3.0

package/src/cli-policy.ts

@@ -0,0 +1,99 @@
+/**
+ * DeepTutor bridge: safety tiers for the generic `deeptutor_cli` passthrough.
+ *
+ * The passthrough exists so the plugin never has to mirror DeepTutor's command
+ * surface: whatever the installed CLI offers is reachable, and the agent learns
+ * it from `--help`. The price is that the plugin cannot know what a command it
+ * has never seen does, so the default for anything unrecognised is "needs the
+ * user's explicit go-ahead" rather than "run".
+ *
+ *   read     run right away: help, and commands whose verb only reads
+ *   confirm  run only with confirm=true (writes, and every verb not listed here)
+ *   blocked  never run: destructive verbs, and interactive / long-running
+ *            commands that would hang a non-interactive tool call
+ */
+
+export type CliTier = "read" | "confirm" | "blocked";
+
+export interface CliVerdict {
+  tier: CliTier;
+  reason: string;
+}
+
+/** Top-level commands that start a REPL, a server, a launcher or a setup wizard. */
+const INTERACTIVE_TOP = new Set(["chat", "start", "stop", "serve", "init"]);
+
+/** Verbs that only read. Matched against the subcommand (or a single-command top level). */
+const READ_VERBS = new Set([
+  "list",
+  "show",
+  "info",
+  "search",
+  "state",
+  "status",
+  "doctor",
+  "get",
+  "view",
+]);
+
+/** Verbs that delete, reset or roll back state, or need an interactive login. */
+const BLOCKED_VERB =
+  /^(delete|remove|remove-.+|clear|uninstall|rollback|purge|reset|drop|wipe|prune|login|logout)$/;
+
+/** Commands the plugin's own tools run without confirmation; same rule here. */
+const READ_TOP = new Set(["doctor", "run"]);
+
+/** Leading positional words (the command path), stopping at the first option. */
+export function commandPath(args: readonly string[]): string[] {
+  const path: string[] = [];
+  for (const a of args) {
+    if (a.startsWith("-")) break;
+    path.push(a);
+  }
+  return path;
+}
+
+/** Classify one `deeptutor <args>` invocation. Pure; unit-tested. */
+export function classifyCliArgs(args: readonly string[]): CliVerdict {
+  if (args.length === 0) {
+    return { tier: "read", reason: "no arguments prints the top-level help" };
+  }
+  if (args.includes("--help") || args.includes("-h")) {
+    return { tier: "read", reason: "--help only prints usage" };
+  }
+  const path = commandPath(args);
+  const [top, sub] = path;
+  if (!top) {
+    return { tier: "confirm", reason: "options without a command" };
+  }
+  if (INTERACTIVE_TOP.has(top)) {
+    return {
+      tier: "blocked",
+      reason: `\`deeptutor ${top}\` is interactive or long-running and would hang a tool call; run it in a terminal yourself`,
+    };
+  }
+  for (const word of [top, sub]) {
+    if (word && BLOCKED_VERB.test(word)) {
+      return {
+        tier: "blocked",
+        reason: `\`${word}\` deletes, resets or logs in; run it in a terminal yourself if you really mean it`,
+      };
+    }
+  }
+  if (READ_TOP.has(top)) {
+    return { tier: "read", reason: `\`deeptutor ${top}\` is a read-only or learning command` };
+  }
+  if (sub && (READ_VERBS.has(sub) || sub.startsWith("list-"))) {
+    return { tier: "read", reason: `\`${sub}\` only reads` };
+  }
+  if (!sub && path.length === 1) {
+    return {
+      tier: "confirm",
+      reason: `\`deeptutor ${top}\` without a subcommand; use --help to see what it does`,
+    };
+  }
+  return {
+    tier: "confirm",
+    reason: `\`${[top, sub].filter(Boolean).join(" ")}\` may change DeepTutor state`,
+  };
+}

package/src/config.ts

@@ -56,15 +56,5 @@ export function configGuide(): string {
   );
 }
 
-export const CAPABILITIES = [
-  "chat",
-  "deep_solve",
-  "deep_question",
-  "deep_research",
-  "visualize",
-  "math_animator",
-  "mastery_path",
-] as const;
-
 export const truncate = (s: string, n: number) =>
   s.length > n ? s.slice(0, n) + `\n…[truncated, ${s.length} chars total]` : s;

package/src/discovery.ts

@@ -0,0 +1,112 @@
+/**
+ * DeepTutor bridge: runtime discovery of the capabilities a deployment offers.
+ *
+ * DeepTutor 1.7 ships capabilities as optional modules, so the set differs per
+ * deployment and grows with every release. Instead of a hard-coded enum the
+ * plugin asks `deeptutor module list` (JSON) which modules are ready and what
+ * capabilities they provide, and caches the answer for a few minutes.
+ *
+ * Discovery is advisory: a capability that no module lists may still come from a
+ * DeepTutor plugin, so an unknown name is passed through to the CLI. Only a
+ * capability whose module is known but not ready is refused up front, because
+ * that run is certain to fail and the reason is worth telling the agent.
+ */
+import { runCli, type CliResult } from "./cli-exec.ts";
+
+export interface ModuleInfo {
+  id: string;
+  ready: boolean;
+  capabilities: string[];
+  issues: string[];
+}
+
+export interface CapabilityIndex {
+  /** Capabilities whose module is installed, enabled and ready. */
+  ready: string[];
+  /** Capabilities whose module exists but is not ready → module id + reason. */
+  unavailable: Record<string, { module: string; reason: string }>;
+}
+
+/** Parse `deeptutor module list` output (a JSON array). Tolerates leading noise. Pure. */
+export function parseModuleList(stdout: string): ModuleInfo[] | undefined {
+  const start = stdout.indexOf("[");
+  if (start < 0) return undefined;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(stdout.slice(start));
+  } catch {
+    return undefined;
+  }
+  if (!Array.isArray(raw)) return undefined;
+  const out: ModuleInfo[] = [];
+  for (const m of raw) {
+    if (!m || typeof m !== "object" || typeof (m as any).id !== "string") continue;
+    const r = m as Record<string, unknown>;
+    out.push({
+      id: r.id as string,
+      ready: r.installed === true && r.enabled === true && r.ready === true,
+      capabilities: Array.isArray(r.capabilities)
+        ? r.capabilities.filter((c): c is string => typeof c === "string")
+        : [],
+      issues: Array.isArray(r.issues) ? r.issues.map((i) => String(i)) : [],
+    });
+  }
+  return out;
+}
+
+/** Fold module infos into a capability index. Pure. */
+export function indexCapabilities(modules: ModuleInfo[]): CapabilityIndex {
+  const ready = new Set<string>();
+  const unavailable: CapabilityIndex["unavailable"] = {};
+  for (const m of modules) {
+    for (const cap of m.capabilities) {
+      if (m.ready) ready.add(cap);
+      else
+        unavailable[cap] = {
+          module: m.id,
+          reason: m.issues.length ? m.issues.join("; ") : "module not installed or not enabled",
+        };
+    }
+  }
+  for (const cap of ready) delete unavailable[cap];
+  return { ready: [...ready].sort(), unavailable };
+}
+
+const CACHE_MS = 5 * 60_000;
+let cache: { at: number; index: CapabilityIndex } | undefined;
+
+/**
+ * Current capability index, cached for 5 minutes. Returns undefined when the
+ * deployment cannot tell (old DeepTutor without `module list`, CLI unreachable).
+ */
+export async function discoverCapabilities(
+  signal?: AbortSignal,
+  run: (args: string[], opts: { signal?: AbortSignal; timeoutMs?: number }) => Promise<CliResult> = runCli,
+  now: () => number = Date.now,
+): Promise<CapabilityIndex | undefined> {
+  if (cache && now() - cache.at < CACHE_MS) return cache.index;
+  const res = await run(["module", "list"], { signal, timeoutMs: 60_000 });
+  if (res.code !== 0) return undefined;
+  const modules = parseModuleList(res.stdout);
+  if (!modules) return undefined;
+  const index = indexCapabilities(modules);
+  cache = { at: now(), index };
+  return index;
+}
+
+/** Test hook: forget the cached index. */
+export function resetCapabilityCache() {
+  cache = undefined;
+}
+
+/** One line listing the ready capabilities, for tool results and errors. */
+export function describeCapabilities(index: CapabilityIndex | undefined): string {
+  if (!index) return "Available capabilities: unknown (run `deeptutor module list` to check).";
+  const off = Object.entries(index.unavailable)
+    .map(([cap, u]) => `${cap} (module ${u.module}: ${u.reason})`)
+    .join(", ");
+  return (
+    `Available capabilities: ${index.ready.join(", ") || "(none)"}` +
+    (off ? `\nNot ready on this deployment: ${off}` : "")
+  );
+}

package/src/index.ts

@@ -1,16 +1,17 @@
 /**
  * DeepTutor bridge plugin for DeepSeek Harness (dsh).
  *
- * Registers three model-facing tools:
+ * Registers the host-neutral tools from src/tools.ts:
  *   - deeptutor_run  — execute a DeepTutor learning capability
  *   - deeptutor_kb   — list / search / info knowledge bases
  *   - deeptutor_note — archive a Markdown learning note to a server notebook
+ *   - deeptutor_cli  — any other DeepTutor CLI command, behind safety tiers
+ *
+ * The same tools are served to MCP clients (Claude Code, …) by src/mcp.ts.
  *
  * Transport: every tool drives the deeptutor CLI.
  *   - Local: DEEPTUTOR_SSH_HOST unset → runs the local CLI (DEEPTUTOR_LOCAL_BIN).
  *   - Remote: DEEPTUTOR_SSH_HOST set → runs the server's CLI over SSH.
- * The HTTP/WS API was dropped: DeepTutor 1.7 moved it off /api/v1 and put it behind
- * a login, so the old probe always 404'd and cost ~30s per call before the CLI ran anyway.
  *
  * Env config (agent-agnostic): DEEPTUTOR_SSH_HOST / DEEPTUTOR_LOCAL_BIN /
  * DEEPTUTOR_REMOTE_BIN / DEEPTUTOR_REMOTE_HOME — see src/config.ts and
@@ -18,329 +19,41 @@
  */
 import type { Context } from "@deepseek-ai/cordis";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { CAPABILITIES, configGuide, configHint, SSH_HOST, truncate } from "./config.ts";
-import { cliNoteLocal, cliNoteRemote, runCli } from "./cli-exec.ts";
-import { renderHtml } from "./html-render.ts";
-import { cliRunTurn, fmtTurnResult } from "./turn.ts";
 import { HTML_DOC_SCRIPT } from "./html-render.ts";
+import { TOOLS } from "./tools.ts";
 
 export const name = "dsh-deeptutor";
 export const inject = ["tools"] as const;
 
-/** Drop keys whose value is `undefined` so the canonical JSON value stays lossless-JSON. */
-type Jsonify<T extends Record<string, unknown>> = {
-  [K in keyof T as T[K] extends undefined ? never : K]: Exclude<T[K], undefined>;
-};
-function json<T extends Record<string, unknown>>(o: T): Jsonify<T> {
+/** Drop undefined values so the canonical JSON value stays lossless-JSON. */
+function json(o: Record<string, unknown>): { text: string } & Record<string, any> {
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(o)) if (v !== undefined) out[k] = v;
-  return out as Jsonify<T>;
+  return out as { text: string };
 }
 
+const OUTPUT = {
+  schema: {
+    type: "object",
+    properties: { text: { type: "string" } },
+    additionalProperties: true,
+  },
+  render: (_args: unknown, value: { text?: string }) => [{ type: "text" as const, text: value.text ?? "" }],
+} as const;
+
 export function apply(ctx: Context) {
   console.log(`[dsh-deeptutor] plugin loaded (html script: ${HTML_DOC_SCRIPT})`);
-
-  // ---------- 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 {
-          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: any) {
-          if (exec.signal.aborted) {
-            // user cancelled mid-CLI-run: report it as a cancellation, not a failure
-            throw new Error("[deeptutor_run cancelled]");
-          }
-          throw new Error(
-            configGuide() +
-              `[deeptutor_run failed] ${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 (applied locally to the CLI search result; the deeptutor CLI has no --top-k flag)",
-        },
-        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;
-        // 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: string[];
-        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",
-          ];
-        }
-        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 parsed = JSON.parse(stdout);
-            const fmtHit = (s: any, i: number) => {
-              const text = s.text ?? s.content ?? s.snippet ?? JSON.stringify(s);
-              const src = s.source ?? s.doc_name ?? s.file ?? "";
-              const title = s.title ? `  title: ${s.title}` : "";
-              const score = typeof s.score === "number" ? `  score: ${s.score}` : "";
-              return `[${i + 1}]${src ? `  source: ${src}` : ""}${title}${score}\n${typeof text === "string" ? text : JSON.stringify(text)}`;
-            };
-            // Current deeptutor CLI (1.5.x) returns an object
-            // { query, answer, content, sources, provider }; older builds
-            // returned a bare array of hits. Accept both.
-            if (Array.isArray(parsed)) {
-              const hits = args.top_k ? parsed.slice(0, args.top_k) : parsed;
-              body = `${hits.length} hits:\n\n` + hits.map(fmtHit).join("\n\n");
-            } else if (parsed && typeof parsed === "object") {
-              const parts: string[] = [];
-              if (parsed.query) parts.push(`Query: ${parsed.query}`);
-              if (typeof parsed.answer === "string" && parsed.answer.trim())
-                parts.push(`Answer: ${parsed.answer.trim()}`);
-              const sources = Array.isArray(parsed.sources) ? parsed.sources : [];
-              const hits = args.top_k ? sources.slice(0, args.top_k) : sources;
-              parts.push(`${hits.length} hits:`);
-              parts.push(hits.map(fmtHit).join("\n\n"));
-              body = parts.join("\n\n");
-            }
-          } 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") as string;
-        const nbName = args.notebook.trim();
-        // 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);
-        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] notebook=${nbName}, title=${args.title}, type=${recordType}\n${truncate((stdout ?? "").trim(), 2000)}`,
-        });
-      },
-    }),
-  );
+  for (const tool of TOOLS) {
+    ctx.tools.register(
+      defineTool({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        output: OUTPUT,
+        async execute(args, exec) {
+          return json(await tool.execute(args as Record<string, any>, exec.signal)) as any;
+        },
+      }),
+    );
+  }
 }

package/src/mcp-main.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Entry point of the `dsh-deeptutor-mcp` bin: the DeepTutor tools as an MCP
+ * stdio server (Claude Code, Codex and other MCP clients).
+ */
+import { startStdioServer } from "./mcp.ts";
+
+startStdioServer();