dsh-session-recall 0.4.1 → 0.5.1

package/README.md

@@ -27,8 +27,6 @@ If you need agent memory orchestration, use a memory framework; if you need boun
 
 ## Roadmap
 
-- **P1: ranking controls** — configurable recency decay and session pinning on top of FTS relevance.
-- **P1: query diagnostics** — expose match reason (fts/cjk-fallback/filters) and scan budget in result metadata.
 - **P2: evidence handoff** — one-click bridge to session export for matched sessions.
 
 ## Why
@@ -120,10 +118,14 @@ Deployment-level controls for what the model may read back:
 | `redactionMode` | `off` / `mask` / `hash` | `off` | Redact secret-looking text (bearer headers, prefixed API keys, private-key blocks, emails) in snippets and titles. `hash` keeps secrets comparable (`#xxxxxxxx`, same secret → same marker) without being readable. Results carry a `redacted` count. |
 | `cwdAllowlist` | list of paths | (none) | Only sessions started in these directories are searchable; the calling cwd itself must be listed. |
 | `cwdDenylist` | list of paths | (none) | These directories are never searchable. Deny wins over allow. |
+| `recencyHalfLifeDays` | days (e.g. `30`) | (off) | Re-rank cross-session hits: backend rank × exponential recency decay over the match time. Unset or `<= 0` keeps backend order. Per result page. |
+| `pinnedCwds` | list of paths | (none) | Sessions from these project directories rank first, as a group. |
 | `allProjectsPolicy` | `allow` / `deny` / `confirm` | `allow` | `deny` ignores `all_projects` with a model-facing hint; `confirm` asks the user through the official `@deepseek-ai/dsh-user-approval` seam — fail-closed when no answerer is composed. |
 
 All three gates apply uniformly to cross-session hits, the CJK fallback scan, and `session_id` reads — no bypass route.
 
+Every result also carries a `diagnostics` object (v0.5): which engine produced the matches (`fts` / `cjk-fallback` / `session-scan`), how many sessions a fallback scan visited against its budget, and whether re-ranking was applied — so callers can tell *why* they got what they got.
+
 ## Known limitations
 
 - First search after startup walks the durable logs to build the index (the tool description warns the model); subsequent searches are incremental.

package/README.zh.md

@@ -27,8 +27,6 @@ DeepSeek Harness 的**确定性跨会话全文检索**插件：注册模型可
 
 ## 路线图
 
-- **P1：排序策略可配** —— 在 FTS 相关度之上增加时间衰减、会话 pin 权重。
-- **P1：查询诊断元数据** —— 返回命中来源（fts/cjk-fallback/filters）与扫描预算。
 - **P2：证据联动导出** —— 命中后可一键触发对应会话导出。
 
 ## 为什么做这个
@@ -120,10 +118,14 @@ dsh plugin --profile web add github:kittimzhe/dsh-session-recall
 | `redactionMode` | `off` / `mask` / `hash` | `off` | 对标题与摘录中疑似密钥的文本（Bearer 头、前缀式 API key、私钥块、邮箱）脱敏。`hash` 用确定性摘要 `#xxxxxxxx`（同一密钥同一标记）保持可比性。结果带 `redacted` 计数。 |
 | `cwdAllowlist` | 路径列表 | （无） | 只检索这些目录下启动的会话；当前项目目录本身也必须在列表内。 |
 | `cwdDenylist` | 路径列表 | （无） | 这些目录永不检索。deny 优先于 allow。 |
+| `recencyHalfLifeDays` | 天数（如 `30`） | （关闭） | 跨会话命中重排：后端名次 × 命中时间上的指数衰减。不设或 `<= 0` 保持后端顺序。按结果页生效。 |
+| `pinnedCwds` | 路径列表 | （无） | 这些项目目录的会话作为一组排在最前。 |
 | `allProjectsPolicy` | `allow` / `deny` / `confirm` | `allow` | `deny` 忽略 `all_projects` 并向模型说明；`confirm` 走官方 `@deepseek-ai/dsh-user-approval` 接缝向用户请求批准——无应答者时 fail-closed。 |
 
 三道闸门统一作用于跨会话命中、CJK 回退扫描和 `session_id` 直读——没有绕行路径。
 
+每个结果还带 `diagnostics` 对象（v0.5）：命中由哪个引擎产生（`fts` / `cjk-fallback` / `session-scan`）、回退扫描访问了几个会话（对照预算）、是否做了重排——让调用方知道「为什么是这些结果」。
+
 ## 已知限制
 
 - 启动后第一次搜索会扫全量日志建索引（工具描述里已警告模型）；之后增量更新。

package/lib/index.d.ts

@@ -46,6 +46,10 @@ interface RecallConfig {
    * approve through the `@deepseek-ai/dsh-user-approval` seam; fail-closed).
    */
   allProjectsPolicy?: AllProjectsPolicy;
+  /** Re-rank cross-session hits with exponential recency decay (half-life in days). Default: off. */
+  recencyHalfLifeDays?: number;
+  /** Sessions started in these project directories rank first. Default: none. */
+  pinnedCwds?: readonly string[];
 }
 /** Validated, fully defaulted configuration. */
 interface NormalizedRecallConfig {
@@ -59,6 +63,8 @@ interface NormalizedRecallConfig {
   readonly cwdAllowlist: readonly string[];
   readonly cwdDenylist: readonly string[];
   readonly allProjectsPolicy: AllProjectsPolicy;
+  readonly recencyHalfLifeDays: number | undefined;
+  readonly pinnedCwds: readonly string[];
 }
 /** Default, clamp, and cross-check every optional field. */
 declare function normalizeRecallConfig(config?: RecallConfig): NormalizedRecallConfig;
@@ -91,6 +97,17 @@ interface RecallScope {
   allProjects: boolean;
   sessionId: string | null;
 }
+/** How the matches in a result were produced (v0.5 diagnostics). */
+interface RecallDiagnostics {
+  /** Which engine produced the matches. */
+  readonly source: 'fts' | 'cjk-fallback' | 'session-scan';
+  /** Sessions visited by the fallback scan, when it ran. */
+  readonly scanned?: number;
+  /** The fallback scan budget (`cjkFallbackScanMax`), when a scan ran. */
+  readonly scanBudget?: number;
+  /** True when re-ranking (recency decay / pinning) was applied to this page. */
+  readonly ranked: boolean;
+}
 /** The `recall` tool's canonical JSON value, validated against the output schema. */
 interface RecallResult {
   query: string;
@@ -102,6 +119,8 @@ interface RecallResult {
   hint: string | null;
   /** How many secret-looking fields were redacted in this result (0 when redaction is off). */
   redacted: number;
+  /** How this result was produced; null when the call failed before searching. */
+  diagnostics: RecallDiagnostics | null;
 }
 /** The typed model-facing arguments after schema validation. */
 interface RecallArgs {
@@ -112,6 +131,53 @@ interface RecallArgs {
   cursor?: string;
 }
 //#endregion
+//#region src/rank.d.ts
+/**
+ * Result re-ranking for cross-session recall hits.
+ *
+ * The FTS backend returns hits in its own relevance order but exposes no
+ * numeric score. Two optional, composable controls re-rank that order:
+ *
+ * - **Recency decay** (`recencyHalfLifeDays`): each hit's weight is its
+ *   backend rank position (1/rank, a monotone relevance proxy) multiplied by
+ *   an exponential decay `0.5^(ageDays / halfLife)` over the match time. A hit
+ *   one half-life old needs roughly twice the relevance rank to keep its
+ *   place — "the bug we fixed last week" beats an older, equally-ranked match.
+ *
+ * - **Session pinning** (`pinnedCwds`): hits from pinned project directories
+ *   float to the top as a group, preserving their internal order.
+ *
+ * Sorting is stable (ties keep backend order) and per result page: the
+ * backend pages lazily, so ranking is applied to the page in hand — a
+ * documented limitation, not a global rerank.
+ *
+ * @module dsh-session-recall/rank
+ */
+/** The slice of a recall item ranking needs (structural, for testability). */
+interface RankableItem {
+  readonly cwd: string | null;
+  readonly createdAt: number;
+  readonly bestMatch: {
+    readonly time: number;
+  };
+}
+interface RankingOptions {
+  /** Exponential recency half-life in days; unset disables decay re-ranking. */
+  readonly recencyHalfLifeDays?: number;
+  /** Project directories whose hits float to the top. */
+  readonly pinnedCwds?: readonly string[];
+  /** Clock override for tests; defaults to Date.now(). */
+  readonly now?: number;
+}
+/** True when any ranking control is active. */
+declare function rankingActive(options: RankingOptions): boolean;
+/**
+ * Re-rank one page of hits. Returns the same item references in a new order;
+ * the input is never mutated. With no controls active the input order is
+ * returned unchanged.
+ */
+declare function rankItems<T extends RankableItem>(items: readonly T[], options?: RankingOptions): T[];
+//#endregion
 //#region src/tool.d.ts
 /** The ctx.sessionQuery surface this tool consumes (structural, for testability). */
 interface RecallQueryEngine {
@@ -185,4 +251,4 @@ declare const inject: string[];
 /** Plugin entry: mount the `recall` tool on the global tool registry. */
 declare function apply(ctx: Context, config?: RecallConfig): void;
 //#endregion
-export { ALL_PROJECTS_POLICIES, type AllProjectsPolicy, type NormalizedRecallConfig, RECALL_TOOL_DESCRIPTION, REDACTION_MODES, type RecallApprovalVerdict, type RecallApprover, type RecallArgs, type RecallBestMatch, type RecallConfig, type RecallItem, type RecallQueryEngine, type RecallResult, type RecallScope, type RedactionMode, apply, cjkFallbackHint, cjkZeroHitHint, clamp, createRecallTool, cwdAllowed, firstLineClipped, formatDate, hasCJK, id8, inject, name, normalizeQuery, normalizeRecallConfig, normalizeRedactionMode, recallContentBlocks, recallPresentationMeta, redactText, renderRecallText, snippetAround };
+export { ALL_PROJECTS_POLICIES, type AllProjectsPolicy, type NormalizedRecallConfig, RECALL_TOOL_DESCRIPTION, REDACTION_MODES, type RankableItem, type RankingOptions, type RecallApprovalVerdict, type RecallApprover, type RecallArgs, type RecallBestMatch, type RecallConfig, type RecallDiagnostics, type RecallItem, type RecallQueryEngine, type RecallResult, type RecallScope, type RedactionMode, apply, cjkFallbackHint, cjkZeroHitHint, clamp, createRecallTool, cwdAllowed, firstLineClipped, formatDate, hasCJK, id8, inject, name, normalizeQuery, normalizeRecallConfig, normalizeRedactionMode, rankItems, rankingActive, recallContentBlocks, recallPresentationMeta, redactText, renderRecallText, snippetAround };

package/lib/index.js

@@ -95,7 +95,9 @@ function normalizeRecallConfig(config) {
 		redactionMode: normalizeRedactionMode(config?.redactionMode),
 		cwdAllowlist: stringList(config?.cwdAllowlist),
 		cwdDenylist: stringList(config?.cwdDenylist),
-		allProjectsPolicy: normalizePolicy(config?.allProjectsPolicy)
+		allProjectsPolicy: normalizePolicy(config?.allProjectsPolicy),
+		recencyHalfLifeDays: typeof config?.recencyHalfLifeDays === "number" && Number.isFinite(config.recencyHalfLifeDays) && config.recencyHalfLifeDays > 0 ? Math.min(3650, Math.trunc(config.recencyHalfLifeDays)) : void 0,
+		pinnedCwds: stringList(config?.pinnedCwds)
 	};
 }
 /** Whether a session cwd is searchable under the allowlist/denylist policy. */
@@ -106,6 +108,43 @@ function cwdAllowed(cwd, cfg) {
 	return true;
 }
 //#endregion
+//#region src/rank.ts
+/** True when any ranking control is active. */
+function rankingActive(options) {
+	return (options.recencyHalfLifeDays ?? 0) > 0 || (options.pinnedCwds?.length ?? 0) > 0;
+}
+/** One item's decayed weight; rank positions are 1-based. */
+function weight(item, rank, halfLifeDays, now) {
+	const relevance = 1 / rank;
+	if (halfLifeDays === void 0 || halfLifeDays <= 0) return relevance;
+	const matchTime = item.bestMatch.time > 0 ? item.bestMatch.time : item.createdAt;
+	const ageDays = Math.max(0, (now - matchTime) / 864e5);
+	return relevance * Math.pow(.5, ageDays / halfLifeDays);
+}
+/**
+* Re-rank one page of hits. Returns the same item references in a new order;
+* the input is never mutated. With no controls active the input order is
+* returned unchanged.
+*/
+function rankItems(items, options) {
+	if (options === void 0 || !rankingActive(options)) return [...items];
+	const now = options.now ?? Date.now();
+	const halfLife = options.recencyHalfLifeDays;
+	const pinned = new Set(options.pinnedCwds ?? []);
+	const decorated = items.map((item, index) => ({
+		item,
+		index,
+		pinned: item.cwd !== null && pinned.has(item.cwd),
+		score: weight(item, index + 1, halfLife, now)
+	}));
+	decorated.sort((a, b) => {
+		if (a.pinned !== b.pinned) return a.pinned ? -1 : 1;
+		if (b.score !== a.score) return b.score - a.score;
+		return a.index - b.index;
+	});
+	return decorated.map((entry) => entry.item);
+}
+//#endregion
 //#region src/util.ts
 /** Small pure helpers shared by the recall tool and its renderers. */
 /** Clamp `n` into the inclusive `[lo, hi]` range. */
@@ -185,6 +224,8 @@ function renderRecallText(result) {
 	const lines = [];
 	const noun = result.scope.sessionId != null ? "events" : "sessions";
 	lines.push(`Recall "${result.query}" — ${result.count} ${noun}${scopeParts.length > 0 ? ` (${scopeParts.join(", ")})` : ""}`);
+	const diag = diagnosticsLine(result.diagnostics);
+	if (diag !== null) lines.push(diag);
 	if (result.items.length === 0) lines.push("No matches.");
 	else result.items.forEach((item, i) => {
 		lines.push(`${i + 1}. ${sessionLabel(result, i)}`);
@@ -194,6 +235,17 @@ function renderRecallText(result) {
 	if (result.hint != null) lines.push(`Hint: ${result.hint}`);
 	return lines.join("\n");
 }
+/** One compact diagnostics line, only when it carries information. */
+function diagnosticsLine(d) {
+	if (d == null) return null;
+	const parts = [];
+	if (d.source !== "fts") {
+		const scan = d.scanned !== void 0 ? ` (scanned ${d.scanned}${d.scanBudget !== void 0 ? ` of ${d.scanBudget}` : ""})` : "";
+		parts.push(`matched via ${d.source}${scan}`);
+	}
+	if (d.ranked) parts.push("re-ranked: recency decay + pinned projects");
+	return parts.length > 0 ? `Diagnostics: ${parts.join("; ")}` : null;
+}
 /** Content-block projection required by the tool's output declaration. */
 function recallContentBlocks(result) {
 	return [{
@@ -249,6 +301,7 @@ const RECALL_TOOL_DESCRIPTION = [
 	"Use it when the user refers to earlier work (\"that bug we fixed last week\", \"the font we chose for my resume\") or when prior context was compacted away.",
 	"Matches whole words/phrases for English and code identifiers; a zero-hit Chinese (CJK) query automatically falls back to a substring scan in which every whitespace-separated term must match. Returns the best-matching event snippet per session plus the session id.",
 	"Then use the read tool on files, or ask the user, to go deeper — this tool only points at history, it does not resume sessions.",
+	"To save a full evidence report of a hit session, call the transcript_export tool (from dsh-session-export) with its sessionId when available.",
 	"Scoping: by default only sessions started in the current project directory; pass all_projects=true to search everywhere (the deployment may ignore it or require user approval).",
 	"When the deployment enables redaction, secret-looking text in snippets appears as [REDACTED] or a #hash marker — treat it as removed; do not try to reconstruct or echo it.",
 	"The first search after startup may be slow while the index builds."
@@ -282,7 +335,8 @@ function recallError(query, error) {
 		items: [],
 		nextCursor: null,
 		hint: friendlyError(error),
-		redacted: 0
+		redacted: 0,
+		diagnostics: null
 	};
 }
 function brand(value) {
@@ -362,9 +416,9 @@ function cjkTextFilters(query) {
 */
 async function cjkScanSessions(engine, query, agentCwd, wantAll, cfg, scanMax, limit, signal) {
 	const all = await engine.listSessions(signal);
-	const candidates = (!wantAll && agentCwd != null ? all.filter((record) => record.header.cwd === agentCwd) : all).filter((record) => cwdAllowed(record.header.cwd, cfg));
+	const page = (!wantAll && agentCwd != null ? all.filter((record) => record.header.cwd === agentCwd) : all).filter((record) => cwdAllowed(record.header.cwd, cfg)).slice(0, scanMax);
 	const items = [];
-	for (const record of candidates.slice(0, scanMax)) {
+	for (const record of page) {
 		if (items.length >= limit) break;
 		const { filters, highlight } = cjkTextFilters(query);
 		const docs = await engine.filterEvents(record.header.id, filters);
@@ -387,7 +441,11 @@ async function cjkScanSessions(engine, query, agentCwd, wantAll, cfg, scanMax, l
 			}
 		});
 	}
-	return items;
+	return {
+		items,
+		scanned: page.length,
+		budget: scanMax
+	};
 }
 const nullableString = { oneOf: [{ type: "string" }, { type: "null" }] };
 const recallOutputSchema = {
@@ -434,7 +492,24 @@ const recallOutputSchema = {
 		},
 		nextCursor: nullableString,
 		hint: nullableString,
-		redacted: { type: "integer" }
+		redacted: { type: "integer" },
+		diagnostics: { oneOf: [{ type: "null" }, {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				source: {
+					type: "string",
+					enum: [
+						"fts",
+						"cjk-fallback",
+						"session-scan"
+					]
+				},
+				scanned: { type: "integer" },
+				scanBudget: { type: "integer" },
+				ranked: { type: "boolean" }
+			}
+		}] }
 	}
 };
 /**
@@ -546,7 +621,8 @@ function createRecallTool(config, engine, approver) {
 				items: [],
 				nextCursor: null,
 				hint: "the current project directory is excluded by the recall scope policy (cwd allowlist/denylist). Ask the user to adjust the plugin configuration if this is unexpected.",
-				redacted: 0
+				redacted: 0,
+				diagnostics: null
 			};
 			try {
 				if (args.session_id != null && args.session_id !== "") {
@@ -565,13 +641,24 @@ function createRecallTool(config, engine, approver) {
 						items: [],
 						nextCursor: null,
 						hint: "that session belongs to a project directory excluded by the recall scope policy (cwd allowlist/denylist).",
-						redacted: 0
+						redacted: 0,
+						diagnostics: null
 					};
 					let items = eventItems(page, sessionId);
 					let hint = null;
+					let diagnostics = {
+						source: "fts",
+						ranked: false
+					};
 					if (items.length === 0 && hasCJK(query) && cfg.cjkFallback) {
 						const { filters, highlight } = cjkTextFilters(query);
 						const docs = await engine.filterEvents(sessionId, filters);
+						diagnostics = {
+							source: "session-scan",
+							scanned: 1,
+							scanBudget: cfg.cjkFallbackScanMax,
+							ranked: false
+						};
 						if (docs.length > 0) items = docs.slice(0, limit).map((doc) => ({
 							sessionId,
 							id8: id8(sessionId),
@@ -598,7 +685,8 @@ function createRecallTool(config, engine, approver) {
 						items: red.items,
 						nextCursor: page.nextCursor ?? null,
 						hint: joinHints(hint, red.hint),
-						redacted: red.redacted
+						redacted: red.redacted,
+						diagnostics
 					};
 				}
 				const request = {
@@ -612,17 +700,32 @@ function createRecallTool(config, engine, approver) {
 				if (args.cursor != null && args.cursor !== "") request.cursor = brand(args.cursor);
 				const page = await engine.searchSessions(request, { signal: exec.signal });
 				const titles = await titlesFor(engine, page.items.map((hit) => hit.header.id), exec.signal);
-				let items = toItems(page.items, titles).filter((item) => cwdAllowed(item.cwd, cfg));
+				const rankingOptions = {
+					recencyHalfLifeDays: cfg.recencyHalfLifeDays,
+					pinnedCwds: cfg.pinnedCwds
+				};
+				const ranked = rankingActive(rankingOptions);
+				let items = rankItems(toItems(page.items, titles).filter((item) => cwdAllowed(item.cwd, cfg)), rankingOptions);
 				let hint = null;
 				let fallbackRan = false;
+				let diagnostics = {
+					source: "fts",
+					ranked
+				};
 				if (items.length === 0 && hasCJK(query) && cfg.cjkFallback) {
 					fallbackRan = true;
-					const scanned = await cjkScanSessions(engine, query, agentCwd, wantAll, cfg, cfg.cjkFallbackScanMax, limit, exec.signal);
-					const scanTitles = await titlesFor(engine, scanned.map((item) => item.sessionId), exec.signal);
-					items = scanned.map((item) => ({
+					const scan = await cjkScanSessions(engine, query, agentCwd, wantAll, cfg, cfg.cjkFallbackScanMax, limit, exec.signal);
+					const scanTitles = await titlesFor(engine, scan.items.map((item) => item.sessionId), exec.signal);
+					items = rankItems(scan.items.map((item) => ({
 						...item,
 						title: scanTitles.get(item.sessionId) ?? null
-					}));
+					})), rankingOptions);
+					diagnostics = {
+						source: "cjk-fallback",
+						scanned: scan.scanned,
+						scanBudget: scan.budget,
+						ranked
+					};
 					hint = items.length > 0 ? cjkFallbackHint(items.length, cfg.cjkHint) : cjkZeroHitHint(query, true, cfg.cjkHint);
 				} else if (items.length === 0) hint = cjkZeroHitHint(query, true, cfg.cjkHint);
 				const red = applyRedaction(items);
@@ -634,7 +737,8 @@ function createRecallTool(config, engine, approver) {
 					items: red.items,
 					nextCursor: !fallbackRan ? page.nextCursor ?? null : null,
 					hint: joinHints(hint, ...scopeHints, red.hint),
-					redacted: red.redacted
+					redacted: red.redacted,
+					diagnostics
 				};
 			} catch (error) {
 				return recallError(query, error);
@@ -693,4 +797,4 @@ function apply(ctx, config) {
 	}, "session-recall lifecycle");
 }
 //#endregion
-export { ALL_PROJECTS_POLICIES, RECALL_TOOL_DESCRIPTION, REDACTION_MODES, apply, cjkFallbackHint, cjkZeroHitHint, clamp, createRecallTool, cwdAllowed, firstLineClipped, formatDate, hasCJK, id8, inject, name, normalizeQuery, normalizeRecallConfig, normalizeRedactionMode, recallContentBlocks, recallPresentationMeta, redactText, renderRecallText, snippetAround };
+export { ALL_PROJECTS_POLICIES, RECALL_TOOL_DESCRIPTION, REDACTION_MODES, apply, cjkFallbackHint, cjkZeroHitHint, clamp, createRecallTool, cwdAllowed, firstLineClipped, formatDate, hasCJK, id8, inject, name, normalizeQuery, normalizeRecallConfig, normalizeRedactionMode, rankItems, rankingActive, recallContentBlocks, recallPresentationMeta, redactText, renderRecallText, snippetAround };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-session-recall",
   "description": "Deterministic cross-session transcript retrieval for DeepSeek Harness: the model-facing `recall` tool searches past session logs with explicit scope control",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "publishConfig": {
     "access": "public"
   },