dsh-plugin-sessiongraph-tool 0.1.19 → 0.1.20

package/lib/history-hint.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The "this looks like a question about past conversations" reminder.
+ *
+ * The system prompt already says to search the session index instead of grepping `~/.dsh/sessions`.
+ * That is not enough in practice: a memory provider injects its own recall block on every step, so a
+ * model that has just been handed a summary of the past reaches for the summary and never opens the
+ * index. The summary is cheap and always present; the index is one tool call away. This module closes
+ * that gap at the one moment it matters — right before a model request whose user input asks about
+ * something that already happened.
+ *
+ * Three rules keep it from becoming noise:
+ *
+ * - **Only a genuine user input can trigger it.** Injected context, tool results and notices from
+ *   other plugins are user-role messages too, and matching their text would let the reminder trigger
+ *   itself. Only a message whose `source.kind` is `user` is read.
+ * - **Once per conversation, and never after the tool was used.** A conversation that already called
+ *   `sessiongraph` has demonstrated it knows the tool; repeating the advice would spend tokens to say
+ *   nothing new. The state is keyed by agent id, so one session cannot silence another.
+ * - **It rides the admission waterfall, never blocks it.** The listener answers only after `next()`
+ *   resolved, appends to a batch that is already being sent, and returns a rejected decision
+ *   untouched — the reminder can never veto a step or change what a user typed.
+ * @module dsh-plugin-sessiongraph-tool/history-hint
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** `source.kind` of the reminder message, so a later step can tell it apart from real user input. */
+export declare const HISTORY_HINT_SOURCE_KIND = "sessiongraph-hint";
+/**
+ * Words that make a question about the past. Matched as substrings against the user's own text.
+ *
+ * Deliberately broad: a false positive costs one short sentence once per conversation, while a miss
+ * sends the model back to grepping compressed logs and memory summaries. Terms that are equally at
+ * home in a question about the current task (`进度`, `之前`) are kept, because those are exactly the
+ * questions that were answered from memory before this reminder existed.
+ */
+export declare const HISTORY_QUESTION_TERMS: readonly string[];
+/**
+ * A message-shaped reminder, structurally identical to what `dsh-llm`'s `createUserMessage` builds.
+ *
+ * Built as a plain object rather than through `@deepseek-ai/dsh-llm`: that package moves exports
+ * between minor releases, and a static import of a symbol that later moves takes the whole plugin
+ * out of the host. Four lines of local typing do not.
+ */
+export interface HistoryHintMessage {
+    readonly id: string;
+    readonly role: 'user';
+    readonly content: readonly {
+        readonly type: 'text';
+        readonly text: string;
+    }[];
+    readonly source: {
+        readonly kind: string;
+        readonly form: 'notice';
+        readonly summary: string;
+    };
+}
+/** The reminder text. One short paragraph: it is read by a model that already has the system prompt. */
+export declare const HISTORY_HINT_TEXT: string;
+/**
+ * The per-conversation bookkeeping a {@link registerHistoryHint} listener keeps.
+ *
+ * Shared between the pre-step hook and the tools on purpose: the tool reports that a conversation has
+ * already reached the index, which is what turns the reminder off for the rest of that conversation.
+ */
+export interface HistoryHintState {
+    /** Agents that already called the `sessiongraph` tool. */
+    readonly usedBy: Set<string>;
+    /** Agents that already received the reminder. */
+    readonly hintedTo: Set<string>;
+}
+/** A fresh state object; one per plugin registration. */
+export declare function createHistoryHintState(): HistoryHintState;
+/**
+ * Record that a conversation already called the index, which disables the reminder for it.
+ *
+ * A conversation that has seen `sessiongraph` results does not need to be told the tool exists; the
+ * advice would be paid for in tokens and answer a question nobody asked.
+ * @param state - the per-registration bookkeeping.
+ * @param context - the tool execution (or any record carrying `agent.id`).
+ */
+export declare function noteHistoryToolUse(state: HistoryHintState, context: unknown): void;
+/**
+ * Whether one piece of user text reads as a question about the past.
+ * @param text - the user's own words (never injected context).
+ * @returns true when any {@link HISTORY_QUESTION_TERMS} appears in it.
+ */
+export declare function looksLikeHistoryQuestion(text: string): boolean;
+/**
+ * The text of the last message the user actually typed in this batch.
+ *
+ * Only `role: 'user'` with `source.kind: 'user'` counts. Everything else that can carry the user role
+ * — recall blocks, job notices, time context, this module's own reminder — is excluded, because
+ * matching against injected text is how a reminder ends up triggering itself.
+ * @param messages - the batch the host is about to send.
+ * @returns the typed text, or undefined when this batch has none (a tool-only step, for instance).
+ */
+export declare function lastUserText(messages: readonly unknown[] | undefined): string | undefined;
+/**
+ * Build the reminder message.
+ * @returns a frozen, message-shaped reminder with its own id.
+ */
+export declare function buildHistoryHint(): HistoryHintMessage;
+/**
+ * Append the history reminder to the next admitted step, once per conversation.
+ *
+ * Registered per agent rather than globally for the same reason the update notice is: the host's hook
+ * is agent-scoped, `next` only means something inside that scope, and one registration per
+ * conversation is what keeps a reminder out of a session that never asked a history question.
+ * @param ctx - the plugin context.
+ * @param state - the per-registration bookkeeping shared with the tools.
+ */
+export declare function registerHistoryHint(ctx: Context, state: HistoryHintState): void;
+//# sourceMappingURL=history-hint.d.ts.map

package/lib/history-hint.js

@@ -0,0 +1,172 @@
+/**
+ * The "this looks like a question about past conversations" reminder.
+ *
+ * The system prompt already says to search the session index instead of grepping `~/.dsh/sessions`.
+ * That is not enough in practice: a memory provider injects its own recall block on every step, so a
+ * model that has just been handed a summary of the past reaches for the summary and never opens the
+ * index. The summary is cheap and always present; the index is one tool call away. This module closes
+ * that gap at the one moment it matters — right before a model request whose user input asks about
+ * something that already happened.
+ *
+ * Three rules keep it from becoming noise:
+ *
+ * - **Only a genuine user input can trigger it.** Injected context, tool results and notices from
+ *   other plugins are user-role messages too, and matching their text would let the reminder trigger
+ *   itself. Only a message whose `source.kind` is `user` is read.
+ * - **Once per conversation, and never after the tool was used.** A conversation that already called
+ *   `sessiongraph` has demonstrated it knows the tool; repeating the advice would spend tokens to say
+ *   nothing new. The state is keyed by agent id, so one session cannot silence another.
+ * - **It rides the admission waterfall, never blocks it.** The listener answers only after `next()`
+ *   resolved, appends to a batch that is already being sent, and returns a rejected decision
+ *   untouched — the reminder can never veto a step or change what a user typed.
+ * @module dsh-plugin-sessiongraph-tool/history-hint
+ */
+import { randomUUID } from 'node:crypto';
+import { agentIdOf } from "./status-hint.js";
+/** `source.kind` of the reminder message, so a later step can tell it apart from real user input. */
+export const HISTORY_HINT_SOURCE_KIND = 'sessiongraph-hint';
+/**
+ * Words that make a question about the past. Matched as substrings against the user's own text.
+ *
+ * Deliberately broad: a false positive costs one short sentence once per conversation, while a miss
+ * sends the model back to grepping compressed logs and memory summaries. Terms that are equally at
+ * home in a question about the current task (`进度`, `之前`) are kept, because those are exactly the
+ * questions that were answered from memory before this reminder existed.
+ */
+export const HISTORY_QUESTION_TERMS = [
+    '进度',
+    '上次',
+    '之前',
+    '昨天',
+    '前天',
+    '上周',
+    '上个月',
+    '那个会话',
+    '哪个会话',
+    '哪个对话',
+    '说过',
+    '做过',
+    '干过',
+    '聊过',
+    '记得',
+    '当时',
+    '继续上次',
+    'last time',
+    'previously',
+];
+/** The reminder text. One short paragraph: it is read by a model that already has the system prompt. */
+export const HISTORY_HINT_TEXT = '[会话历史提醒] 这个问题像是在问本机过去会话里发生过什么。先用 sessiongraph 查全机会话原文'
+    + '（search 跨会话检索 / timeline 按时间 / session 打开某会话），再用记忆摘要与落盘文件补证；'
+    + '不要只凭记忆摘要作答，也不要 grep ~/.dsh/sessions（zstd 压缩，读不到正文）。';
+/** A fresh state object; one per plugin registration. */
+export function createHistoryHintState() {
+    return { usedBy: new Set(), hintedTo: new Set() };
+}
+/**
+ * Record that a conversation already called the index, which disables the reminder for it.
+ *
+ * A conversation that has seen `sessiongraph` results does not need to be told the tool exists; the
+ * advice would be paid for in tokens and answer a question nobody asked.
+ * @param state - the per-registration bookkeeping.
+ * @param context - the tool execution (or any record carrying `agent.id`).
+ */
+export function noteHistoryToolUse(state, context) {
+    const agentId = agentIdOf(context);
+    if (agentId !== undefined)
+        state.usedBy.add(agentId);
+}
+/**
+ * Whether one piece of user text reads as a question about the past.
+ * @param text - the user's own words (never injected context).
+ * @returns true when any {@link HISTORY_QUESTION_TERMS} appears in it.
+ */
+export function looksLikeHistoryQuestion(text) {
+    const haystack = text.toLowerCase();
+    return HISTORY_QUESTION_TERMS.some(term => haystack.includes(term.toLowerCase()));
+}
+/** Minimal structural read of a message the host put in the admission batch. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * The text of the last message the user actually typed in this batch.
+ *
+ * Only `role: 'user'` with `source.kind: 'user'` counts. Everything else that can carry the user role
+ * — recall blocks, job notices, time context, this module's own reminder — is excluded, because
+ * matching against injected text is how a reminder ends up triggering itself.
+ * @param messages - the batch the host is about to send.
+ * @returns the typed text, or undefined when this batch has none (a tool-only step, for instance).
+ */
+export function lastUserText(messages) {
+    if (!Array.isArray(messages))
+        return undefined;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (!isRecord(message) || message.role !== 'user')
+            continue;
+        const source = message.source;
+        if (!isRecord(source) || source.kind !== 'user')
+            continue;
+        const content = message.content;
+        if (!Array.isArray(content))
+            continue;
+        const text = content
+            .filter((part) => isRecord(part) && part.type === 'text' && typeof part.text === 'string')
+            .map(part => part.text)
+            .join('\n')
+            .trim();
+        if (text !== '')
+            return text;
+    }
+    return undefined;
+}
+/**
+ * Build the reminder message.
+ * @returns a frozen, message-shaped reminder with its own id.
+ */
+export function buildHistoryHint() {
+    return {
+        id: randomUUID(),
+        role: 'user',
+        content: [{ type: 'text', text: HISTORY_HINT_TEXT }],
+        source: {
+            kind: HISTORY_HINT_SOURCE_KIND,
+            form: 'notice',
+            summary: 'sessiongraph: 历史问题先查会话索引',
+        },
+    };
+}
+/**
+ * Append the history reminder to the next admitted step, once per conversation.
+ *
+ * Registered per agent rather than globally for the same reason the update notice is: the host's hook
+ * is agent-scoped, `next` only means something inside that scope, and one registration per
+ * conversation is what keeps a reminder out of a session that never asked a history question.
+ * @param ctx - the plugin context.
+ * @param state - the per-registration bookkeeping shared with the tools.
+ */
+export function registerHistoryHint(ctx, state) {
+    const events = ctx;
+    // Inside an effect so the subscription follows the plugin's own lifetime.
+    ctx.effect(() => events.on('agent/created', payload => {
+        const agentCtx = payload.agent?.ctx;
+        if (agentCtx === undefined)
+            return;
+        const agentId = agentIdOf(payload);
+        agentCtx.on('agent/pre-step', async (stepPayload, next) => {
+            const decision = await next();
+            // A rejected step sends nothing, so there is no batch to put a reminder into.
+            if (decision.kind !== 'enter')
+                return decision;
+            const text = lastUserText(stepPayload.messages);
+            if (text === undefined || !looksLikeHistoryQuestion(text))
+                return decision;
+            const key = agentId ?? 'unknown-agent';
+            if (state.usedBy.has(key) || state.hintedTo.has(key))
+                return decision;
+            state.hintedTo.add(key);
+            return { ...decision, messages: [...decision.messages, buildHistoryHint()] };
+        });
+    }));
+}
+//# sourceMappingURL=history-hint.js.map

package/lib/index.d.ts

@@ -95,6 +95,14 @@ export interface Config {
      * registry GET, so the cost of a shorter interval is latency nobody waits on, not tokens.
      */
     updateCheckIntervalMs?: number;
+    /**
+     * Append one reminder to the model request whose user input looks like a question about past
+     * conversations, when that conversation has not used the index yet (default true). The system
+     * prompt already says to use the index; this is the moment-of-use nudge for a model that has just
+     * been handed a memory summary and would otherwise answer from it. Once per conversation, never
+     * after the tool itself ran.
+     */
+    historyHint?: boolean;
 }
 export declare const Config: z<Config>;
 /**

package/lib/index.js

@@ -27,6 +27,7 @@ import { renderSessiongraph } from "./render.js";
 import { SESSIONGRAPH_DEFAULT_LIMITS, SESSIONGRAPH_INDEX_PARAMETERS, SESSIONGRAPH_OUTPUT_SCHEMA, SESSIONGRAPH_PARAMETERS, } from "./schema.js";
 import { agentIdOf, indexStatusHint } from "./status-hint.js";
 import { createUpdateChecker, defaultStateFile, DEFAULT_UPDATE_CHECK_INTERVAL_MS, readOwnVersion } from "./version-check.js";
+import { createHistoryHintState, noteHistoryToolUse, registerHistoryHint } from "./history-hint.js";
 export { SESSIONGRAPH_DEFAULT_LIMITS, SESSIONGRAPH_ENTRY_KINDS, SESSIONGRAPH_INDEX_PARAMETERS, SESSIONGRAPH_OPERATIONS, SESSIONGRAPH_OUTPUT_SCHEMA, SESSIONGRAPH_PARAMETERS, SESSIONGRAPH_TOOL_OPERATIONS, } from "./schema.js";
 export { clipText, formatBytes, formatDuration, formatLiveReplay, formatLiveSessions, formatTime, renderSessiongraph, STALE_NOTE, } from "./render.js";
 export { LazyIndexRefresher } from "./refresh.js";
@@ -73,6 +74,7 @@ export const Config = z.object({
     indexTimeoutMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_SESSIONGRAPH_INDEX_TIMEOUT_MS),
     updateCheck: z.boolean().default(true),
     updateCheckIntervalMs: z.number().default(DEFAULT_UPDATE_CHECK_INTERVAL_MS),
+    historyHint: z.boolean().default(true),
 });
 /**
  * Register both tools and the system-prompt guidance.
@@ -110,6 +112,10 @@ export function apply(ctx, config) {
         freshnessThresholdMs: resolved.freshnessThresholdMs,
         index: (options, signal) => ctx.sessiongraph.index(indexRoot, options, signal),
     });
+    // Shared between the tools and the pre-step hook: a conversation that already reached the index
+    // must not be told the index exists. Kept even when the hint is off, so turning the reminder back
+    // on mid-process cannot re-nag a conversation that has been using the tool all along.
+    const historyHintState = createHistoryHintState();
     // A function, not a string: the host re-evaluates it on every assembly, which is what lets the model
     // learn whether an index exists for free instead of spending a `status` round-trip. It does one
     // synchronous stat and never opens the index — see `status-hint.ts`.
@@ -129,6 +135,7 @@ export function apply(ctx, config) {
         timeoutMs: resolved.timeoutMs,
         async execute(args, exec) {
             updateChecker?.noteToolUse(agentIdOf(exec));
+            noteHistoryToolUse(historyHintState, exec);
             return runQuery(ctx, refresher, indexRoot, resolved, args, exec);
         },
         presentCall: args => ({
@@ -149,6 +156,7 @@ export function apply(ctx, config) {
         timeoutMs: resolved.indexTimeoutMs,
         async execute(args, exec) {
             updateChecker?.noteToolUse(agentIdOf(exec));
+            noteHistoryToolUse(historyHintState, exec);
             return runIndex(ctx, indexRoot, args, exec);
         },
         presentCall: args => {
@@ -175,6 +183,12 @@ export function apply(ctx, config) {
     // the listener tied to this plugin instance's lifetime.
     if (updateChecker !== undefined)
         registerUpdateNotice(ctx, updateChecker);
+    // The history reminder rides the same waterfall: `agent/pre-step` is the one surface between the
+    // user's input and the next model request, which is exactly where "this looks like a question about
+    // the past, and no summary is allowed to be the evidence" belongs. Registered here for the same
+    // lifetime reason as the notice above.
+    if (resolved.historyHint)
+        registerHistoryHint(ctx, historyHintState);
 }
 /**
  * Append the "a newer release exists" notice to the next admitted step, once per release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-sessiongraph-tool",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Model-facing sessiongraph tools for DeepSeek Harness — a read-only sessiongraph tool that searches the whole local conversation history, plus a sessiongraph_index tool that builds or refreshes the index on its own, much larger timeout budget",
   "keywords": [
     "dsh",
@@ -50,8 +50,8 @@
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "dsh-plugin-sessiongraph-service": "^0.1.19",
-    "dsh-plugin-sessiongraph-sessions": "^0.1.19"
+    "dsh-plugin-sessiongraph-service": "^0.1.20",
+    "dsh-plugin-sessiongraph-sessions": "^0.1.20"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.1",