dsh-session-recall 0.7.3 → 0.7.5

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 import { ToolDefinition, ToolRunContext } from "@deepseek-ai/dsh-tools";
 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 { SessionId } from "@deepseek-ai/dsh-session";
 import { Context } from "@deepseek-ai/cordis";
 import { ContentBlock } from "@deepseek-ai/dsh-llm";
 //#region src/redact.d.ts
@@ -56,6 +56,19 @@ interface RecallConfig {
    * same project are invisible unless this is set to `false`.
    */
   callerTreeOnly?: boolean;
+  /**
+   * When the session index itself fails (`SESSION_QUERY_PERSISTENCE_FAILED`,
+   * e.g. one un-migratable artifact failing every indexed search —
+   * deepseek-harness discussion #7995), retry with a direct scan of the
+   * persisted session logs instead of failing the call. Default `true`.
+   */
+  rawScanFallback?: boolean;
+  /** Max persisted sessions visited by one degraded raw scan. Default `200`. */
+  rawScanMaxSessions?: number;
+  /** Wall-clock ceiling (ms) for one degraded raw scan. Default `20000`. */
+  rawScanMaxDurationMs?: number;
+  /** Compressed-size ceiling (bytes) per session log in a degraded scan. Default 8 MiB. */
+  rawScanMaxSessionBytes?: number;
 }
 /** Validated, fully defaulted configuration. */
 interface NormalizedRecallConfig {
@@ -72,6 +85,10 @@ interface NormalizedRecallConfig {
   readonly recencyHalfLifeDays: number | undefined;
   readonly pinnedCwds: readonly string[];
   readonly callerTreeOnly: boolean;
+  readonly rawScanFallback: boolean;
+  readonly rawScanMaxSessions: number;
+  readonly rawScanMaxDurationMs: number;
+  readonly rawScanMaxSessionBytes: number;
 }
 /** Default, clamp, and cross-check every optional field. */
 declare function normalizeRecallConfig(config?: RecallConfig): NormalizedRecallConfig;
@@ -107,7 +124,7 @@ interface RecallScope {
 /** 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';
+  readonly source: 'fts' | 'cjk-fallback' | 'session-scan' | 'raw-scan';
   /** Sessions visited by the fallback scan, when it ran. */
   readonly scanned?: number;
   /** The fallback scan budget (`cjkFallbackScanMax`), when a scan ran. */
@@ -209,7 +226,8 @@ type RecallApprovalVerdict = 'allowed-once' | 'rejected' | 'cancelled' | 'unavai
  * Optional user-approval seam for the `all_projects` gate (`allProjectsPolicy:
  * 'confirm'`). Receives the tool run context (for the agent) and a
  * human-readable reason; `'allowed-once'` is the only grant. Wired from
- * `ctx.approval` in the plugin entry; fail-closed when absent.
+ * `ctx.get('approval')` in the plugin entry (optional service, not in
+ * `inject`); fail-closed when absent.
  */
 type RecallApprover = (exec: ToolRunContext, reason: string) => Promise<RecallApprovalVerdict>;
 /**
@@ -218,6 +236,13 @@ type RecallApprover = (exec: ToolRunContext, reason: string) => Promise<RecallAp
  */
 declare function createRecallTool(config?: RecallConfig, engine?: RecallQueryEngine, approver?: RecallApprover): ToolDefinition;
 //#endregion
+//#region node_modules/@deepseek-ai/dsh-util-values/lib/types/index.d.ts
+/** Duplicate-install-safe JSON and immutable-value helpers. @module @deepseek-ai/dsh-util-values */
+/** A value that round-trips through JSON without loss. */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+//#endregion
 //#region src/render.d.ts
 /**
  * Render the compact Markdown the model reads: one header line, one line per
@@ -236,6 +261,70 @@ declare function cjkFallbackHint(matched: number, enabled: boolean): string | nu
 /** The zero-hit hint, shown only when both the full-text and substring paths miss. */
 declare function cjkZeroHitHint(query: string, zeroHits: boolean, enabled: boolean): string | null;
 //#endregion
+//#region src/resilient.d.ts
+/** Default scan budget (sessions visited per degraded call). */
+declare const RAW_SCAN_DEFAULT_MAX_SESSIONS = 300;
+/** Hard ceiling for the scan budget. */
+declare const RAW_SCAN_MAX_SESSIONS_MAX = 2000;
+/** Where the harness persists sessions: `$DSH_HOME/sessions` (default `~/.dsh/sessions`). */
+declare function discoverSessionsRoot(): string;
+/** True when an error means "the index is unavailable", not "the query was bad". */
+declare function isIndexOutage(error: unknown): boolean;
+interface RawScanOptions {
+  /** Sessions root (workspace directories below this). */
+  root: string;
+  /** Normalized search query; whitespace-separated terms, all must match. */
+  query: string;
+  /** Restrict to sessions started in this cwd (unless `allProjects`). */
+  cwd: string | null;
+  /** Ignore the cwd scope. */
+  allProjects: boolean;
+  /** Restrict to one session id (the `session_id` argument), or null. */
+  sessionId: string | null;
+  /** Only sessions newer than this many days (0 = no time filter). */
+  sinceDays: number;
+  /** Only tool events whose tool name contains one of these substrings. */
+  tools: readonly string[] | null;
+  /** Only failed tool calls (tool results carrying an error flag). */
+  errorsOnly: boolean;
+  /** Max sessions to return. */
+  limit: number;
+  /** Scan budget: max sessions visited. */
+  maxSessions: number;
+  /** Wall-clock ceiling in ms for the whole pass (0 = no ceiling). */
+  maxDurationMs: number;
+  /** Compressed-size ceiling per session log; larger logs are skipped (pure-JS zstd is slow). */
+  maxSessionBytes: number;
+}
+interface RawScanResult {
+  items: RecallItem[];
+  /** Sessions whose events were actually scanned. */
+  scanned: number;
+  /** The scan budget that applied. */
+  budget: number;
+  /** Sessions skipped because their log could not be decompressed or parsed. */
+  unreadable: number;
+  /** False when the scan stopped early (budget/ceiling): results cover the newest sessions only. */
+  coveredAll: boolean;
+  /** In-scope sessions skipped because their log exceeded `maxSessionBytes`. */
+  skippedOversized: number;
+  /** Session directories that existed under the root when the scan started. */
+  totalCandidates: number;
+}
+/**
+ * Scan persisted session logs directly, honoring the same scope filters as
+ * the indexed path. Never throws for per-session problems; returns what it
+ * found plus scan counters.
+ *
+ * Cost model (newest-first): the header line of every session is read
+ * through the streaming decompressor (milliseconds each); only sessions
+ * passing the scope filters are decompressed fully, and only sessions whose
+ * bytes mention every term are parsed line by line. `maxDurationMs` puts a
+ * wall-clock ceiling on the pass — when it trips, `coveredAll` is false and
+ * the caller should say so (results cover the newest sessions only).
+ */
+declare function rawScanSessions(options: RawScanOptions): Promise<RawScanResult>;
+//#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. */
@@ -266,4 +355,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 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 };
+export { ALL_PROJECTS_POLICIES, type AllProjectsPolicy, type NormalizedRecallConfig, RAW_SCAN_DEFAULT_MAX_SESSIONS, RAW_SCAN_MAX_SESSIONS_MAX, RECALL_TOOL_DESCRIPTION, REDACTION_MODES, type RankableItem, type RankingOptions, type RawScanOptions, type RawScanResult, 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, discoverSessionsRoot, firstLineClipped, formatDate, hasCJK, id8, inject, isIndexOutage, name, normalizeQuery, normalizeRecallConfig, normalizeRedactionMode, rankItems, rankingActive, rawScanSessions, recallContentBlocks, recallPresentationMeta, redactText, renderRecallText, snippetAround };