dsh-session-eval 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.2.4 — 2026-10-11
+
+Feature release: eval-history report files.
+
+- New: `/eval-history --out PATH[.md|.json]` writes the history report to a Markdown or JSON file instead of only echoing it (contributed by @varshith84 in #4, merged as 117f918 after a maintainer rebase).
+
+# Changelog
+
+
 ## 0.2.3 — 2026-10-03
 
 Docs polish round (no runtime changes).
@@ -7,8 +16,6 @@ Docs polish round (no runtime changes).
 - Community section; bilingual issue templates (`.github/ISSUE_TEMPLATE/`).
 - English/Chinese README sections kept in sync.
 
-# Changelog
-
 ## 0.2.2 — 2026-10-02
 
 Contributor-first docs release.

package/README.md

@@ -91,6 +91,8 @@ Both are useful; they don't compete. Benchmarks test what you *predicted*; retro
 | `/eval-history [N]` | Grade the last N sessions in this workspace and show the trend |
 | `/eval-history … --json` | Machine-readable history report |
 
+Use `/eval-history --out report.md` to save the terminal card as Markdown, or add `--json` to save the JSON payload. Relative paths resolve against the current session workspace (the process working directory when unavailable). Parent directories must already exist; file errors are reported without creating directories. Existing output files are overwritten.
+
 `/eval-history` finds the sessions for you via the same `sessionQuery` seam `/archive` uses (scoped to the current workspace's `cwd`), grades each, and diffs the first against the last. `/eval-diff` remains the tool when you already know the two ids that matter.
 
 Typical use: grade the ten sessions before and after a plugin or prompt change; a persistent `Reliability` regression is an early warning that the change hurt real work, not just benchmarks.

package/README.zh.md

@@ -91,6 +91,8 @@ Notes:
 | `/eval-history [N]` | 本工作区最近 N 个会话成绩单 + 首末趋势 |
 | `/eval-history … --json` | 机器可读历史报告 |
 
+使用 `/eval-history --out report.md` 将终端卡片保存为 Markdown，添加 `--json` 则保存 JSON。相对路径基于当前会话工作目录（缺失时使用进程工作目录）。父目录必须已存在；写入失败会返回错误，不会创建目录。已存在的输出文件会被覆盖。
+
 `/eval-history` 通过与 `/archive` 相同的 `sessionQuery` 接缝自动找到会话（按当前工作区 `cwd` 过滤），逐个评级，并把首尾两个会话做趋势对比——不用再手动挑 id。已经知道两个关键 id 时用 `/eval-diff`。
 
 典型用法：换插件或 prompt 前后各评十个会话；`Reliability` 持续回归 = 改动伤害了真实工作的早期预警。

package/lib/index.d.ts

@@ -133,11 +133,12 @@ declare function executeEval(ctx: Context, invocation: CommandInvocation, seam?:
 declare function executeEvalDiff(ctx: Context, invocation: CommandInvocation, seam?: QuerySeam): Promise<CommandResult>;
 //#endregion
 //#region src/historyCommand.d.ts
-declare const EVAL_HISTORY_USAGE = "Usage: /eval-history [N] [--json]  (N = last N sessions, 1-20, default 5)";
+declare const EVAL_HISTORY_USAGE = "Usage: /eval-history [N] [--json] [--out PATH]  (N = last N sessions, 1-20, default 5)";
 /** Args for /eval-history. */
 interface EvalHistoryArgs {
   readonly count: number;
   readonly json: boolean;
+  readonly out?: string;
 }
 /** Parse /eval-history input; returns args or a usage-error string. */
 declare function parseEvalHistoryArgs(rawInput: string): EvalHistoryArgs | string;
@@ -177,7 +178,7 @@ declare function executeEvalHistory(ctx: Context, invocation: CommandInvocation,
  *
  * @module dsh-session-eval/version
  */
-declare const VERSION = "0.2.3";
+declare const VERSION = "0.2.4";
 //#endregion
 //#region src/index.d.ts
 declare const name = "session-eval";

package/lib/index.js

@@ -1,4 +1,6 @@
 import { SessionId } from "@deepseek-ai/dsh-session";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
 //#region src/metrics.ts
 /** Count a correction signal for every extra user message inside a consecutive-user run. */
 function countCorrections(events) {
@@ -227,7 +229,7 @@ function compareSessions(before, after) {
 *
 * @module dsh-session-eval/version
 */
-const VERSION = "0.2.3";
+const VERSION = "0.2.4";
 //#endregion
 //#region src/evalCommand.ts
 const EVAL_USAGE = "Usage: /eval [--id <sessionId>] [--json]";
@@ -327,14 +329,14 @@ async function executeEval(ctx, invocation, seam = ctx.sessionQuery) {
 	if (parsed.json === true) return {
 		kind: "success",
 		text: JSON.stringify({
-			generator: "dsh-session-eval v0.2.3",
+			generator: "dsh-session-eval v0.2.4",
 			metrics,
 			card
 		}, null, 2)
 	};
 	return {
 		kind: "success",
-		text: renderCard(card, "dsh-session-eval v0.2.3")
+		text: renderCard(card, "dsh-session-eval v0.2.4")
 	};
 }
 /** Execute /eval-diff against the session-query seam. */
@@ -358,25 +360,44 @@ async function executeEvalDiff(ctx, invocation, seam = ctx.sessionQuery) {
 	if (parsed.json === true) return {
 		kind: "success",
 		text: JSON.stringify({
-			generator: "dsh-session-eval v0.2.3",
+			generator: "dsh-session-eval v0.2.4",
 			report
 		}, null, 2)
 	};
 	return {
 		kind: "success",
-		text: renderTrend(report, "dsh-session-eval v0.2.3")
+		text: renderTrend(report, "dsh-session-eval v0.2.4")
 	};
 }
 //#endregion
 //#region src/historyCommand.ts
-const EVAL_HISTORY_USAGE = "Usage: /eval-history [N] [--json]  (N = last N sessions, 1-20, default 5)";
+/**
+* `/eval-history` — grade the last N sessions in this workspace and show the trend.
+*
+* Completes the regression-tracking story: `/eval-diff` compares two sessions
+* you already know about; this command finds them for you (via
+* `ctx.sessionQuery.listSessions()`, same seam as `/archive` in
+* dsh-session-export) and answers "is the trend improving?" out of the box.
+*
+* @module dsh-session-eval/historyCommand
+*/
+const EVAL_HISTORY_USAGE = "Usage: /eval-history [N] [--json] [--out PATH]  (N = last N sessions, 1-20, default 5)";
 /** Parse /eval-history input; returns args or a usage-error string. */
 function parseEvalHistoryArgs(rawInput) {
 	const tokens = rawInput.trim().split(/\s+/).filter((t) => t.length > 0);
 	let count = 5;
 	let json = false;
 	let sawCount = false;
-	for (const token of tokens) {
+	let out;
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (token === "--out") {
+			if (out !== void 0) return `--out may be given only once.\n${EVAL_HISTORY_USAGE}`;
+			const path = tokens[++i];
+			if (!path || path.startsWith("--")) return `--out requires a path.\n${EVAL_HISTORY_USAGE}`;
+			out = path;
+			continue;
+		}
 		if (token === "--json") {
 			if (json) return `--json may be given only once.\n${EVAL_HISTORY_USAGE}`;
 			json = true;
@@ -392,7 +413,8 @@ function parseEvalHistoryArgs(rawInput) {
 	}
 	return {
 		count,
-		json
+		json,
+		...out !== void 0 ? { out } : {}
 	};
 }
 function toMillis(createdAt) {
@@ -441,10 +463,6 @@ async function executeEvalHistory(ctx, invocation, seam = ctx.sessionQuery) {
 		id: String(header.id),
 		createdAt: toMillis(header.createdAt)
 	})).sort((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0)).slice(-parsed.count);
-	if (recent.length === 0) return {
-		kind: "success",
-		text: "No sessions found in this workspace; nothing to grade."
-	};
 	const entries = [];
 	for (const header of recent) {
 		let events;
@@ -468,16 +486,25 @@ async function executeEvalHistory(ctx, invocation, seam = ctx.sessionQuery) {
 		entries,
 		trend: entries.length >= 2 ? compareSessions(entries[0].metrics, entries[entries.length - 1].metrics) : null
 	};
-	if (parsed.json === true) return {
-		kind: "success",
-		text: JSON.stringify({
-			generator: `dsh-session-eval v${VERSION}`,
-			report
-		}, null, 2)
-	};
+	const text = parsed.json ? JSON.stringify({
+		generator: `dsh-session-eval v${VERSION}`,
+		report
+	}, null, 2) : renderHistory(report);
+	if (parsed.out !== void 0) {
+		const path = resolve(typeof ownCwd === "string" ? ownCwd : process.cwd(), parsed.out);
+		try {
+			const output = parsed.json ? text : `\`\`\`text\n${text}\n\`\`\``;
+			await writeFile(path, `${output}\n`, "utf8");
+		} catch (error) {
+			return {
+				kind: "error",
+				text: `Could not write history report to ${path}: ${error instanceof Error ? error.message : String(error)}`
+			};
+		}
+	}
 	return {
 		kind: "success",
-		text: renderHistory(report)
+		text
 	};
 }
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-session-eval",
   "description": "Retrospective agent-session evaluation for DeepSeek Harness: deterministic grade cards from persisted session logs, cross-session regression diffs, era comparison — no benchmark runs, no LLM judges.",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "publishConfig": {
     "access": "public"
   },