dsh-session-recall 0.5.1 → 0.7.0

package/README.md

@@ -21,7 +21,7 @@ If you need agent memory orchestration, use a memory framework; if you need boun
 | Capability focus | Memory frameworks | Generic transcript search | `dsh-session-recall` |
 |---|---|---|---|
 | Retrieval target | Derived memory objects | Varies by implementation | **Original session transcript events** |
-| Scope control | Framework-specific | Often coarse | **cwd-scoped default + explicit `all_projects` gate** |
+| Scope control | Framework-specific | Often coarse | **cwd-scoped default + explicit `all_projects`, `since_days`, `tools`, `errors_only` gate** |
 | CJK behavior | Framework-specific | Often tokenizer-limited | **FTS + CJK zero-hit substring fallback** |
 | Output contract | Usually framework-native | Varies | **Typed `recall` result with stable fields/hints** |
 

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 import { ToolDefinition, ToolRunContext } from "@deepseek-ai/dsh-tools";
-import { SessionEventResultFilter, SessionEventSearchDocument, SessionEventSearchPage, SessionEventSearchRequest, SessionRecord, SessionSearchExecContext, SessionSearchHit, SessionSearchPage, SessionSearchRequest, SessionTitleObservationResult } from "@deepseek-ai/dsh-session-query";
+import { SessionEventResultFilter, SessionEventSearchDocument, SessionEventSearchPage, SessionEventSearchRequest, SessionLineageTrace, SessionRecord, SessionSearchExecContext, SessionSearchHit, SessionSearchPage, SessionSearchRequest, SessionTitleObservationResult } from "@deepseek-ai/dsh-session-query";
 import { JsonValue, SessionId } from "@deepseek-ai/dsh-session";
 import { Context } from "@deepseek-ai/cordis";
 import { ContentBlock } from "@deepseek-ai/dsh-llm";
@@ -50,6 +50,12 @@ interface RecallConfig {
   recencyHalfLifeDays?: number;
   /** Sessions started in these project directories rank first. Default: none. */
   pinnedCwds?: readonly string[];
+  /**
+   * Restrict recall results to sessions in the calling agent's own lineage
+   * (ancestors + self + descendants). Default `true` — other agents in the
+   * same project are invisible unless this is set to `false`.
+   */
+  callerTreeOnly?: boolean;
 }
 /** Validated, fully defaulted configuration. */
 interface NormalizedRecallConfig {
@@ -65,6 +71,7 @@ interface NormalizedRecallConfig {
   readonly allProjectsPolicy: AllProjectsPolicy;
   readonly recencyHalfLifeDays: number | undefined;
   readonly pinnedCwds: readonly string[];
+  readonly callerTreeOnly: boolean;
 }
 /** Default, clamp, and cross-check every optional field. */
 declare function normalizeRecallConfig(config?: RecallConfig): NormalizedRecallConfig;
@@ -129,6 +136,12 @@ interface RecallArgs {
   all_projects?: boolean;
   limit?: number;
   cursor?: string;
+  /** Only return sessions/entries newer than this many days. */
+  since_days?: number;
+  /** Only return tool-related events whose tool name matches one of these (substring, case-insensitive). */
+  tools?: readonly string[];
+  /** Only return failed tool calls (tool results carrying an error). */
+  errors_only?: boolean;
 }
 //#endregion
 //#region src/rank.d.ts
@@ -186,6 +199,8 @@ interface RecallQueryEngine {
   readTitleSnapshots(sessionIds: readonly string[], signal?: AbortSignal): Promise<SessionTitleObservationResult[]>;
   listSessions(signal?: AbortSignal): Promise<SessionRecord[]>;
   filterEvents(sessionId: SessionId, filters: readonly SessionEventResultFilter[]): Promise<SessionEventSearchDocument[]>;
+  /** Trace the caller's session lineage for caller-authorization gating. */
+  traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>;
 }
 declare const RECALL_TOOL_DESCRIPTION: string;
 /** The approval verdict vocabulary mirrored from `@deepseek-ai/dsh-user-approval`. */

package/lib/index.js

@@ -97,7 +97,8 @@ function normalizeRecallConfig(config) {
 		cwdDenylist: stringList(config?.cwdDenylist),
 		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)
+		pinnedCwds: stringList(config?.pinnedCwds),
+		callerTreeOnly: config?.callerTreeOnly !== false
 	};
 }
 /** Whether a session cwd is searchable under the allowlist/denylist policy. */
@@ -296,13 +297,55 @@ function cjkZeroHitHint(query, zeroHits, enabled) {
 * calling agent's own project cwd unless the model explicitly widens the
 * scope and the deployment allows it.
 */
+/** Whether a best-match event type is a tool result (vs user/assistant message). */
+function isToolResultType(type) {
+	return type === "tool/result" || type.startsWith("tool/");
+}
+/** Apply the dimensional post-filters (sinceDays / tools / errorsOnly) to recall items. */
+function applyDimensionFilters(items, args, now = Date.now()) {
+	let out = [...items];
+	if (args.since_days !== void 0 && args.since_days > 0) {
+		const cutoff = now - args.since_days * 864e5;
+		out = out.filter((item) => {
+			return Math.max(item.createdAt ?? 0, item.bestMatch?.time ?? 0) >= cutoff;
+		});
+	}
+	if (args.tools !== void 0 && args.tools.length > 0) {
+		const needles = args.tools.map((t) => t.toLowerCase());
+		out = out.filter((item) => {
+			if (!isToolResultType(item.bestMatch?.type ?? "")) return false;
+			const snippet = (item.bestMatch?.snippet ?? "").toLowerCase();
+			return needles.some((n) => snippet.includes(n));
+		});
+	}
+	if (args.errors_only === true) out = out.filter((item) => {
+		if ((item.bestMatch?.type ?? "") !== "tool/result") return false;
+		const snippet = item.bestMatch?.snippet ?? "";
+		return snippet.includes("[error]") || /\berror\b|\bfailed\b/i.test(snippet);
+	});
+	return out;
+}
+/** Walk a lineage trace and collect every session id in the tree. */
+function collectLineageIds(trace) {
+	const ids = /* @__PURE__ */ new Set();
+	ids.add(trace.target.header.id);
+	for (const ancestor of trace.ancestors) ids.add(ancestor.header.id);
+	const walk = (nodes) => {
+		for (const node of nodes) {
+			ids.add(node.session.header.id);
+			walk(node.descendants);
+		}
+	};
+	walk(trace.descendants);
+	return ids;
+}
 const RECALL_TOOL_DESCRIPTION = [
 	"Search the FULL TEXT of past and current session transcripts on this machine (your own conversation history with this user).",
 	"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).",
+	"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). Narrow further with since_days (only sessions newer than N days), tools (only tool events whose tool name matches, e.g. tools=[\"bash\"]), or errors_only=true (only failed tool calls).",
 	"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."
 ].join(" ");
@@ -585,6 +628,19 @@ function createRecallTool(config, engine, approver) {
 			cursor: {
 				type: "string",
 				description: "Opaque continuation cursor from a previous recall result with hasMore=true."
+			},
+			since_days: {
+				type: "integer",
+				description: "Only return sessions newer than this many days (0 = no time filter)."
+			},
+			tools: {
+				type: "array",
+				items: { type: "string" },
+				description: "Only return tool events whose tool name contains one of these substrings (case-insensitive), e.g. [\"bash\",\"read\"]."
+			},
+			errors_only: {
+				type: "boolean",
+				description: "Only return failed tool calls (tool results carrying an error)."
 			}
 		},
 		output: {
@@ -598,6 +654,11 @@ function createRecallTool(config, engine, approver) {
 			if (query === "") return recallError(query, Object.assign(/* @__PURE__ */ new Error("empty query"), { code: "SESSION_QUERY_INVALID_QUERY" }));
 			const limit = clamp(Math.trunc(args.limit ?? cfg.defaultLimit), 1, cfg.maxLimit);
 			const agentCwd = exec.agent?.session.header?.cwd ?? null;
+			const callerSessionId = exec.agent?.session?.id;
+			let allowedIds = null;
+			if (cfg.callerTreeOnly && callerSessionId != null) try {
+				allowedIds = collectLineageIds(await engine.traceSession(SessionId(callerSessionId), exec.signal));
+			} catch {}
 			const scopeHints = [];
 			let wantAll = false;
 			if (args.session_id == null && args.all_projects === true) {
@@ -633,6 +694,17 @@ function createRecallTool(config, engine, approver) {
 						limit,
 						cursor: brand(args.cursor)
 					}, { signal: exec.signal });
+					if (allowedIds != null && !allowedIds.has(args.session_id)) return {
+						query,
+						scope,
+						count: 0,
+						hasMore: false,
+						items: [],
+						nextCursor: null,
+						hint: "that session is outside your conversation lineage. Search without session_id to find sessions in your own tree, or ask the user to disable callerTreeOnly.",
+						redacted: 0,
+						diagnostics: null
+					};
 					if (!cwdAllowed(page.session.cwd ?? null, cfg)) return {
 						query,
 						scope,
@@ -644,7 +716,7 @@ function createRecallTool(config, engine, approver) {
 						redacted: 0,
 						diagnostics: null
 					};
-					let items = eventItems(page, sessionId);
+					let items = applyDimensionFilters(eventItems(page, sessionId), args);
 					let hint = null;
 					let diagnostics = {
 						source: "fts",
@@ -659,7 +731,7 @@ function createRecallTool(config, engine, approver) {
 							scanBudget: cfg.cjkFallbackScanMax,
 							ranked: false
 						};
-						if (docs.length > 0) items = docs.slice(0, limit).map((doc) => ({
+						if (docs.length > 0) items = applyDimensionFilters(docs.slice(0, limit).map((doc) => ({
 							sessionId,
 							id8: id8(sessionId),
 							title: null,
@@ -673,7 +745,7 @@ function createRecallTool(config, engine, approver) {
 								time: doc.time,
 								snippet: snippetAround(doc.text, highlight, CJK_SNIPPET_CHARS)
 							}
-						}));
+						})), args);
 						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);
@@ -706,6 +778,8 @@ function createRecallTool(config, engine, approver) {
 				};
 				const ranked = rankingActive(rankingOptions);
 				let items = rankItems(toItems(page.items, titles).filter((item) => cwdAllowed(item.cwd, cfg)), rankingOptions);
+				if (allowedIds != null) items = items.filter((item) => allowedIds.has(item.sessionId));
+				items = applyDimensionFilters(items, args);
 				let hint = null;
 				let fallbackRan = false;
 				let diagnostics = {
@@ -716,7 +790,7 @@ function createRecallTool(config, engine, approver) {
 					fallbackRan = true;
 					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) => ({
+					items = rankItems(scan.items.filter((item) => allowedIds == null || allowedIds.has(item.sessionId)).map((item) => ({
 						...item,
 						title: scanTitles.get(item.sessionId) ?? null
 					})), rankingOptions);

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.5.1",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },