dsh-session-eval 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.3.0 — 2026-10-23
+
+Feature release: configurable grade bands (#1) and the history time window (#2).
+
+- New: a `gradeBands` config block overrides the default thresholds for any dimension, per-profile — `reliability` in error-rate percent, `reask` in corrections per 10 user turns, `toolLoad` as `[lowC, lowB, highC, highD]` calls per turn. Invalid config (unknown keys, wrong arity, non-numeric, negative, non-ascending) fails fast at plugin load with a readable error; defaults are unchanged when nothing is configured.
+- New: `/eval-history --since 24h|7d|30d` grades only sessions whose latest activity falls inside the window — filtered by last event time, not creation time. An empty window prints a clear message; without the flag the behavior is exactly as before.
+
+## 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 +23,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

@@ -65,7 +65,7 @@ All three read through the same trusted `ctx.sessionQuery` seam, so any persiste
 
 - **Local dev**: `npm ci && npm run typecheck && npm test && npm run bundle` (Node 20 or 22).
 - **Start in the source**: [`src/grade.ts`](src/grade.ts) (thresholds, grade cards), [`src/metrics.ts`](src/metrics.ts) (metric extraction), [`src/trend.ts`](src/trend.ts) (`/eval-history` trend logic). See [CONTRIBUTING.md](CONTRIBUTING.md) for the source map and first-PR suggestions.
-- **Open gaps**: [#1](https://github.com/kittimzhe/dsh-session-eval/issues/1) (configurable thresholds), [#2](https://github.com/kittimzhe/dsh-session-eval/issues/2) (`/eval-history --since`), [#3](https://github.com/kittimzhe/dsh-session-eval/issues/3) (`/eval-history --out`) — or browse [issues labeled `good first issue`](https://github.com/kittimzhe/dsh-session-eval/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
+- **Open gaps**: [#1](https://github.com/kittimzhe/dsh-session-eval/issues/1) (configurable thresholds) and [#2](https://github.com/kittimzhe/dsh-session-eval/issues/2) (`/eval-history --since`) shipped in v0.3.0 — browse [issues labeled `good first issue`](https://github.com/kittimzhe/dsh-session-eval/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
 - **Rules**: behavior changes need tests; doc changes must update `README.md` and `README.zh.md` in sync; version releases belong to the maintainer. Details: [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## How it differs from benchmark-style evaluation
@@ -90,9 +90,28 @@ Both are useful; they don't compete. Benchmarks test what you *predicted*; retro
 | `/eval-diff … --json` | Machine-readable trend report |
 | `/eval-history [N]` | Grade the last N sessions in this workspace and show the trend |
 | `/eval-history … --json` | Machine-readable history report |
+| `/eval-history --since 7d` | Grade only sessions with activity inside the window (`24h`, `30d` also parse) |
+
+`--since` filters by each session's **latest activity**, not its creation time: a session opened long ago but active an hour ago stays in the window; a freshly created but silent one drops out. With `--since 7d` the trend compares the first and last of the in-window set, and an empty window prints a clear message instead of a crash. Without the flag, behavior is exactly as before (last N sessions).
+
+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.
 
+## Configuring grade bands
+
+The thresholds are defaults, not laws. A `gradeBands` block under the plugin's config node (naturally per-profile) overrides any dimension — values are the A–D upper bounds, ascending:
+
+```yaml
+session-eval:
+  gradeBands:
+    reliability: [4, 8, 15, 30]   # tool error-rate percent
+    reask: [0, 2, 4, 8]           # corrections per 10 user turns
+    toolLoad: [0.1, 0.5, 8, 20]   # tool calls per turn: [lowC, lowB, highC, highD]
+```
+
+Any subset may be overridden; unlisted dimensions keep the documented defaults. Unknown keys, wrong arity, non-numeric, negative, or non-ascending values fail fast at plugin load with a readable error — sessions are never graded against bands nobody chose.
+
 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.
 
 ## Dimensions & thresholds

package/README.zh.md

@@ -65,7 +65,7 @@ Notes:
 
 - **本地开发**：`npm ci && npm run typecheck && npm test && npm run bundle`（Node 20 或 22）。
 - **源码入口**：[`src/grade.ts`](src/grade.ts)（阈值与等级卡）、[`src/metrics.ts`](src/metrics.ts)（指标提取）、[`src/trend.ts`](src/trend.ts)（`/eval-history` 趋势逻辑）。源码地图与第一次 PR 建议见 [CONTRIBUTING.md](CONTRIBUTING.md)。
-- **当前缺口**：[#1](https://github.com/kittimzhe/dsh-session-eval/issues/1)（阈值可配置）、[#2](https://github.com/kittimzhe/dsh-session-eval/issues/2)（`/eval-history --since`）、[#3](https://github.com/kittimzhe/dsh-session-eval/issues/3)（`/eval-history --out`）——或浏览 [`good first issue` 标签](https://github.com/kittimzhe/dsh-session-eval/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)。
+- **当前缺口**：[#1](https://github.com/kittimzhe/dsh-session-eval/issues/1)（阈值可配置）与 [#2](https://github.com/kittimzhe/dsh-session-eval/issues/2)（`/eval-history --since`）已在 v0.3.0 落地——或浏览 [`good first issue` 标签](https://github.com/kittimzhe/dsh-session-eval/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)。
 - **规矩**：行为变更必须带测试；文档必须 `README.md` 与 `README.zh.md` 同步改；版本发布由维护者执行。详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
 ## 与基准式评测（dsh-eval）的区别
@@ -90,11 +90,30 @@ Notes:
 | `/eval-diff … --json` | 机器可读趋势报告 |
 | `/eval-history [N]` | 本工作区最近 N 个会话成绩单 + 首末趋势 |
 | `/eval-history … --json` | 机器可读历史报告 |
+| `/eval-history --since 7d` | 只评窗口内有活动的会话（也支持 `24h`、`30d`） |
+
+`--since` 按**最新活动时间**过滤，而非创建时间：很久前打开但一小时前还活跃的会话留在窗口内；刚创建但一直沉默的会被排除。`--since 7d` 下趋势对比的是窗口内首末两个会话；窗口为空时打印明确提示而不是崩溃。不加该参数时行为与从前完全一致（最近 N 个）。
+
+使用 `/eval-history --out report.md` 将终端卡片保存为 Markdown，添加 `--json` 则保存 JSON。相对路径基于当前会话工作目录（缺失时使用进程工作目录）。父目录必须已存在；写入失败会返回错误，不会创建目录。已存在的输出文件会被覆盖。
 
 `/eval-history` 通过与 `/archive` 相同的 `sessionQuery` 接缝自动找到会话（按当前工作区 `cwd` 过滤），逐个评级，并把首尾两个会话做趋势对比——不用再手动挑 id。已经知道两个关键 id 时用 `/eval-diff`。
 
 典型用法：换插件或 prompt 前后各评十个会话；`Reliability` 持续回归 = 改动伤害了真实工作的早期预警。
 
+## 配置等级阈值
+
+阈值是默认值而非铁律。在插件配置节点下（天然按 profile 区分）加 `gradeBands` 块即可覆盖任意维度——值为 A–D 各档上限、升序：
+
+```yaml
+session-eval:
+  gradeBands:
+    reliability: [4, 8, 15, 30]   # 工具错误率百分比
+    reask: [0, 2, 4, 8]           # 每 10 个用户轮次的纠错次数
+    toolLoad: [0.1, 0.5, 8, 20]   # 每轮工具调用数：[lowC, lowB, highC, highD]
+```
+
+可只覆盖部分维度；未列出的保持文档默认值。未知键、元素个数不对、非数字、负数或非升序，都会在插件加载时以可读错误快速失败——绝不会对着没人选过的阈值评级。
+
 ## 维度与阈值（确定性，无裁判）
 
 | 维度 | 指标 | A | B | C | D | E |

package/lib/index.d.ts

@@ -92,8 +92,23 @@ declare function computeMetrics(sessionId: string, events: readonly EvalEvent[])
 declare function adaptEvents(raw: readonly unknown[]): EvalEvent[];
 //#endregion
 //#region src/grade.d.ts
-/** Grade one session deterministically. */
-declare function gradeSession(m: SessionMetrics): GradeCard;
+/**
+ * Grade bands per dimension, overridable from the plugin config (#1).
+ * Each array holds the A/B/C/D upper bounds in ascending order; anything
+ * above the D bound grades E. Reliability bounds are error-rate fractions,
+ * re-ask bounds are corrections per 10 user turns, tool-load bounds are
+ * calls per turn as [lowC, lowB, highC, highD].
+ */
+interface GradeBands {
+  readonly reliability: readonly [number, number, number, number];
+  readonly reask: readonly [number, number, number, number];
+  readonly toolLoad: readonly [number, number, number, number];
+}
+/**
+ * Grade one session deterministically. `bands` may override any subset of
+ * the dimensions; unspecified ones keep the documented defaults.
+ */
+declare function gradeSession(m: SessionMetrics, bands?: Partial<GradeBands>): GradeCard;
 //#endregion
 //#region src/trend.d.ts
 /** Compare two sessions dimension by dimension. */
@@ -128,16 +143,22 @@ interface QuerySeam {
   }>;
 }
 /** Execute /eval against the session-query seam. */
-declare function executeEval(ctx: Context, invocation: CommandInvocation, seam?: QuerySeam): Promise<CommandResult>;
+declare function executeEval(ctx: Context, invocation: CommandInvocation, seam?: QuerySeam, bands?: Partial<GradeBands>): Promise<CommandResult>;
 /** Execute /eval-diff against the session-query 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] [--since 24h|7d|30d]  (N = last N sessions, 1-20, default 5; --since grades only sessions whose latest activity falls inside the window)";
 /** Args for /eval-history. */
 interface EvalHistoryArgs {
   readonly count: number;
   readonly json: boolean;
+  readonly out?: string;
+  /** Time window from --since; grades only sessions whose latest activity falls inside. */
+  readonly since?: {
+    label: string;
+    ms: number;
+  };
 }
 /** Parse /eval-history input; returns args or a usage-error string. */
 declare function parseEvalHistoryArgs(rawInput: string): EvalHistoryArgs | string;
@@ -152,6 +173,8 @@ interface HistoryEntry {
 interface HistoryReport {
   readonly entries: readonly HistoryEntry[];
   readonly trend: TrendReport | null;
+  /** The --since label this report was filtered by, if any. */
+  readonly sinceLabel?: string;
 }
 /** The slice of sessionQuery this command consumes (structural, for testability). */
 interface HistorySeam {
@@ -169,7 +192,7 @@ interface HistorySeam {
 /** Render a history report as terminal text. */
 declare function renderHistory(report: HistoryReport): string;
 /** Execute /eval-history against the session-query seam. */
-declare function executeEvalHistory(ctx: Context, invocation: CommandInvocation, seam?: HistorySeam): Promise<CommandResult>;
+declare function executeEvalHistory(ctx: Context, invocation: CommandInvocation, seam?: HistorySeam, bands?: Partial<GradeBands>): Promise<CommandResult>;
 //#endregion
 //#region src/version.d.ts
 /**
@@ -177,12 +200,18 @@ declare function executeEvalHistory(ctx: Context, invocation: CommandInvocation,
  *
  * @module dsh-session-eval/version
  */
-declare const VERSION = "0.2.3";
+declare const VERSION = "0.3.0";
 //#endregion
 //#region src/index.d.ts
 declare const name = "session-eval";
 declare const inject: string[];
-/** Plugin entry: mount the /eval, /eval-diff and /eval-history commands. */
-declare function apply(ctx: Context): void;
+/**
+ * Plugin entry: mount the /eval, /eval-diff and /eval-history commands.
+ *
+ * `config` is the plugin's node in the host config tree (per-profile): its
+ * `gradeBands` block overrides the default grade thresholds — see config.ts.
+ * Invalid config fails fast here, at plugin load, rather than mid-grade.
+ */
+declare function apply(ctx: Context, config?: unknown): void;
 //#endregion
 export { type DimensionDelta, type DimensionGrade, EVAL_DIFF_USAGE, EVAL_HISTORY_USAGE, EVAL_USAGE, type EvalArgs, type EvalDiffArgs, type EvalEvent, type EvalEventKind, type EvalHistoryArgs, type Grade, type GradeCard, type HistoryEntry, type HistoryReport, type HistorySeam, type SessionMetrics, type TrendReport, VERSION, adaptEvents, apply, compareSessions, computeMetrics, executeEval, executeEvalDiff, executeEvalHistory, gradeSession, id8, inject, name, parseEvalArgs, parseEvalDiffArgs, parseEvalHistoryArgs, renderCard, renderHistory, renderTrend };

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) {
@@ -84,27 +86,35 @@ function readBool(source, key) {
 }
 //#endregion
 //#region src/grade.ts
-/** Reliability thresholds on tool error rate (fraction). */
-const RELIABILITY = [
-	["A", .05],
-	["B", .1],
-	["C", .2],
-	["D", .35]
-];
-/** Re-ask thresholds: corrections per 10 user turns. */
-const REASK = [
-	["A", 0],
-	["B", 1],
-	["C", 2],
-	["D", 4]
-];
-/** Tool-load thresholds: tool calls per user turn (both churn extremes graded). */
-const TOOL_LOAD_LOW_B = .5;
-const TOOL_LOAD_LOW_C = .1;
-const TOOL_LOAD_HIGH_C = 8;
-const TOOL_LOAD_HIGH_D = 20;
-function gradeBy(rate, table) {
-	for (const [grade, max] of table) if (rate <= max) return grade;
+/** The documented defaults; unchanged when no config is given. */
+const DEFAULT_GRADE_BANDS = {
+	reliability: [
+		.05,
+		.1,
+		.2,
+		.35
+	],
+	reask: [
+		0,
+		1,
+		2,
+		4
+	],
+	toolLoad: [
+		.1,
+		.5,
+		8,
+		20
+	]
+};
+function gradeBy(rate, bands) {
+	const grades = [
+		"A",
+		"B",
+		"C",
+		"D"
+	];
+	for (let i = 0; i < bands.length; i++) if (rate <= bands[i]) return grades[i];
 	return "E";
 }
 const ORDER = [
@@ -120,8 +130,15 @@ function worst(a, b) {
 function pct(rate) {
 	return `${(rate * 100).toFixed(1)}%`;
 }
-/** Grade one session deterministically. */
-function gradeSession(m) {
+/**
+* Grade one session deterministically. `bands` may override any subset of
+* the dimensions; unspecified ones keep the documented defaults.
+*/
+function gradeSession(m, bands = {}) {
+	const b = {
+		...DEFAULT_GRADE_BANDS,
+		...bands
+	};
 	const dimensions = [];
 	const notes = [];
 	if (m.toolCalls === 0) {
@@ -132,7 +149,7 @@ function gradeSession(m) {
 		});
 		notes.push("Reliability is n/a — the session made no tool calls.");
 	} else {
-		const grade = gradeBy(m.toolErrorRate, RELIABILITY);
+		const grade = gradeBy(m.toolErrorRate, b.reliability);
 		dimensions.push({
 			dimension: "Reliability",
 			grade,
@@ -145,7 +162,7 @@ function gradeSession(m) {
 		detail: "no user turns"
 	});
 	else {
-		const grade = gradeBy(m.correctionRate, REASK);
+		const grade = gradeBy(m.correctionRate, b.reask);
 		dimensions.push({
 			dimension: "Re-ask",
 			grade,
@@ -158,9 +175,10 @@ function gradeSession(m) {
 		detail: "no tool activity"
 	});
 	else {
+		const [lowC, lowB, highC, highD] = b.toolLoad;
 		let grade = "A";
-		if (m.toolLoad < TOOL_LOAD_LOW_B) grade = m.toolLoad < TOOL_LOAD_LOW_C ? "C" : "B";
-		if (m.toolLoad > TOOL_LOAD_HIGH_C) grade = worst(grade, m.toolLoad > TOOL_LOAD_HIGH_D ? "D" : "C");
+		if (m.toolLoad < lowB) grade = m.toolLoad < lowC ? "C" : "B";
+		if (m.toolLoad > highC) grade = worst(grade, m.toolLoad > highD ? "D" : "C");
 		dimensions.push({
 			dimension: "Tool load",
 			grade,
@@ -227,7 +245,7 @@ function compareSessions(before, after) {
 *
 * @module dsh-session-eval/version
 */
-const VERSION = "0.2.3";
+const VERSION = "0.3.0";
 //#endregion
 //#region src/evalCommand.ts
 const EVAL_USAGE = "Usage: /eval [--id <sessionId>] [--json]";
@@ -310,7 +328,7 @@ async function readEvents(ctx, seam, sessionIdRaw) {
 	}
 }
 /** Execute /eval against the session-query seam. */
-async function executeEval(ctx, invocation, seam = ctx.sessionQuery) {
+async function executeEval(ctx, invocation, seam = ctx.sessionQuery, bands = {}) {
 	const parsed = parseEvalArgs(invocation.rawInput);
 	if (typeof parsed === "string") return {
 		kind: "error",
@@ -323,18 +341,18 @@ async function executeEval(ctx, invocation, seam = ctx.sessionQuery) {
 		text: events
 	};
 	const metrics = computeMetrics(sessionIdRaw, adaptEvents(events));
-	const card = gradeSession(metrics);
+	const card = gradeSession(metrics, bands);
 	if (parsed.json === true) return {
 		kind: "success",
 		text: JSON.stringify({
-			generator: "dsh-session-eval v0.2.3",
+			generator: "dsh-session-eval v0.3.0",
 			metrics,
 			card
 		}, null, 2)
 	};
 	return {
 		kind: "success",
-		text: renderCard(card, "dsh-session-eval v0.2.3")
+		text: renderCard(card, "dsh-session-eval v0.3.0")
 	};
 }
 /** Execute /eval-diff against the session-query seam. */
@@ -358,25 +376,58 @@ 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.3.0",
 			report
 		}, null, 2)
 	};
 	return {
 		kind: "success",
-		text: renderTrend(report, "dsh-session-eval v0.2.3")
+		text: renderTrend(report, "dsh-session-eval v0.3.0")
 	};
 }
 //#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] [--since 24h|7d|30d]  (N = last N sessions, 1-20, default 5; --since grades only sessions whose latest activity falls inside the window)";
 /** 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;
+	let since;
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (token === "--since") {
+			if (since !== void 0) return `--since may be given only once.\n${EVAL_HISTORY_USAGE}`;
+			const value = tokens[++i];
+			const match = /^(\d+)(h|d)$/.exec(value ?? "");
+			if (!match) return `--since needs a window like 24h or 7d.\n${EVAL_HISTORY_USAGE}`;
+			const amount = Number(match[1]);
+			if (amount < 1 || amount > 365) return `--since window is out of range.\n${EVAL_HISTORY_USAGE}`;
+			since = {
+				label: value,
+				ms: amount * (match[2] === "h" ? 36e5 : 864e5)
+			};
+			continue;
+		}
+		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 +443,9 @@ function parseEvalHistoryArgs(rawInput) {
 	}
 	return {
 		count,
-		json
+		json,
+		...out !== void 0 ? { out } : {},
+		...since !== void 0 ? { since } : {}
 	};
 }
 function toMillis(createdAt) {
@@ -410,7 +463,10 @@ function stamp(ms) {
 /** Render a history report as terminal text. */
 function renderHistory(report) {
 	const lines = [];
-	if (report.entries.length === 0) return "No sessions found in this workspace; nothing to grade.";
+	if (report.entries.length === 0) {
+		if (report.sinceLabel !== void 0) return `No sessions with activity in the last ${report.sinceLabel} in this workspace; nothing to grade.`;
+		return "No sessions found in this workspace; nothing to grade.";
+	}
 	lines.push(`Session history — last ${report.entries.length} in this workspace`);
 	for (const entry of report.entries) {
 		const m = entry.metrics;
@@ -421,7 +477,7 @@ function renderHistory(report) {
 	return lines.join("\n");
 }
 /** Execute /eval-history against the session-query seam. */
-async function executeEvalHistory(ctx, invocation, seam = ctx.sessionQuery) {
+async function executeEvalHistory(ctx, invocation, seam = ctx.sessionQuery, bands = {}) {
 	const parsed = parseEvalHistoryArgs(invocation.rawInput);
 	if (typeof parsed === "string") return {
 		kind: "error",
@@ -437,18 +493,37 @@ async function executeEvalHistory(ctx, invocation, seam = ctx.sessionQuery) {
 			text: `Could not list sessions: ${error instanceof Error ? error.message : String(error)}`
 		};
 	}
-	const recent = records.map((record) => record.header).filter((header) => header != null).filter((header) => ownCwd === void 0 || header.cwd === ownCwd).map((header) => ({
+	const headers = records.map((record) => record.header).filter((header) => header != null).filter((header) => ownCwd === void 0 || header.cwd === ownCwd).map((header) => ({
 		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."
-	};
+	})).sort((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0));
+	const activityCache = /* @__PURE__ */ new Map();
+	let recent = headers.slice(-parsed.count);
+	if (parsed.since !== void 0) {
+		const cutoff = Date.now() - parsed.since.ms;
+		const chosen = [];
+		for (let i = headers.length - 1; i >= 0 && chosen.length < parsed.count; i--) {
+			const header = headers[i];
+			let log;
+			try {
+				log = await seam.readSession(SessionId(header.id));
+			} catch (error) {
+				return {
+					kind: "error",
+					text: `Could not read session ${id8(header.id)}: ${error instanceof Error ? error.message : String(error)}`
+				};
+			}
+			activityCache.set(header.id, log.events);
+			if (adaptEvents(log.events).reduce((max, event) => Math.max(max, event.time), Number.NEGATIVE_INFINITY) >= cutoff) chosen.unshift(header);
+		}
+		recent = chosen;
+	}
 	const entries = [];
 	for (const header of recent) {
+		const cached = activityCache.get(header.id);
 		let events;
-		try {
+		if (cached !== void 0) events = cached;
+		else try {
 			events = (await seam.readSession(SessionId(header.id))).events;
 		} catch (error) {
 			return {
@@ -461,36 +536,119 @@ async function executeEvalHistory(ctx, invocation, seam = ctx.sessionQuery) {
 			sessionId: header.id,
 			createdAt: header.createdAt,
 			metrics,
-			card: gradeSession(metrics)
+			card: gradeSession(metrics, bands)
 		});
 	}
 	const report = {
 		entries,
-		trend: entries.length >= 2 ? compareSessions(entries[0].metrics, entries[entries.length - 1].metrics) : null
+		trend: entries.length >= 2 ? compareSessions(entries[0].metrics, entries[entries.length - 1].metrics) : null,
+		...parsed.since !== void 0 ? { sinceLabel: parsed.since.label } : {}
 	};
-	if (parsed.json === true) return {
+	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: JSON.stringify({
-			generator: `dsh-session-eval v${VERSION}`,
-			report
-		}, null, 2)
+		text
 	};
+}
+//#endregion
+//#region src/config.ts
+/**
+* Plugin config parsing for dsh-session-eval.
+*
+* The config block lives under the plugin's node in the host config tree, so
+* it is naturally per-profile: each profile can grade against its own bands.
+*
+* Shape (#1):
+*
+* ```yaml
+* session-eval:
+*   gradeBands:
+*     reliability: [4, 8, 15, 30]   # tool error-rate percent, A–D upper bounds
+*     reask: [0, 2, 4, 8]           # corrections per 10 user turns
+*     toolLoad: [0.1, 0.5, 8, 20]   # tool calls per turn: [lowC, lowB, highC, highD]
+* ```
+*
+* Unknown keys, wrong arity, non-numeric, negative or non-ascending values
+* fail fast with a readable error — a silent fallback would grade sessions
+* against bands nobody chose.
+*
+* @module dsh-session-eval/config
+*/
+const DIMENSIONS = [
+	"reliability",
+	"reask",
+	"toolLoad"
+];
+const SHAPE = "4 ascending numbers: reliability = tool error-rate percent A–D upper bounds, reask = corrections per 10 user turns, toolLoad = [lowC, lowB, highC, highD] tool calls per turn";
+function parseDimension(dimension, raw) {
+	const where = `gradeBands.${dimension}`;
+	if (raw.length !== 4) throw new Error(`${where} needs exactly ${SHAPE}`);
+	const values = raw.map((entry) => {
+		if (typeof entry !== "number" || !Number.isFinite(entry)) throw new Error(`${where} entries must each be a finite number (${SHAPE})`);
+		return entry;
+	});
+	for (const value of values) if (value < 0) throw new Error(`${where} entries must not be negative (${SHAPE})`);
+	for (let i = 1; i < values.length; i++) if (values[i] <= values[i - 1]) throw new Error(`${where} entries must be strictly ascending (${SHAPE})`);
+	return values;
+}
+/**
+* Parse the plugin config into grade bands. Returns the defaults unchanged
+* when nothing is configured; throws a readable Error on any invalid input.
+*/
+function parseGradeBands(config) {
+	if (config === void 0 || config === null) return DEFAULT_GRADE_BANDS;
+	if (typeof config !== "object") throw new Error("session-eval config must be a mapping");
+	const root = config;
+	for (const key of Object.keys(root)) if (key !== "gradeBands") throw new Error(`Unknown session-eval config key "${key}" — only "gradeBands" is read`);
+	const raw = root.gradeBands;
+	if (raw === void 0) return DEFAULT_GRADE_BANDS;
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new Error("session-eval gradeBands must be a mapping");
+	const overrides = {};
+	for (const key of Object.keys(raw)) if (!DIMENSIONS.includes(key)) throw new Error(`Unknown gradeBands dimension "${key}" — expected one of ${DIMENSIONS.join(", ")}`);
+	for (const dimension of DIMENSIONS) {
+		const entry = raw[dimension];
+		if (entry !== void 0) overrides[dimension] = parseDimension(dimension, entry);
+	}
+	const quad = (dimension) => overrides[dimension];
 	return {
-		kind: "success",
-		text: renderHistory(report)
+		reliability: overrides.reliability !== void 0 ? overrides.reliability.map((v) => v / 100) : DEFAULT_GRADE_BANDS.reliability,
+		reask: overrides.reask !== void 0 ? quad("reask") : DEFAULT_GRADE_BANDS.reask,
+		toolLoad: overrides.toolLoad !== void 0 ? quad("toolLoad") : DEFAULT_GRADE_BANDS.toolLoad
 	};
 }
 //#endregion
 //#region src/index.ts
 const name = "session-eval";
 const inject = ["commands", "sessionQuery"];
-/** Plugin entry: mount the /eval, /eval-diff and /eval-history commands. */
-function apply(ctx) {
+/**
+* Plugin entry: mount the /eval, /eval-diff and /eval-history commands.
+*
+* `config` is the plugin's node in the host config tree (per-profile): its
+* `gradeBands` block overrides the default grade thresholds — see config.ts.
+* Invalid config fails fast here, at plugin load, rather than mid-grade.
+*/
+function apply(ctx, config) {
+	const bands = parseGradeBands(config);
 	ctx.effect(function* () {
 		yield ctx.commands.register({
 			name: "eval",
 			description: "Print a deterministic grade card for this session (or another via --id): reliability, re-ask, tool load",
-			handler: (invocation) => executeEval(ctx, invocation)
+			handler: (invocation) => executeEval(ctx, invocation, void 0, bands)
 		});
 		yield ctx.commands.register({
 			name: "eval-diff",
@@ -500,7 +658,7 @@ function apply(ctx) {
 		yield ctx.commands.register({
 			name: "eval-history",
 			description: "Grade the last N sessions in this workspace (default 5) and show whether the trend is improving",
-			handler: (invocation) => executeEvalHistory(ctx, invocation)
+			handler: (invocation) => executeEvalHistory(ctx, invocation, void 0, bands)
 		});
 	}, "session-eval lifecycle");
 }

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.3.0",
   "publishConfig": {
     "access": "public"
   },