dsh-deeptutor 0.2.1 → 0.3.1

package/lib/tools.js

@@ -0,0 +1,304 @@
+/**
+ * DeepTutor bridge: the agent-facing tools, defined once and host-neutral.
+ *
+ * Two hosts adapt these specs:
+ *   - dsh (src/index.ts) registers them through `defineTool`;
+ *   - MCP clients such as Claude Code (src/mcp.ts) list and call them over stdio.
+ *
+ * Parameter specs use the dsh-tools shape (JSON-Schema-like, `required: true`
+ * on the property) so dsh can infer argument types; `toJsonSchema` turns them
+ * into plain JSON Schema for MCP.
+ *
+ * The four tools split the work like this:
+ *   deeptutor_run   one learning turn (event folding, session reuse, HTML render)
+ *   deeptutor_kb    list / search / info knowledge bases (hit formatting)
+ *   deeptutor_note  archive Markdown to a notebook (find-or-create, file upload)
+ *   deeptutor_cli   any other CLI command, discovered from --help, behind the
+ *                   safety tiers in cli-policy.ts
+ */
+import { cliNoteLocal, cliNoteRemote, runCli } from "./cli-exec.js";
+import { classifyCliArgs } from "./cli-policy.js";
+import { configGuide, configHint, SSH_HOST, truncate } from "./config.js";
+import { describeCapabilities, discoverCapabilities } from "./discovery.js";
+import { renderHtml } from "./html-render.js";
+import { cliRunTurn, fmtTurnResult } from "./turn.js";
+/** Plain JSON Schema (object) for one tool's parameters. Pure. */
+export function toJsonSchema(params) {
+    const properties = {};
+    const required = [];
+    for (const [key, spec] of Object.entries(params)) {
+        const { required: isRequired, ...schema } = spec;
+        properties[key] = schema;
+        if (isRequired)
+            required.push(key);
+    }
+    return { type: "object", properties, required, additionalProperties: false };
+}
+/** Required-parameter and basic type check (MCP clients may skip schema validation). Pure. */
+export function validateArgs(params, args) {
+    const problems = [];
+    for (const [key, spec] of Object.entries(params)) {
+        const v = args[key];
+        if (v === undefined || v === null) {
+            if (spec.required)
+                problems.push(`missing required parameter "${key}"`);
+            continue;
+        }
+        const ok = spec.type === "array"
+            ? Array.isArray(v) && v.every((x) => typeof x === "string")
+            : spec.type === "object"
+                ? typeof v === "object" && !Array.isArray(v)
+                : typeof v === spec.type;
+        if (!ok)
+            problems.push(`parameter "${key}" must be ${spec.type === "array" ? "an array of strings" : `a ${spec.type}`}`);
+        else if (spec.type === "string" && spec.enum && !spec.enum.includes(v))
+            problems.push(`parameter "${key}" must be one of: ${spec.enum.join(", ")}`);
+    }
+    return problems;
+}
+// ---------- deeptutor_run ----------
+const runTool = {
+    name: "deeptutor_run",
+    description: "Execute one learning call on the DeepTutor service, e.g. deep_solve (in-depth explanation), deep_question (self-test questions), deep_research, chat, mastery_path (learning path), visualize. The capability set depends on the deployment and its installed modules: list it with deeptutor_cli args=[\"module\",\"list\"] (capabilities of modules that are ready). Can mount knowledge bases (kbs) and tools (rag, web_search, …; list them with deeptutor_cli args=[\"plugin\",\"list\"]). Returns the final answer plus session_id; pass session_id in later turns to continue the context.",
+    parameters: {
+        capability: {
+            type: "string",
+            required: true,
+            description: "Capability name, e.g. deep_solve / deep_question / deep_research / chat / mastery_path / visualize. Not a fixed list: whatever the deployment's ready modules provide.",
+        },
+        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 action=list first; never guess names)",
+        },
+        tools: {
+            type: "array",
+            items: { type: "string" },
+            description: "Tools to enable, e.g. rag (KB retrieval), web_search, reason, brainstorm, code_execution",
+        },
+        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, default 30000" },
+        html: {
+            type: "string",
+            description: "Optional output path for a self-contained local HTML render of the answer (also writes the companion .md next to it), e.g. data/study/abstract-class/knowledge.html. Relative paths resolve against the agent's working directory. Set it when the user wants browsable/printable study material.",
+        },
+        html_title: { type: "string", description: "HTML page title (default: derived from the html file name)" },
+    },
+    async execute(args, signal) {
+        const timeoutMs = (args.timeout ?? 600) * 1000;
+        const maxChars = args.max_chars ?? 30000;
+        const capability = String(args.capability).trim();
+        const index = await discoverCapabilities(signal).catch(() => undefined);
+        const off = index?.unavailable[capability];
+        if (off) {
+            throw new Error(`[deeptutor_run] capability "${capability}" is not ready on this deployment ` +
+                `(module ${off.module}: ${off.reason}).\n${describeCapabilities(index)}`);
+        }
+        try {
+            const r = await cliRunTurn({ ...args, capability }, timeoutMs, signal);
+            const htmlNote = await renderHtml(args, r.answer);
+            return {
+                mode: "cli",
+                sessionId: r.sessionId,
+                toolCalls: r.toolCalls,
+                errors: r.errors,
+                text: configHint() + fmtTurnResult(capability, r, maxChars) + htmlNote,
+            };
+        }
+        catch (err) {
+            if (signal.aborted)
+                throw new Error("[deeptutor_run cancelled]");
+            const known = index && !index.ready.includes(capability) ? `\n${describeCapabilities(index)}` : "";
+            throw new Error(configGuide() + `[deeptutor_run failed] ${err?.message ?? String(err)}${known}`);
+        }
+    },
+};
+// ---------- deeptutor_kb ----------
+const kbTool = {
+    name: "deeptutor_kb",
+    description: "Search DeepTutor knowledge bases: list all bases, search inside a base (RAG hit snippets), info for details. Search the user's personal knowledge bases before generating learning content and combine the hits with authoritative sources. Other kb commands (create, add, sources, eval…) go through deeptutor_cli.",
+    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)" },
+        mode: { type: "string", enum: ["hybrid", "dense", "sparse"], description: "Retrieval mode, default hybrid" },
+        top_k: {
+            type: "number",
+            description: "Number of hits to return, default all (applied locally; the CLI has no --top-k flag)",
+        },
+        max_chars: { type: "number", description: "Max characters of the returned content, default 30000" },
+    },
+    async execute(args, signal) {
+        const maxChars = args.max_chars ?? 30000;
+        if ((args.action === "search" || args.action === "info") && !args.kb) {
+            throw new Error(`[deeptutor_kb] action=${args.action} needs kb`);
+        }
+        if (args.action === "search" && !args.query)
+            throw new Error("[deeptutor_kb] action=search needs query");
+        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"];
+        const { stdout, stderr, code, killed } = await runCli(argv, { 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")
+            body = formatSearch(stdout, args.top_k) ?? body;
+        return { action: args.action, mode: "cli", kb: args.kb, query: args.query, text: truncate(body, maxChars) };
+    },
+};
+/** Format `kb search --format json` output; undefined when it is not JSON. Exported for tests. */
+export function formatSearch(stdout, topK) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+    const fmtHit = (s, i) => {
+        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)}`;
+    };
+    // The CLI returns { query, answer, content, sources, provider }; older builds a bare array.
+    if (Array.isArray(parsed)) {
+        const hits = topK ? parsed.slice(0, topK) : parsed;
+        return `${hits.length} hits:\n\n` + hits.map(fmtHit).join("\n\n");
+    }
+    if (parsed && typeof parsed === "object") {
+        const parts = [];
+        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 = topK ? sources.slice(0, topK) : sources;
+        parts.push(`${hits.length} hits:`);
+        parts.push(hits.map(fmtHit).join("\n\n"));
+        return parts.join("\n\n");
+    }
+    return undefined;
+}
+// ---------- deeptutor_note ----------
+const noteTool = {
+    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). Only when the user asks to save/archive notes.",
+    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" },
+        type: {
+            type: "string",
+            enum: ["chat", "question", "research", "solve"],
+            description: "Record type, default chat",
+        },
+        content: { type: "string", required: true, description: "Learning note content in Markdown" },
+    },
+    async execute(args, signal) {
+        const recordType = (args.type ?? "chat");
+        const nbName = String(args.notebook).trim();
+        const { stdout, stderr, code } = SSH_HOST
+            ? await cliNoteRemote(nbName, args.title, recordType, args.content, signal)
+            : await cliNoteLocal(nbName, args.title, recordType, args.content, signal);
+        if (code !== 0) {
+            throw new Error(`[deeptutor_note failed] exit=${code}\n${truncate(stderr || stdout, 2000)}` + configGuide());
+        }
+        return {
+            notebook: nbName,
+            title: args.title,
+            mode: "cli",
+            text: configHint() +
+                `[note archived] notebook=${nbName}, title=${args.title}, type=${recordType}\n${truncate((stdout ?? "").trim(), 2000)}`,
+        };
+    },
+};
+// ---------- deeptutor_cli ----------
+/**
+ * Rich pads every line to the terminal width; drop that padding and blank-line
+ * runs so wide output does not waste the model's context. Pure; exported for tests.
+ */
+export function tidyOutput(s) {
+    return s
+        .split(/\r?\n/)
+        .map((l) => l.trimEnd())
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+/**
+ * Wider than Rich's 80-column default so list tables keep more of each cell,
+ * but not so wide that help boxes (which always span the full width) bloat.
+ */
+const CLI_ENV = { COLUMNS: "120", NO_COLOR: "1", TERM: "dumb" };
+const cliTool = {
+    name: "deeptutor_cli",
+    description: "Run any DeepTutor CLI command: `deeptutor <args>` (locally or over SSH, same as the other tools). Use it for everything the dedicated tools do not cover, and discover commands from the CLI itself instead of guessing: args=[\"--help\"], then [\"<command>\",\"--help\"]. Read-only commands (help, list/show/info/search/state/status, doctor, run) execute directly. Any other command may change DeepTutor state and needs confirm=true, which you may only set after the user explicitly asked for that change. Destructive commands (delete, remove, clear, uninstall, rollback…) and interactive ones (chat, start, serve, init, login) are refused; tell the user to run those in a terminal.",
+    parameters: {
+        args: {
+            type: "array",
+            items: { type: "string" },
+            required: true,
+            description: "Arguments after `deeptutor`, one per item, e.g. [\"kb\",\"list-sources\",\"dotnet\"] or [\"notebook\",\"show\",\"sqlserver-learning\"]",
+        },
+        confirm: {
+            type: "boolean",
+            description: "Set true only when the user explicitly asked for this state-changing command",
+        },
+        timeout: { type: "number", description: "Timeout in seconds, default 120" },
+        max_chars: { type: "number", description: "Max characters of output returned, default 30000" },
+    },
+    async execute(args, signal) {
+        const argv = args.args.map(String);
+        const verdict = classifyCliArgs(argv);
+        const shown = `deeptutor ${argv.join(" ")}`.trim();
+        if (verdict.tier === "blocked")
+            throw new Error(`[deeptutor_cli refused] ${shown}: ${verdict.reason}`);
+        if (verdict.tier === "confirm" && args.confirm !== true) {
+            throw new Error(`[deeptutor_cli needs confirmation] ${shown}: ${verdict.reason}. ` +
+                "Ask the user; retry with confirm=true only after they explicitly approve this command.");
+        }
+        const maxChars = args.max_chars ?? 30000;
+        const { stdout, stderr, code, killed } = await runCli(argv, {
+            signal,
+            timeoutMs: (args.timeout ?? 120) * 1000,
+            env: CLI_ENV,
+        });
+        if (killed)
+            throw new Error(signal.aborted ? "[deeptutor_cli cancelled]" : `[deeptutor_cli timed out] ${shown}`);
+        const out = tidyOutput([stdout, stderr ? `--- stderr ---\n${stderr}` : ""].filter(Boolean).join("\n"));
+        const text = `[${shown}] exit=${code}\n${truncate(out || "(no output)", maxChars)}`;
+        if (code !== 0)
+            throw new Error(code === 127 ? text + configGuide() : text);
+        return { args: argv, tier: verdict.tier, exitCode: code, text };
+    },
+};
+export const TOOLS = [runTool, kbTool, noteTool, cliTool];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-deeptutor",
-  "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).",
+  "version": "0.3.1",
+  "description": "Learning assistant extension for DeepSeek Harness (dsh) and Claude Code (MCP): DeepTutor tutoring for your agent: deep explanations, self-test questions, learning paths, personal knowledge-base search (RAG), note archiving, and any other DeepTutor CLI command (drives the DeepTutor CLI locally or over SSH).",
   "keywords": [
     "dsh",
     "dsh-plugin",
@@ -9,7 +9,9 @@
     "deeptutor",
     "tutoring",
     "rag",
-    "agent"
+    "agent",
+    "mcp",
+    "claude-code"
   ],
   "license": "MIT",
   "repository": {
@@ -28,7 +30,8 @@
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "bin": {
-    "dsh-deeptutor": "scripts/install-profile.mjs"
+    "dsh-deeptutor": "scripts/install-profile.mjs",
+    "dsh-deeptutor-mcp": "lib/mcp-main.js"
   },
   "exports": {
     ".": {
@@ -61,7 +64,8 @@
     "typecheck": "tsc --noEmit",
     "prepack": "npm run build && npm run typecheck",
     "pack:check": "npm pack --dry-run",
-    "test": "node --test --experimental-strip-types"
+    "test": "node --test --experimental-strip-types",
+    "check:cli": "node --experimental-strip-types --no-warnings scripts/check-cli.ts"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",

package/scripts/check-cli.ts

@@ -0,0 +1,80 @@
+/**
+ * Drift check against a live DeepTutor deployment: `npm run check:cli`.
+ *
+ * The plugin discovers capabilities and commands at runtime, so a new DeepTutor
+ * release needs no plugin change, except when the few CLI shapes the dedicated
+ * tools are built on change. This script checks exactly those shapes on the
+ * deployment the DEEPTUTOR_* env vars point at, so a DeepTutor upgrade that
+ * breaks the plugin shows up here before a tool call fails.
+ *
+ * On Windows run it from PowerShell or cmd: Git Bash (MSYS) rewrites
+ * /home/... env values into C:/Program Files/Git/home/... before node sees them.
+ */
+import { runCli } from "../src/cli-exec.ts";
+import { SSH_HOST } from "../src/config.ts";
+import { parseModuleList } from "../src/discovery.ts";
+
+interface Check {
+  name: string;
+  args: string[];
+  /** Substrings that must appear in the output (Rich help tables are plain text inside). */
+  expect?: string[];
+  verify?: (stdout: string) => string | undefined;
+}
+
+const CHECKS: Check[] = [
+  { name: "top-level commands", args: ["--help"], expect: ["run", "kb", "notebook", "module"] },
+  {
+    name: "run options (deeptutor_run)",
+    args: ["run", "--help"],
+    expect: ["--format", "--kb", "--tool", "--session", "--language", "--config", "--config-json"],
+  },
+  { name: "kb subcommands (deeptutor_kb)", args: ["kb", "--help"], expect: ["list", "info", "search"] },
+  { name: "kb search options", args: ["kb", "search", "--help"], expect: ["--format", "--mode"] },
+  { name: "notebook subcommands (deeptutor_note)", args: ["notebook", "--help"], expect: ["list", "create", "add-md"] },
+  { name: "notebook add-md options", args: ["notebook", "add-md", "--help"], expect: ["--title", "--type"] },
+  { name: "notebook create options", args: ["notebook", "create", "--help"], expect: ["--description"] },
+  {
+    name: "module list JSON (capability discovery)",
+    args: ["module", "list"],
+    verify: (out) => {
+      const mods = parseModuleList(out);
+      if (!mods) return "output is not a JSON array";
+      if (!mods.some((m) => m.capabilities.length)) return "no module reports capabilities";
+      return undefined;
+    },
+  },
+  {
+    name: "kb list JSON",
+    args: ["kb", "list", "--format", "json"],
+    verify: (out) => {
+      try {
+        JSON.parse(out);
+        return undefined;
+      } catch {
+        return "output is not JSON";
+      }
+    },
+  },
+];
+
+const env = { COLUMNS: "120", NO_COLOR: "1", TERM: "dumb" };
+console.log(`Checking DeepTutor CLI (${SSH_HOST ? `remote via ${SSH_HOST}` : "local"})\n`);
+let failed = 0;
+for (const c of CHECKS) {
+  const res = await runCli(c.args, { timeoutMs: 90_000, env });
+  const out = res.stdout + "\n" + res.stderr;
+  const problems: string[] = [];
+  if (res.code !== 0) problems.push(`exit ${res.code}: ${res.stderr.trim().split("\n").slice(-3).join(" ")}`);
+  for (const s of c.expect ?? []) if (!out.includes(s)) problems.push(`missing "${s}"`);
+  const v = res.code === 0 ? c.verify?.(res.stdout) : undefined;
+  if (v) problems.push(v);
+  if (problems.length) {
+    failed++;
+    console.log(`✗ ${c.name}  (deeptutor ${c.args.join(" ")})\n    ${problems.join("\n    ")}`);
+  } else {
+    console.log(`✓ ${c.name}`);
+  }
+}
+console.log(failed ? `\n${failed} check(s) failed: the plugin's CLI assumptions drifted.` : "\nAll checks passed.");
+process.exit(failed ? 1 : 0);

package/scripts/mcp-launch.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Launcher for the DeepTutor MCP server, used by the Claude Code plugin
+ * (`mcpServers` in .claude-plugin/plugin.json → `node ${CLAUDE_PLUGIN_ROOT}/scripts/mcp-launch.mjs`).
+ * The config lives in plugin.json, not a root .mcp.json: Claude Code also reads
+ * a root .mcp.json as project-scope config whenever this repo is the working
+ * directory, where ${CLAUDE_PLUGIN_ROOT} is undefined.
+ *
+ * A plugin installed from the marketplace is a plain git checkout: it has the
+ * TypeScript sources but no compiled lib/ and no node_modules. The server has no
+ * runtime dependencies, so the launcher picks the first entry that works:
+ *
+ *   1. lib/mcp-main.js                  compiled build (npm install, or a dev checkout after `npm run build`)
+ *   2. src/mcp-main.ts                  the checkout's own sources, via Node's type stripping (Node >= 22.6)
+ *   3. npx dsh-deeptutor@<this version> the published package, for older Node
+ *
+ * 1 and 2 run exactly the code of the installed plugin version; 3 pins the npm
+ * package to the same version, so plugin and server never drift apart.
+ * stdin/stdout are inherited untouched: they carry the MCP protocol.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const lib = join(root, 'lib', 'mcp-main.js');
+const src = join(root, 'src', 'mcp-main.ts');
+
+/** Node >= 22.6 can run .ts with --experimental-strip-types (unflagged from 23.6). */
+export function supportsTypeStripping(version = process.versions.node) {
+  const [major, minor] = version.split('.').map(Number);
+  return major > 22 || (major === 22 && minor >= 6);
+}
+
+/** Pick the command that starts the server. Exported for tests. */
+export function pickLaunch({ hasLib, hasSrc, nodeVersion, version, platform = process.platform }) {
+  if (hasLib) return { command: process.execPath, args: [lib] };
+  if (hasSrc && supportsTypeStripping(nodeVersion)) {
+    return { command: process.execPath, args: ['--experimental-strip-types', '--no-warnings', src] };
+  }
+  const npxArgs = ['-y', '-p', `dsh-deeptutor@${version}`, 'dsh-deeptutor-mcp'];
+  // npx is a .cmd shim on Windows; spawning it needs a shell there.
+  return { command: 'npx', args: npxArgs, shell: platform === 'win32' };
+}
+
+function main() {
+  const version = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
+  const launch = pickLaunch({
+    hasLib: existsSync(lib),
+    hasSrc: existsSync(src),
+    nodeVersion: process.versions.node,
+    version,
+  });
+  const child = spawn(launch.command, launch.args, {
+    stdio: 'inherit',
+    shell: launch.shell ?? false,
+    windowsHide: true,
+  });
+  child.on('error', (err) => {
+    process.stderr.write(`[dsh-deeptutor mcp] failed to start ${launch.command}: ${err.message}\n`);
+    process.exit(1);
+  });
+  child.on('exit', (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+  for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => child.kill(sig));
+}
+
+// Run only when executed directly (tests import pickLaunch). realpath + lowercase:
+// Windows hands us drive letters and separators in whatever case the caller used.
+const same = (a, b) => realpathSync(a).toLowerCase() === realpathSync(b).toLowerCase();
+if (process.argv[1] && existsSync(process.argv[1]) && same(process.argv[1], fileURLToPath(import.meta.url))) main();

package/src/cli-exec.ts

@@ -107,14 +107,29 @@ function execFileResolved(
   });
 }
 
-async function sshExec(
-  argv: string[],
-  opts: { signal?: AbortSignal; timeoutMs?: number } = {},
-): Promise<CliResult> {
+/** Options shared by every CLI invocation. */
+export interface CliOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  /** Extra env vars for the deeptutor process (names must match [A-Z_][A-Z0-9_]*). */
+  env?: Record<string, string>;
+}
+
+const ENV_NAME = /^[A-Z_][A-Z0-9_]*$/;
+
+/** `export K='v'` lines for the remote script; values are single-quote escaped. */
+export function exportLines(env: Record<string, string> = {}): string[] {
+  return Object.entries(env)
+    .filter(([k]) => ENV_NAME.test(k))
+    .map(([k, v]) => `export ${k}='${v.replace(/'/g, `'\\''`)}'`);
+}
+
+async function sshExec(argv: string[], opts: CliOptions = {}): Promise<CliResult> {
   const payload = JSON.stringify({ argv, cwd: DEEPTUTOR_HOME });
   const script = [
     `export DEEPTUTOR_HOME=${DEEPTUTOR_HOME}`,
     "export DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=1",
+    ...exportLines(opts.env),
     "F=/tmp/dt_pi_$$",
     `echo '${b64(payload)}' | base64 -d > "$F.json"`,
     `echo '${b64(PY_RUNNER)}' | base64 -d > "$F.py"`,
@@ -145,10 +160,7 @@ async function sshExec(
  *   - Local deployment (SSH_HOST empty) → execute DEEPTUTOR_LOCAL_BIN locally.
  * args are deeptutor subcommand args (without the program name).
  */
-export async function runCli(
-  args: string[],
-  opts: { signal?: AbortSignal; timeoutMs?: number } = {},
-): Promise<CliResult> {
+export async function runCli(args: string[], opts: CliOptions = {}): Promise<CliResult> {
   if (SSH_HOST) {
     return sshExec([DEEPTUTOR_BIN, ...args], opts);
   }
@@ -159,7 +171,7 @@ export async function runCli(
   const res = await execFileResolved(cmd.file, cmd.args, {
     signal: opts.signal,
     timeoutMs: opts.timeoutMs,
-    env: { PYTHONUTF8: "1", PYTHONIOENCODING: "utf-8" },
+    env: { ...opts.env, PYTHONUTF8: "1", PYTHONIOENCODING: "utf-8" },
     windowsVerbatimArguments: cmd.windowsVerbatimArguments,
   });
   const out = res.stdout ?? "";

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;