dsh-session-eval 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.4.1 — 2026-11-05
+
+Peer-range compatibility release (no behavior change).
+
+- `@deepseek-ai/dsh-*` peers widened to `^0.1.5-rc.3 || ^0.2.0 || 0.2.2-rc.1` and `@deepseek-ai/cordis` to `^4.0.2`, ahead of the DSH 0.2.2 release train.
+- Verified against `@deepseek-ai/*@0.2.2-rc.1` in a scratch install: full suite 60/60 green. Notably `SESSION_FORMAT_VERSION` moved 3 → 4 upstream; a v3-header archive still round-trips through the 0.2.2 `buildArchiveFromLog` (historical formats are translated), so existing exported bundles keep grading identically.
+
+## 0.4.0 — 2026-11-05
+
+Evidence-handoff closure (#8): `/eval --report <bundle-or-archive.zip>`.
+
+- Grades straight from an exported dsh-session-export artifact — bundle ZIPs (nested archive.zip) and raw /archive ZIPs — no session id to copy, and it works after the session is gone from the store.
+- The artifact's JSONL is the canonical event log, so `--report` matches `/eval --id` exactly; a round-trip test builds bundles with the real dsh-session-export writer and asserts identical metrics and cards.
+- Zero runtime dependencies kept: a minimal ZIP reader (central directory + raw DEFLATE via node:zlib, CRC32-verified) mirrors the export writer; dsh-session-export is a devDependency only, for the interop test.
+- README.md / README.zh.md document the recall → report → eval closure with a worked example.
+
 ## 0.3.0 — 2026-10-23
 
 Feature release: configurable grade bands (#1) and the history time window (#2).

package/README.md

@@ -61,6 +61,19 @@ Notes:
 
 All three read through the same trusted `ctx.sessionQuery` seam, so any persistence backend (JSONL or SQLite) works without touching raw artifacts.
 
+### Evidence-handoff closure (#8)
+
+`/eval --report` grades straight from an artifact `dsh-session-export` already wrote — no session id to copy, and it works after the session is gone from the store:
+
+```
+recall "resume template font"
+→ session session-ca62e005-… · report /proj/dsh-transcripts/bundle-ca62e005-20261104-120000.zip
+
+/eval --report /proj/dsh-transcripts/bundle-ca62e005-20261104-120000.zip
+```
+
+Bundle ZIPs (the nested `archive.zip` raw JSONL) and raw `/archive` ZIPs are both accepted. The JSONL inside is the canonical event log — the same bytes `readSession` returns — so `--report` grades **identically** to `/eval --id` (verified by a round-trip test against the real `dsh-session-export` writer). `--id` and `--report` are mutually exclusive.
+
 ## Contributing
 
 - **Local dev**: `npm ci && npm run typecheck && npm test && npm run bundle` (Node 20 or 22).
@@ -85,6 +98,7 @@ Both are useful; they don't compete. Benchmarks test what you *predicted*; retro
 |---|---|
 | `/eval` | Grade card for the current session |
 | `/eval --id <sessionId>` | Grade a specific session |
+| `/eval --report <bundle-or-archive.zip>` | Grade from an exported artifact (works after the session is gone from the store) |
 | `/eval --json` | Machine-readable metrics + card |
 | `/eval-diff <beforeId> <afterId>` | Regression comparison, noise-tolerant |
 | `/eval-diff … --json` | Machine-readable trend report |

package/README.zh.md

@@ -61,6 +61,19 @@ Notes:
 
 三者都通过同一个可信的 `ctx.sessionQuery` 缝读取，JSONL / SQLite 等任何持久化后端均可使用。
 
+### 证据联动闭环（#8）
+
+`/eval --report` 直接从 `dsh-session-export` 已写出的产物评分——不用抄会话 id，会话从存储中删除后依然可评：
+
+```
+recall "resume template font"
+→ session session-ca62e005-… · report /proj/dsh-transcripts/bundle-ca62e005-20261104-120000.zip
+
+/eval --report /proj/dsh-transcripts/bundle-ca62e005-20261104-120000.zip
+```
+
+接受 bundle ZIP（内嵌 `archive.zip` 原始 JSONL）与裸 `/archive` ZIP。里面的 JSONL 就是权威事件日志——与 `readSession` 返回的是同一份字节——所以 `--report` 与 `/eval --id` **评分完全一致**（用真实 `dsh-session-export` 写入器做过往返测试）。`--id` 与 `--report` 互斥。
+
 ## 贡献
 
 - **本地开发**：`npm ci && npm run typecheck && npm test && npm run bundle`（Node 20 或 22）。

package/lib/index.d.ts

@@ -114,13 +114,18 @@ declare function gradeSession(m: SessionMetrics, bands?: Partial<GradeBands>): G
 /** Compare two sessions dimension by dimension. */
 declare function compareSessions(before: SessionMetrics, after: SessionMetrics): TrendReport;
 //#endregion
+//#region src/artifact.d.ts
+/** Filesystem seam (injectable for tests). */
+type ReadFile = (path: string) => Buffer;
+//#endregion
 //#region src/evalCommand.d.ts
-declare const EVAL_USAGE = "Usage: /eval [--id <sessionId>] [--json]";
+declare const EVAL_USAGE = "Usage: /eval [--id <sessionId>] [--report <bundle-or-archive.zip>] [--json]";
 declare const EVAL_DIFF_USAGE = "Usage: /eval-diff <beforeSessionId> <afterSessionId> [--json]";
 declare function id8(sessionId: string): string;
 /** Args for /eval. */
 interface EvalArgs {
   readonly sessionId?: string;
+  readonly report?: string;
   readonly json?: boolean;
 }
 /** Args for /eval-diff. */
@@ -142,8 +147,8 @@ interface QuerySeam {
     events: readonly unknown[];
   }>;
 }
-/** Execute /eval against the session-query seam. */
-declare function executeEval(ctx: Context, invocation: CommandInvocation, seam?: QuerySeam, bands?: Partial<GradeBands>): Promise<CommandResult>;
+/** Execute /eval against the session-query seam or an exported artifact. */
+declare function executeEval(ctx: Context, invocation: CommandInvocation, seam?: QuerySeam, bands?: Partial<GradeBands>, readFile?: ReadFile): Promise<CommandResult>;
 /** Execute /eval-diff against the session-query seam. */
 declare function executeEvalDiff(ctx: Context, invocation: CommandInvocation, seam?: QuerySeam): Promise<CommandResult>;
 //#endregion

package/lib/index.js

@@ -1,4 +1,6 @@
 import { SessionId } from "@deepseek-ai/dsh-session";
+import { crc32, inflateRawSync } from "node:zlib";
+import { readFileSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 //#region src/metrics.ts
@@ -85,6 +87,137 @@ function readBool(source, key) {
 	return typeof value === "boolean" ? value : void 0;
 }
 //#endregion
+//#region src/zip.ts
+/**
+* Minimal single-file ZIP reader (methods 0 and 8, no external dependency).
+*
+* The mirror of dsh-session-export's `util/zip.ts` writer: parses the
+* End-of-Central-Directory record, walks the central directory, and inflates
+* each entry with raw DEFLATE (`node:zlib.inflateRawSync`, ZIP method 8) or
+* copies stored entries (method 0). Data descriptors are not needed because
+* the writer emits none; CRC32 is verified per entry. Only the features the
+* toolchain's own archives use are supported — a ZIP using extensions beyond
+* that is rejected with a clear error, not misread.
+*
+* @module dsh-session-eval/zip
+*/
+const EOCD_SIG = 101010256;
+const CD_SIG = 33639248;
+const LFH_SIG = 67324752;
+/** Locate the EOCD record: normally the last 22 bytes; scan back over a comment if present. */
+function findEocd(buf) {
+	const limit = Math.max(0, buf.length - 22 - 65536);
+	for (let i = buf.length - 22; i >= limit; i -= 1) if (buf.readUInt32LE(i) === EOCD_SIG) return i;
+	return -1;
+}
+/**
+* Read every entry of a ZIP archive. Throws `Error` with a plain message on
+* anything that is not a supported archive (truncated, unknown method, or a
+* CRC mismatch) — callers surface the message to the user.
+*/
+function readZipEntries(buf) {
+	const eocd = findEocd(buf);
+	if (eocd < 0) throw new Error("not a ZIP archive (no end-of-central-directory record)");
+	const entryCount = buf.readUInt16LE(eocd + 10);
+	const cdOffset = buf.readUInt32LE(eocd + 16);
+	const entries = [];
+	let p = cdOffset;
+	for (let i = 0; i < entryCount; i += 1) {
+		if (p + 46 > buf.length || buf.readUInt32LE(p) !== CD_SIG) throw new Error(`corrupt ZIP: central directory entry ${i} is unreadable`);
+		const method = buf.readUInt16LE(p + 10);
+		const crcExpected = buf.readUInt32LE(p + 16);
+		const compressedSize = buf.readUInt32LE(p + 20);
+		const rawSize = buf.readUInt32LE(p + 24);
+		const nameLength = buf.readUInt16LE(p + 28);
+		const extraLength = buf.readUInt16LE(p + 30);
+		const commentLength = buf.readUInt16LE(p + 32);
+		const localOffset = buf.readUInt32LE(p + 42);
+		const name = buf.toString("utf8", p + 46, p + 46 + nameLength);
+		if (buf.readUInt32LE(localOffset) !== LFH_SIG) throw new Error(`corrupt ZIP: entry "${name}" has no local file header`);
+		const lfhNameLength = buf.readUInt16LE(localOffset + 26);
+		const lfhExtraLength = buf.readUInt16LE(localOffset + 28);
+		const dataStart = localOffset + 30 + lfhNameLength + lfhExtraLength;
+		const compressed = buf.subarray(dataStart, dataStart + compressedSize);
+		let raw;
+		if (method === 0) raw = Buffer.from(compressed);
+		else if (method === 8) raw = inflateRawSync(compressed);
+		else throw new Error(`unsupported ZIP compression method ${method} for entry "${name}"`);
+		if (raw.length !== rawSize) throw new Error(`corrupt ZIP: entry "${name}" decompressed to the wrong size`);
+		if (crc32(raw) >>> 0 !== crcExpected) throw new Error(`corrupt ZIP: CRC mismatch for entry "${name}"`);
+		entries.push({
+			name,
+			data: raw
+		});
+		p += 46 + nameLength + extraLength + commentLength;
+	}
+	return entries;
+}
+//#endregion
+//#region src/artifact.ts
+/**
+* Evidence-handoff loader: grade a session straight from an artifact
+* dsh-session-export already wrote (#8 closure).
+*
+* A bundle ZIP (`bundle-<id8>-<timestamp>.zip`) carries the raw JSONL
+* archive as a nested `archive.zip`, and a `/archive` ZIP carries
+* `session.jsonl` at its root. Both are the canonical event log — the same
+* bytes `readSession` would return — so grading from an artifact matches
+* grading through the seam exactly, and works after the session is gone
+* from the store.
+*
+* @module dsh-session-eval/artifact
+*/
+function jsonlEvents(data) {
+	const out = [];
+	for (const line of data.toString("utf8").split("\n")) {
+		const trimmed = line.trim();
+		if (trimmed === "") continue;
+		out.push(JSON.parse(trimmed));
+	}
+	return out;
+}
+function byName(entries) {
+	return new Map(entries.map((entry) => [entry.name, entry.data]));
+}
+/** Parse one zip level; returns null when this level holds no session.jsonl. */
+function loadFromZipLevel(buf, origin) {
+	const files = byName(readZipEntries(buf));
+	const jsonl = files.get("session.jsonl");
+	if (jsonl === void 0) return null;
+	const manifestRaw = files.get("manifest.json");
+	const manifest = manifestRaw === void 0 ? {} : JSON.parse(manifestRaw.toString("utf8"));
+	return {
+		sessionId: typeof manifest.sessionId === "string" ? manifest.sessionId : "unknown-session",
+		events: jsonlEvents(jsonl),
+		origin
+	};
+}
+/**
+* Load a gradeable session from an exported artifact path — a bundle ZIP
+* (nested archive) or a raw `/archive` ZIP. Returns a plain error string on
+* anything unreadable or unrecognized; never throws.
+*/
+function loadReportArtifact(path, readFile) {
+	let buf;
+	try {
+		buf = readFile(path);
+	} catch (error) {
+		return `Could not read ${path}: ${error instanceof Error ? error.message : String(error)}`;
+	}
+	try {
+		const nested = readZipEntries(buf).find((entry) => entry.name === "archive.zip");
+		if (nested !== void 0) {
+			const loaded = loadFromZipLevel(nested.data, `${path} (archive.zip)`);
+			if (loaded !== null) return loaded;
+		}
+		const direct = loadFromZipLevel(buf, path);
+		if (direct !== null) return direct;
+		return `${path} is a ZIP but carries no session.jsonl (neither at the root nor inside archive.zip) — is it a transcript report rather than a bundle or archive?`;
+	} catch (error) {
+		return `Could not load artifact ${path}: ${error instanceof Error ? error.message : String(error)}`;
+	}
+}
+//#endregion
 //#region src/grade.ts
 /** The documented defaults; unchanged when no config is given. */
 const DEFAULT_GRADE_BANDS = {
@@ -248,7 +381,7 @@ function compareSessions(before, after) {
 const VERSION = "0.3.0";
 //#endregion
 //#region src/evalCommand.ts
-const EVAL_USAGE = "Usage: /eval [--id <sessionId>] [--json]";
+const EVAL_USAGE = "Usage: /eval [--id <sessionId>] [--report <bundle-or-archive.zip>] [--json]";
 const EVAL_DIFF_USAGE = "Usage: /eval-diff <beforeSessionId> <afterSessionId> [--json]";
 function id8(sessionId) {
 	return sessionId.length > 8 ? `${sessionId.slice(0, 8)}…` : sessionId;
@@ -271,6 +404,15 @@ function parseEvalArgs(rawInput) {
 			i += 2;
 			continue;
 		}
+		if (token === "--report") {
+			const value = tokens[i + 1];
+			if (value === void 0 || value.startsWith("--")) return `--report requires an artifact path value.\n${EVAL_USAGE}`;
+			if (args.report !== void 0) return `--report may be given only once.\n${EVAL_USAGE}`;
+			if (args.sessionId !== void 0) return `--id and --report are mutually exclusive.\n${EVAL_USAGE}`;
+			args.report = value;
+			i += 2;
+			continue;
+		}
 		if (token === "--json") {
 			if (args.json === true) return `--json may be given only once.\n${EVAL_USAGE}`;
 			args.json = true;
@@ -327,13 +469,36 @@ async function readEvents(ctx, seam, sessionIdRaw) {
 		return `Could not read session ${id8(sessionIdRaw)}: ${error instanceof Error ? error.message : String(error)}`;
 	}
 }
-/** Execute /eval against the session-query seam. */
-async function executeEval(ctx, invocation, seam = ctx.sessionQuery, bands = {}) {
+/** Execute /eval against the session-query seam or an exported artifact. */
+async function executeEval(ctx, invocation, seam = ctx.sessionQuery, bands = {}, readFile = (path) => readFileSync(path)) {
 	const parsed = parseEvalArgs(invocation.rawInput);
 	if (typeof parsed === "string") return {
 		kind: "error",
 		text: parsed
 	};
+	if (parsed.report !== void 0) {
+		const artifact = loadReportArtifact(parsed.report, readFile);
+		if (typeof artifact === "string") return {
+			kind: "error",
+			text: artifact
+		};
+		const metrics = computeMetrics(artifact.sessionId, adaptEvents(artifact.events));
+		const card = gradeSession(metrics, bands);
+		const note = `from artifact ${artifact.origin}`;
+		if (parsed.json === true) return {
+			kind: "success",
+			text: JSON.stringify({
+				generator: "dsh-session-eval v0.3.0",
+				source: note,
+				metrics,
+				card
+			}, null, 2)
+		};
+		return {
+			kind: "success",
+			text: `${renderCard(card, "dsh-session-eval v0.3.0")}\n(${note})`
+		};
+	}
 	const sessionIdRaw = parsed.sessionId ?? String(invocation.agent.session.id);
 	const events = await readEvents(ctx, seam, sessionIdRaw);
 	if (typeof events === "string") return {

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.3.0",
+  "version": "0.4.1",
   "publishConfig": {
     "access": "public"
   },
@@ -38,21 +38,22 @@
     "regression"
   ],
   "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-commands": "^0.1.5-rc.3 || ^0.2.0 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.3 || ^0.2.0 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-rc.3 || ^0.2.0 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-session-query": "^0.1.5-rc.3 || ^0.2.0 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.5-rc.3 || ^0.2.0 || 0.2.2-rc.1"
+  },
+  "devDependencies": {
     "@deepseek-ai/cordis": "4.0.2",
     "@deepseek-ai/dsh-commands": "^0.1.5-rc.3",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.3",
     "@deepseek-ai/dsh-session": "^0.1.5-rc.3",
-    "@deepseek-ai/dsh-session-query": "^0.1.5-rc.3",
-    "@deepseek-ai/dsh-tools": "^0.1.5-rc.3"
-  },
-  "devDependencies": {
     "@types/node": "^26.2.0",
+    "dsh-session-export": "^1.9.0",
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11",
-    "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/dsh-commands": "^0.1.5-rc.3",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.3"
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "bundle": "tsdown",