dsh-session-recall 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kittimzhe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# dsh-session-recall
+
+English | [中文](README.zh.md)
+
+[![npm version](https://img.shields.io/npm/v/dsh-session-recall)](https://www.npmjs.com/package/dsh-session-recall) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Cross-session full-text recall for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): the model-facing `recall` tool lets the agent **search its own past session transcripts** — "that bug we fixed last week", "the font we chose for my resume" — through the trusted `ctx.sessionQuery` seam.
+
+## Why
+
+The official `@deepseek-ai/dsh-session-query` README lists exactly what is missing:
+
+> **No registries or model-facing tool** — … a model-facing tool is absent.
+> **No caller authorization** — … a model tool or UI must constrain which sessions its caller may inspect.
+
+And the shipped web profile mounts its SQLite FTS5 backend with `openAt: never` and an in-memory database — so cross-session full-text search is off by default, and even when enabled the index dies with the process.
+
+| | shipped web profile | + this plugin |
+|---|---|---|
+| Model-facing search tool | absent | **`recall`** |
+| FTS index | `openAt: never` (off) | **on, lazy (`first-search`)** |
+| Index storage | `:memory:` (lost on restart) | **persistent `<DSH_HOME>/session-recall/index.db`** |
+| Caller authorization | caller's responsibility | **cwd-scoped by default, explicit opt-out** |
+
+Memory plugins extract structured notes with an LLM (lossy, costs tokens); `recall` searches the **original transcripts** — zero extraction, zero loss, works retroactively on day one.
+
+## What the model gets
+
+```
+recall({ query })                        → best-matching event per session, current project only
+recall({ query, all_projects: true })    → search every session on the machine
+recall({ query, session_id })            → search the events of one session
+recall({ query, limit, cursor })         → page through results
+```
+
+Each hit carries the session id, title (best-effort), date, and a match snippet; the result renders as a native search card in the Web UI (`SearchMatchesResultView`). Zero-hit CJK queries get a tokenizer hint: the FTS `unicode61` tokenizer indexes uninterrupted CJK runs as single tokens, so the tool teaches the model to retry with short space-separated keywords.
+
+## Scoping (the authorization gap)
+
+`sessionQuery` is trusted infrastructure — it can read every session. This tool therefore constrains each call itself:
+
+- by default, `sessionFilters: [{ kind: 'cwd', values: [<calling agent's cwd>] }]` — only sessions started in the same project directory;
+- `all_projects: true` widens the scope, and only if the deployment allows it (`allowAllProjects: false` disables the argument).
+
+## Install (out-of-tree plugin)
+
+From npm:
+
+```sh
+dsh plugin --profile web add dsh-session-recall
+```
+
+Or from GitHub:
+
+```sh
+dsh plugin --profile web add github:kittimzhe/dsh-session-recall
+```
+
+Then add to the profile's `cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: session-recall
+      name: 'dsh-session-recall'
+```
+
+The bundle's own patch layer turns the persistent index on (`session-query-sqlite` → `openAt: first-search`, `path: <DSH_HOME>/session-recall/index.db`); if you maintain your own override of that row, keep those two values.
+
+## Configuration
+
+Plugin row config (all optional):
+
+```yaml
+- id: session-recall
+  name: 'dsh-session-recall'
+  config:
+    allowAllProjects: true  # honor the tool's all_projects argument
+    defaultLimit: 5         # page size when the model omits limit (1..10)
+    maxLimit: 10            # largest accepted page size (1..25)
+    cjkHint: true           # zero-hit CJK tokenizer workaround hint
+```
+
+## Failure behavior
+
+Every failure returns a friendly `hint` instead of a raw exception: a disabled index explains the two config keys needed, a stale cursor tells the model to restart without one, an unknown `session_id` suggests discovering sessions first. Title enrichment is best-effort — a failed title batch degrades to untitled rows, never a failed search.
+
+## Known limitations
+
+- First search after startup walks the durable logs to build the index (the tool description warns the model); subsequent searches are incremental.
+- `unicode61` matches whole tokens/phrases, not substrings — `AI` does not match `BRAID`. The zero-hit CJK hint mitigates the worst case; a substring fallback via `filterEvents()` is a possible v2.
+- One process must own the index file (single-writer SQLite, per the official backend).
+
+## Development
+
+```sh
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # vitest run
+npm run bundle      # tsdown → lib/
+```
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,104 @@
+# dsh-session-recall
+
+[English](README.md) | 中文
+
+[![npm version](https://img.shields.io/npm/v/dsh-session-recall)](https://www.npmjs.com/package/dsh-session-recall) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+DeepSeek Harness 的跨会话全文回忆插件：注册模型可调用的 `recall` 工具，让 agent 能**检索自己过往的会话原文**——"上周修的那个 bug"、"简历选的什么字体"——全部通过可信的 `ctx.sessionQuery` 缝完成。
+
+## 为什么做这个
+
+官方 `@deepseek-ai/dsh-session-query` 的 README 自己列出了缺口：
+
+> **No registries or model-facing tool** — … a model-facing tool is absent.（没有模型可调用的工具）
+> **No caller authorization** — … a model tool or UI must constrain which sessions its caller may inspect.（调用方授权留给了未来的工具层）
+
+而且官方 web profile 把 SQLite FTS5 后端配置成 `openAt: never` + 内存库——跨会话全文检索默认关闭，就算手动开启，索引也随进程退出而消失。
+
+| | 官方 web 默认 | 装本插件后 |
+|---|---|---|
+| 模型可调用的搜索工具 | 无 | **`recall`** |
+| FTS 索引 | `openAt: never`（关闭） | **开启（懒加载 `first-search`）** |
+| 索引存储 | `:memory:`（重启即失） | **持久化 `<DSH_HOME>/session-recall/index.db`** |
+| 调用方授权 | 留给调用方 | **默认按 cwd 限定当前项目，显式放宽** |
+
+记忆类插件用 LLM 提取结构化笔记（有损、费 token）；`recall` 检索的是**原始对话记录**——零提取、零损失、装完当天就能搜全部历史。
+
+## 模型看到什么
+
+```
+recall({ query })                        → 每个会话返回最强命中事件，默认只搜当前项目
+recall({ query, all_projects: true })    → 搜索本机全部会话
+recall({ query, session_id })            → 只搜指定会话内的事件
+recall({ query, limit, cursor })         → 翻页
+```
+
+每条命中带会话 id、标题（尽力补全）、日期、命中摘录；结果在 Web UI 里渲染成原生搜索卡片（`SearchMatchesResultView`）。CJK 查询零命中时会给出分词提示：FTS 的 `unicode61` 分词器把连续中文当成一个 token，工具会教模型改用空格分隔的短关键词重试。
+
+## 授权边界（官方明确留给工具层的责任）
+
+`sessionQuery` 是可信基础设施——它能读所有会话。所以本工具自己约束每一次调用：
+
+- 默认注入 `sessionFilters: [{ kind: 'cwd', values: [<调用方 agent 的 cwd>] }]`——只搜同一项目目录下开始的会话；
+- `all_projects: true` 才放宽到全机，且部署方可以用 `allowAllProjects: false` 直接禁用该参数。
+
+## 安装（out-of-tree 插件）
+
+从 npm：
+
+```sh
+dsh plugin --profile web add dsh-session-recall
+```
+
+或从 GitHub：
+
+```sh
+dsh plugin --profile web add github:kittimzhe/dsh-session-recall
+```
+
+然后在 profile 的 `cordis.patch.yml` 里加入：
+
+```yaml
+- insert:
+    - id: session-recall
+      name: 'dsh-session-recall'
+```
+
+插件自带 bundle patch 会开启持久化索引（`session-query-sqlite` → `openAt: first-search`、`path: <DSH_HOME>/session-recall/index.db`）；如果你自己覆盖过该行，请保留这两个值。
+
+## 配置
+
+插件行 config（全部可选）：
+
+```yaml
+- id: session-recall
+  name: 'dsh-session-recall'
+  config:
+    allowAllProjects: true  # 是否允许工具的 all_projects 参数
+    defaultLimit: 5         # 模型省略 limit 时的页大小（1..10）
+    maxLimit: 10            # 最大页大小（1..25）
+    cjkHint: true           # CJK 零命中的分词提示开关
+```
+
+## 失败行为
+
+所有失败都返回友好的 `hint` 而不是裸异常：索引未开启会说明需要哪两个配置键；游标失效会告诉模型不带游标重开一次；`session_id` 不存在会建议先做跨会话搜索。标题补全是尽力而为——标题批量读取失败只降级为"无标题"行，绝不让搜索失败。
+
+## 已知限制
+
+- 启动后第一次搜索会扫全量日志建索引（工具描述里已警告模型）；之后增量更新。
+- `unicode61` 按完整 token/短语匹配，不支持子串——`AI` 匹配不到 `BRAID`。CJK 零命中提示缓解了最坏情况；基于 `filterEvents()` 的子串兜底是 v2 方向。
+- 索引文件单进程独占（官方后端的单写者 SQLite 约束）。
+
+## 开发
+
+```sh
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # vitest run
+npm run bundle      # tsdown → lib/
+```
+
+## 许可
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,23 @@
+# The dsh-session-recall bundle patch, applied after every shipped bundle
+# layer (dsh-base, dsh-web-app) and before the user's own profile layer.
+#
+# 1. Turn the opt-in FTS index on and persist it on disk. The shipped web
+#    profile mounts `session-query-sqlite` with `openAt: never` and an
+#    in-memory database, so cross-session full-text search is off and any
+#    manually enabled index dies with the process. `openAt: first-search`
+#    keeps Node 22 startup output clean (the official web-app layer cites the
+#    same reason), and `dshHomePath` is the loader-provided `!!js` helper the
+#    official layers themselves use, so the index lands at
+#    `<DSH_HOME>/session-recall/index.db` whatever DSH_HOME resolves to.
+#    A profile that already pointed this row at its own persistent index can
+#    override either value in its own cordis.patch.yml, which composes later.
+# 2. Mount this plugin's model-facing `recall` tool. Requires the `tools`
+#    and `sessionQuery` services, which dsh-base already provides.
+- id: session-query-sqlite
+  config:
+    openAt: first-search
+    path: !!js dshHomePath('session-recall', 'index.db')
+
+- insert:
+    - id: session-recall
+      name: 'dsh-session-recall'

package/lib/index.d.ts

@@ -0,0 +1,124 @@
+import { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import { SessionEventSearchPage, SessionEventSearchRequest, SessionSearchExecContext, SessionSearchHit, SessionSearchPage, SessionSearchRequest, SessionTitleObservationResult } from "@deepseek-ai/dsh-session-query";
+import { JsonValue } from "@deepseek-ai/dsh-session";
+import { Context } from "@deepseek-ai/cordis";
+import { ContentBlock } from "@deepseek-ai/dsh-llm";
+//#region src/config.d.ts
+/** Plugin-row configuration for dsh-session-recall. */
+interface RecallConfig {
+  /** Honor the tool's `all_projects` argument. Default `true`. */
+  allowAllProjects?: boolean;
+  /** Page size when the model omits `limit`. Default `5`. */
+  defaultLimit?: number;
+  /** Largest accepted page size. Default `10`. */
+  maxLimit?: number;
+  /** Teach the model the CJK tokenizer workaround on zero hits. Default `true`. */
+  cjkHint?: boolean;
+}
+/** Validated, fully defaulted configuration. */
+interface NormalizedRecallConfig {
+  readonly allowAllProjects: boolean;
+  readonly defaultLimit: number;
+  readonly maxLimit: number;
+  readonly cjkHint: boolean;
+}
+/** Default, clamp, and cross-check every optional field. */
+declare function normalizeRecallConfig(config?: RecallConfig): NormalizedRecallConfig;
+//#endregion
+//#region src/types.d.ts
+/** Canonical value types for the `recall` tool's declared output. */
+/** The strongest matching event of one session, as surfaced by the search backend. */
+interface RecallBestMatch {
+  seq: number;
+  type: string;
+  time: number;
+  snippet: string;
+}
+/** One session hit: identity plus its strongest matching event. */
+interface RecallItem {
+  sessionId: string;
+  id8: string;
+  title: string | null;
+  createdAt: number;
+  cwd: string | null;
+  live: boolean;
+  persisted: boolean;
+  bestMatch: RecallBestMatch;
+}
+/** How this call scoped the corpus. */
+interface RecallScope {
+  cwd: string | null;
+  allProjects: boolean;
+  sessionId: string | null;
+}
+/** The `recall` tool's canonical JSON value, validated against the output schema. */
+interface RecallResult {
+  query: string;
+  scope: RecallScope;
+  count: number;
+  hasMore: boolean;
+  items: RecallItem[];
+  nextCursor: string | null;
+  hint: string | null;
+}
+/** The typed model-facing arguments after schema validation. */
+interface RecallArgs {
+  query: string;
+  session_id?: string;
+  all_projects?: boolean;
+  limit?: number;
+  cursor?: string;
+}
+//#endregion
+//#region src/tool.d.ts
+/** The ctx.sessionQuery surface this tool consumes (structural, for testability). */
+interface RecallQueryEngine {
+  searchSessions(request: SessionSearchRequest, exec?: SessionSearchExecContext): Promise<SessionSearchPage<SessionSearchHit>>;
+  searchEvents(request: SessionEventSearchRequest, exec?: SessionSearchExecContext): Promise<SessionEventSearchPage>;
+  readTitleSnapshots(sessionIds: readonly string[], signal?: AbortSignal): Promise<SessionTitleObservationResult[]>;
+}
+declare const RECALL_TOOL_DESCRIPTION: string;
+/**
+ * Build the `recall` ToolDefinition around a concrete sessionQuery engine.
+ * Pure construction — no registration happens here.
+ */
+declare function createRecallTool(config?: RecallConfig, engine?: RecallQueryEngine): ToolDefinition;
+//#endregion
+//#region src/render.d.ts
+/**
+ * Render the compact Markdown the model reads: one header line, one line per
+ * session hit with its best-match event, and a continuation pointer.
+ */
+declare function renderRecallText(result: RecallResult): string;
+/** Content-block projection required by the tool's output declaration. */
+declare function recallContentBlocks(result: RecallResult): ContentBlock[];
+/** Replayable presentation payload consumed by `presentResult` on the UI plane. */
+declare function recallPresentationMeta(result: RecallResult): JsonValue;
+/** The zero-hit CJK tokenizer hint, or `null` when not applicable. */
+declare function cjkZeroHitHint(query: string, zeroHits: boolean, enabled: boolean): string | null;
+//#endregion
+//#region src/util.d.ts
+/** Small pure helpers shared by the recall tool and its renderers. */
+/** Clamp `n` into the inclusive `[lo, hi]` range. */
+declare function clamp(n: number, lo: number, hi: number): number;
+/**
+ * Short session slug for humans: strips the web-profile `session-` prefix and
+ * keeps the first 8 characters of what remains.
+ */
+declare function id8(sessionId: string): string;
+/** Format Unix epoch milliseconds as a local `YYYY-MM-DD` date. */
+declare function formatDate(epochMs: number): string;
+/** Whether `text` contains at least one CJK ideograph, kana, or hangul character. */
+declare function hasCJK(text: string): boolean;
+/** Collapse every whitespace run and trim; used to normalize model-supplied queries. */
+declare function normalizeQuery(text: string): string;
+/** First line of `text` with control characters stripped, clipped to `limit` code points. */
+declare function firstLineClipped(text: string, limit: number): string;
+//#endregion
+//#region src/index.d.ts
+declare const name = "session-recall";
+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 { type NormalizedRecallConfig, RECALL_TOOL_DESCRIPTION, type RecallArgs, type RecallBestMatch, type RecallConfig, type RecallItem, type RecallQueryEngine, type RecallResult, type RecallScope, apply, cjkZeroHitHint, clamp, createRecallTool, firstLineClipped, formatDate, hasCJK, id8, inject, name, normalizeQuery, normalizeRecallConfig, recallContentBlocks, recallPresentationMeta, renderRecallText };

package/lib/index.js

@@ -0,0 +1,390 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { SessionSearchCursor } from "@deepseek-ai/dsh-session-query";
+import { SessionId } from "@deepseek-ai/dsh-session";
+function intIn(value, fallback, lo, hi) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+	return Math.min(hi, Math.max(lo, Math.trunc(value)));
+}
+/** Default, clamp, and cross-check every optional field. */
+function normalizeRecallConfig(config) {
+	const defaultLimit = intIn(config?.defaultLimit, 5, 1, 10);
+	return {
+		allowAllProjects: config?.allowAllProjects !== false,
+		defaultLimit,
+		maxLimit: Math.max(defaultLimit, intIn(config?.maxLimit, 10, 1, 25)),
+		cjkHint: config?.cjkHint !== false
+	};
+}
+//#endregion
+//#region src/util.ts
+/** Small pure helpers shared by the recall tool and its renderers. */
+/** Clamp `n` into the inclusive `[lo, hi]` range. */
+function clamp(n, lo, hi) {
+	return Math.min(hi, Math.max(lo, n));
+}
+/**
+* Short session slug for humans: strips the web-profile `session-` prefix and
+* keeps the first 8 characters of what remains.
+*/
+function id8(sessionId) {
+	return (sessionId.startsWith("session-") ? sessionId.slice(8) : sessionId).slice(0, 8);
+}
+/** Format Unix epoch milliseconds as a local `YYYY-MM-DD` date. */
+function formatDate(epochMs) {
+	const d = new Date(epochMs);
+	const m = String(d.getMonth() + 1).padStart(2, "0");
+	const day = String(d.getDate()).padStart(2, "0");
+	return `${d.getFullYear()}-${m}-${day}`;
+}
+const CJK_RE = /[\u{3400}-\u{4DBF}\u{4E00}-\u{9FFF}\u{F900}-\u{FAFF}\u{3040}-\u{30FF}\u{AC00}-\u{D7AF}\u{3000}-\u{303F}]/u;
+/** Whether `text` contains at least one CJK ideograph, kana, or hangul character. */
+function hasCJK(text) {
+	return CJK_RE.test(text);
+}
+/** Collapse every whitespace run and trim; used to normalize model-supplied queries. */
+function normalizeQuery(text) {
+	return text.trim().replaceAll(/\s+/g, " ");
+}
+/** First line of `text` with control characters stripped, clipped to `limit` code points. */
+function firstLineClipped(text, limit) {
+	const line = text.split("\n", 1)[0] ?? "";
+	let out = "";
+	for (const ch of line) {
+		if ((ch.codePointAt(0) ?? 0) < 32) continue;
+		out += ch;
+		if (out.length >= limit) break;
+	}
+	return out;
+}
+//#endregion
+//#region src/render.ts
+const SNIPPET_CHARS = 120;
+function sessionLabel(result, index) {
+	const item = result.items[index];
+	if (!item) return String(index + 1);
+	return `${item.title ? firstLineClipped(item.title, 48) : `untitled ${item.id8}`} (${item.id8}, ${formatDate(item.createdAt)}${item.live ? ", live" : ""})`;
+}
+/**
+* Render the compact Markdown the model reads: one header line, one line per
+* session hit with its best-match event, and a continuation pointer.
+*/
+function renderRecallText(result) {
+	const scopeParts = [];
+	if (result.scope.sessionId != null) scopeParts.push(`session ${result.scope.sessionId}`);
+	else if (result.scope.allProjects) scopeParts.push("all projects");
+	else if (result.scope.cwd != null) scopeParts.push(`cwd ${result.scope.cwd}`);
+	const lines = [];
+	const noun = result.scope.sessionId != null ? "events" : "sessions";
+	lines.push(`Recall "${result.query}" — ${result.count} ${noun}${scopeParts.length > 0 ? ` (${scopeParts.join(", ")})` : ""}`);
+	if (result.items.length === 0) lines.push("No matches.");
+	else result.items.forEach((item, i) => {
+		lines.push(`${i + 1}. ${sessionLabel(result, i)}`);
+		lines.push(`   ${item.bestMatch.type} #${item.bestMatch.seq}: ${firstLineClipped(item.bestMatch.snippet, SNIPPET_CHARS)}`);
+	});
+	if (result.hasMore && result.nextCursor != null) lines.push(`More: re-call with cursor="${result.nextCursor}"`);
+	if (result.hint != null) lines.push(`Hint: ${result.hint}`);
+	return lines.join("\n");
+}
+/** Content-block projection required by the tool's output declaration. */
+function recallContentBlocks(result) {
+	return [{
+		type: "text",
+		text: renderRecallText(result)
+	}];
+}
+/** Replayable presentation payload consumed by `presentResult` on the UI plane. */
+function recallPresentationMeta(result) {
+	return {
+		query: result.query,
+		count: result.count,
+		hasMore: result.hasMore,
+		items: result.items.map((item) => ({
+			sessionId: item.sessionId,
+			id8: item.id8,
+			label: item.title ?? `untitled ${item.id8}`,
+			createdAt: item.createdAt,
+			seq: item.bestMatch.seq,
+			snippet: firstLineClipped(item.bestMatch.snippet, SNIPPET_CHARS)
+		}))
+	};
+}
+/** The zero-hit CJK tokenizer hint, or `null` when not applicable. */
+function cjkZeroHitHint(query, zeroHits, enabled) {
+	if (!enabled || !zeroHits || !hasCJK(query)) return null;
+	return "no hits for a CJK query — the FTS unicode61 tokenizer indexes uninterrupted CJK runs as single tokens. Retry with short space-separated keywords (e.g. \"简历 模板\" instead of \"我的简历模板在这里\"), or an English term.";
+}
+//#endregion
+//#region src/tool.ts
+/**
+* The `recall` tool: model-facing cross-session full-text search over the
+* trusted `ctx.sessionQuery` seam.
+*
+* The official `@deepseek-ai/dsh-session-query` service deliberately ships no
+* model-facing tool ("No registries or model-facing tool — … a model-facing
+* tool is absent") and no caller authorization ("a model tool or UI must
+* constrain which sessions its caller may inspect"). This plugin fills both
+* gaps: it registers one typed `recall` tool and constrains every call to the
+* calling agent's own project cwd unless the model explicitly widens the
+* scope and the deployment allows it.
+*/
+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 (English and code identifiers work best); 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.",
+	"Scoping: by default only sessions started in the current project directory; pass all_projects=true to search everywhere.",
+	"The first search after startup may be slow while the index builds."
+].join(" ");
+function errCode(error) {
+	return typeof error === "object" && error !== null && "code" in error ? String(error.code) : void 0;
+}
+function friendlyError(error) {
+	const code = errCode(error);
+	switch (code) {
+		case "SESSION_QUERY_SEARCH_DISABLED": return "full-text search is disabled for this deployment: the session-query backend row needs a dedicated on-disk path and an openAt of 'first-search' or 'startup'. This plugin's bundle patch already sets that for shipped web profiles — if you overrode the session-query-sqlite row yourself, check its config.";
+		case "SESSION_QUERY_INVALID_CURSOR":
+		case "SESSION_QUERY_STALE_CURSOR": return "the cursor is stale (the index moved on). Start a fresh recall call without a cursor.";
+		case "SESSION_QUERY_SESSION_NOT_FOUND": return "no session with that session_id exists. Search without session_id to discover candidate sessions first.";
+		case "SESSION_QUERY_INVALID_QUERY": return "the query was empty after trimming. Pass a non-empty search phrase.";
+		case "SESSION_QUERY_INVALID_LIMIT": return "the limit was out of range. Pass an integer between 1 and the deployment max (default 10).";
+		case "SESSION_QUERY_ABORTED": return "the search was cancelled before it finished.";
+		default: return `session search failed${code != null ? ` (${code})` : ""}: ${error instanceof Error ? error.message : String(error)}`;
+	}
+}
+function recallError(query, error) {
+	return {
+		query,
+		scope: {
+			cwd: null,
+			allProjects: false,
+			sessionId: null
+		},
+		count: 0,
+		hasMore: false,
+		items: [],
+		nextCursor: null,
+		hint: friendlyError(error)
+	};
+}
+function brand(value) {
+	return value == null || value === "" ? void 0 : SessionSearchCursor(value);
+}
+/** Best-effort title enrichment; a failed batch degrades to untitled rows. */
+async function titlesFor(engine, sessionIds, signal) {
+	const map = /* @__PURE__ */ new Map();
+	if (sessionIds.length === 0) return map;
+	try {
+		const results = await engine.readTitleSnapshots(sessionIds, signal);
+		for (const r of results) map.set(r.sessionId, r.status === "fulfilled" ? r.value.title?.title ?? null : null);
+	} catch {}
+	return map;
+}
+function toItems(hits, titles) {
+	return hits.map((hit) => ({
+		sessionId: hit.header.id,
+		id8: id8(hit.header.id),
+		title: titles.get(hit.header.id) ?? null,
+		createdAt: hit.header.createdAt,
+		cwd: hit.header.cwd ?? null,
+		live: hit.live,
+		persisted: hit.persisted,
+		bestMatch: {
+			seq: hit.bestMatch.seq,
+			type: hit.bestMatch.type,
+			time: hit.bestMatch.time,
+			snippet: hit.bestMatch.snippet
+		}
+	}));
+}
+function eventItems(page, sessionId) {
+	return page.items.map((event) => ({
+		sessionId,
+		id8: id8(sessionId),
+		title: null,
+		createdAt: page.session.createdAt,
+		cwd: page.session.cwd ?? null,
+		live: true,
+		persisted: false,
+		bestMatch: {
+			seq: event.seq,
+			type: event.type,
+			time: event.time,
+			snippet: event.snippet
+		}
+	}));
+}
+const nullableString = { oneOf: [{ type: "string" }, { type: "null" }] };
+const recallOutputSchema = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		query: { type: "string" },
+		scope: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				cwd: nullableString,
+				allProjects: { type: "boolean" },
+				sessionId: nullableString
+			}
+		},
+		count: { type: "integer" },
+		hasMore: { type: "boolean" },
+		items: {
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					sessionId: { type: "string" },
+					id8: { type: "string" },
+					title: nullableString,
+					createdAt: { type: "integer" },
+					cwd: nullableString,
+					live: { type: "boolean" },
+					persisted: { type: "boolean" },
+					bestMatch: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							seq: { type: "integer" },
+							type: { type: "string" },
+							time: { type: "integer" },
+							snippet: { type: "string" }
+						}
+					}
+				}
+			}
+		},
+		nextCursor: nullableString,
+		hint: nullableString
+	}
+};
+/**
+* Build the `recall` ToolDefinition around a concrete sessionQuery engine.
+* Pure construction — no registration happens here.
+*/
+function createRecallTool(config, engine) {
+	const cfg = normalizeRecallConfig(config);
+	return defineTool({
+		name: "recall",
+		description: RECALL_TOOL_DESCRIPTION,
+		timeoutMs: 1e4,
+		isConcurrencySafe: () => true,
+		parameters: {
+			query: {
+				type: "string",
+				required: true,
+				description: "Literal phrase to search for in past transcript text (word/phrase match, not regex; FTS operators are treated as data)."
+			},
+			session_id: {
+				type: "string",
+				description: "Restrict the search to events of this one session (use after a cross-session hit pointed you here)."
+			},
+			all_projects: {
+				type: "boolean",
+				description: "Search sessions from ALL project directories instead of only the current one. Ignored when the deployment disallows it."
+			},
+			limit: {
+				type: "integer",
+				description: `Page size, default ${cfg.defaultLimit}, at most ${cfg.maxLimit}.`
+			},
+			cursor: {
+				type: "string",
+				description: "Opaque continuation cursor from a previous recall result with hasMore=true."
+			}
+		},
+		output: {
+			schema: recallOutputSchema,
+			render: (_args, value) => recallContentBlocks(value),
+			presentationMeta: (_args, value) => recallPresentationMeta(value)
+		},
+		async execute(args, exec) {
+			const query = normalizeQuery(args.query);
+			if (engine == null) return recallError(query, /* @__PURE__ */ new Error("no sessionQuery engine was wired into this plugin instance"));
+			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 wantAll = args.all_projects === true && cfg.allowAllProjects;
+			const scope = {
+				cwd: agentCwd,
+				allProjects: wantAll,
+				sessionId: args.session_id ?? null
+			};
+			try {
+				if (args.session_id != null && args.session_id !== "") {
+					const sessionId = SessionId(args.session_id);
+					const page = await engine.searchEvents({
+						sessionId,
+						query,
+						limit,
+						cursor: brand(args.cursor)
+					}, { signal: exec.signal });
+					const items = eventItems(page, sessionId);
+					return {
+						query,
+						scope,
+						count: items.length,
+						hasMore: page.nextCursor != null,
+						items,
+						nextCursor: page.nextCursor ?? null,
+						hint: cjkZeroHitHint(query, items.length === 0, cfg.cjkHint)
+					};
+				}
+				const request = {
+					query,
+					limit
+				};
+				if (!wantAll && agentCwd != null) request.sessionFilters = [{
+					kind: "cwd",
+					values: [agentCwd]
+				}];
+				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);
+				const items = toItems(page.items, titles);
+				return {
+					query,
+					scope,
+					count: items.length,
+					hasMore: page.nextCursor != null,
+					items,
+					nextCursor: page.nextCursor ?? null,
+					hint: cjkZeroHitHint(query, items.length === 0, cfg.cjkHint)
+				};
+			} catch (error) {
+				return recallError(query, error);
+			}
+		},
+		presentResult: (_args, result) => {
+			const meta = result.meta;
+			if (meta == null || !Array.isArray(meta.items)) return void 0;
+			return {
+				card: "search",
+				shape: "matches",
+				title: `recall "${meta.query}"`,
+				files: meta.items.map((item) => ({
+					path: `${item.label} · ${item.id8}`,
+					matches: [{
+						lineNumber: item.seq,
+						line: item.snippet
+					}]
+				})),
+				truncated: meta.hasMore,
+				total: meta.count
+			};
+		}
+	});
+}
+//#endregion
+//#region src/index.ts
+const name = "session-recall";
+const inject = ["tools", "sessionQuery"];
+/** Plugin entry: mount the `recall` tool on the global tool registry. */
+function apply(ctx, config) {
+	ctx.effect(function* () {
+		yield ctx.tools.register(createRecallTool(config, ctx.sessionQuery));
+	}, "session-recall lifecycle");
+}
+//#endregion
+export { RECALL_TOOL_DESCRIPTION, apply, cjkZeroHitHint, clamp, createRecallTool, firstLineClipped, formatDate, hasCJK, id8, inject, name, normalizeQuery, normalizeRecallConfig, recallContentBlocks, recallPresentationMeta, renderRecallText };

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "dsh-session-recall",
+  "description": "Cross-session full-text recall for DeepSeek Harness: the model-facing `recall` tool searches past session transcripts through ctx.sessionQuery",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "README.md",
+    "README.zh.md",
+    "LICENSE",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "license": "MIT",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "session",
+    "search",
+    "recall",
+    "memory",
+    "full-text-search"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session-query": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session-query": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^26.2.0",
+    "js-yaml": "^4.2.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}