dsh-context-mode 0.1.2 → 0.2.0

package/vendor/context-mode/src/search/auto-memory.ts

@@ -0,0 +1,200 @@
+/**
+ * Auto-memory search — searches CLAUDE.md / AGENTS.md / GEMINI.md / etc.
+ * and the platform's persistent memory directory for decisions,
+ * preferences, and context from prior sessions.
+ *
+ * Returns results in a format compatible with the unified search pipeline.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, isAbsolute } from "node:path";
+import { resolveClaudeConfigDir } from "../util/claude-config.js";
+import { hashProjectDirCanonical } from "../session/db.js";
+
+const DEBUG = process.env.DEBUG?.includes("context-mode");
+
+export interface AutoMemoryResult {
+  title: string;
+  content: string;
+  source: string;
+  origin: "auto-memory";
+  timestamp?: string;
+}
+
+/**
+ * Minimal adapter contract used by searchAutoMemory.
+ * Avoids depending on the full HookAdapter type to keep this module standalone.
+ */
+export interface AutoMemoryAdapter {
+  getConfigDir(): string;
+  getInstructionFiles(): string[];
+  /**
+   * `projectDir` is optional for backwards compatibility with legacy
+   * callers — when supplied, adapters MUST return a project-scoped path
+   * (see HookAdapter.getMemoryDir contract, issue #663).
+   */
+  getMemoryDir(projectDir?: string): string;
+}
+
+/**
+ * Search auto-memory files for content matching any of the given queries.
+ *
+ * When `adapter` is provided, the per-platform conventions are used:
+ *   1. Project-level: <projectDir>/<each instructionFile>
+ *   2. User-level: <configDir>/<each instructionFile>
+ *   3. Memory dir: <memoryDir>/*.md
+ *
+ * Without an adapter (legacy callers), defaults to Claude conventions
+ * (CLAUDE.md + ~/.claude/memory) for backwards compatibility.
+ *
+ * @param queries  Array of search terms
+ * @param limit    Max results to return
+ * @param projectDir  Project directory path
+ * @param configDir   Explicit config dir override (legacy callers)
+ * @param adapter     Platform adapter — supplies instruction files + memory dir
+ * @returns Matching auto-memory results
+ */
+export function searchAutoMemory(
+  queries: string[],
+  limit: number = 5,
+  projectDir?: string,
+  configDir?: string,
+  adapter?: AutoMemoryAdapter,
+): AutoMemoryResult[] {
+  const results: AutoMemoryResult[] = [];
+
+  // Resolve conventions — adapter wins over explicit configDir, which wins
+  // over the historical Claude defaults.
+  const instructionFiles = adapter?.getInstructionFiles() ?? ["CLAUDE.md"];
+  const adapterConfigDir = adapter?.getConfigDir();
+  // Issue #460 round-3: legacy fallback honors $CLAUDE_CONFIG_DIR via the
+  // canonical util so callers without an adapter still respect relocated
+  // CC config trees (and empty/whitespace env doesn't poison the path).
+  const adapterRelative = adapterConfigDir ? resolveAgainst(projectDir, adapterConfigDir) : null;
+  const effectiveConfigDir = adapterRelative ?? configDir ?? resolveClaudeConfigDir();
+  // Issue #663: scope memory dir by projectDir so parallel projects can't
+  // read each other's auto-memory. Adapter-aware path delegates the
+  // scoping to the adapter; legacy adapterless fallback applies the same
+  // hash directly so the contract holds at both call sites.
+  const adapterMemoryDir = adapter?.getMemoryDir(projectDir);
+  const fallbackMemoryBase = join(effectiveConfigDir, "memory");
+  const fallbackMemoryDir = projectDir
+    ? join(fallbackMemoryBase, hashProjectDirCanonical(projectDir))
+    : fallbackMemoryBase;
+  const memoryDir = adapterMemoryDir
+    ? resolveAgainst(projectDir, adapterMemoryDir)
+    : fallbackMemoryDir;
+
+  // Collect candidate files
+  const candidates: Array<{ path: string; label: string }> = [];
+
+  // 1. Project-level instruction files
+  if (projectDir) {
+    for (const fileName of instructionFiles) {
+      const p = join(projectDir, fileName);
+      if (existsSync(p)) {
+        candidates.push({ path: p, label: `project/${fileName}` });
+      }
+    }
+  }
+
+  // 2. User-level instruction files (skip when configDir resolves to the
+  //    project root — already covered by step 1, would emit dup labels).
+  if (effectiveConfigDir && effectiveConfigDir !== projectDir) {
+    for (const fileName of instructionFiles) {
+      const p = join(effectiveConfigDir, fileName);
+      if (existsSync(p)) {
+        candidates.push({ path: p, label: `user/${fileName}` });
+      }
+    }
+  }
+
+  // 3. Memory directory
+  if (memoryDir && existsSync(memoryDir)) {
+    try {
+      const files = readdirSync(memoryDir).filter(f => f.endsWith(".md"));
+      for (const file of files) {
+        candidates.push({
+          path: join(memoryDir, file),
+          label: `memory/${file}`,
+        });
+      }
+    } catch (e) {
+      if (DEBUG) process.stderr.write(`[ctx] auto-memory dir scan failed: ${e}\n`);
+    }
+  }
+
+  // Search each candidate file for matching queries
+  for (const candidate of candidates) {
+    if (results.length >= limit) break;
+
+    try {
+      // Single stat for both size guard and timestamp — saves one syscall
+      // per candidate file. Cross-platform: statSync semantics identical
+      // on macOS / Linux / Windows; size+mtime read in the same inode probe.
+      let stat;
+      try {
+        stat = statSync(candidate.path);
+        if (stat.size > 1_000_000) continue;
+      } catch { continue; }
+      const content = readFileSync(candidate.path, "utf-8");
+      const contentLower = content.toLowerCase();
+
+      for (const query of queries) {
+        if (results.length >= limit) break;
+
+        const queryLower = query.toLowerCase();
+        // Split query into terms, match if any term is found
+        const terms = queryLower.split(/\s+/).filter(t => t.length >= 3);
+        const matched = terms.some(term => {
+          try {
+            return new RegExp(`\\b${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, "i").test(content);
+          } catch {
+            return contentLower.includes(term); // fallback for invalid regex
+          }
+        });
+
+        if (matched) {
+          // Extract a relevant section around the first match
+          const firstTermIdx = terms.reduce((best, term) => {
+            const idx = contentLower.indexOf(term);
+            return idx >= 0 && (best < 0 || idx < best) ? idx : best;
+          }, -1);
+
+          let start = Math.max(0, firstTermIdx - 200);
+          let end = Math.min(content.length, firstTermIdx + 500);
+          const prevBlank = content.lastIndexOf("\n\n", start);
+          const nextBlank = content.indexOf("\n\n", end);
+          if (prevBlank >= 0) start = prevBlank + 2;
+          if (nextBlank >= 0) end = nextBlank;
+          const snippet = content.slice(start, end).trim();
+
+          results.push({
+            title: `[auto-memory] ${candidate.label}`,
+            content: snippet,
+            source: candidate.label,
+            origin: "auto-memory",
+            timestamp: stat.mtime.toISOString(),
+          });
+          break; // one result per file per query batch
+        }
+      }
+    } catch (e) {
+      if (DEBUG) process.stderr.write(`[ctx] auto-memory file read failed: ${e}\n`);
+    }
+  }
+
+  return results.slice(0, limit);
+}
+
+/**
+ * Resolve a possibly-relative path (e.g. ".github", "memory") against a
+ * project directory. Absolute paths and empty strings are returned as-is
+ * (empty == "use projectDir directly").
+ */
+function resolveAgainst(projectDir: string | undefined, p: string): string {
+  if (!p) return projectDir ?? "";
+  if (isAbsolute(p)) return p;
+  if (!projectDir) return p;
+  return join(projectDir, p);
+}

package/vendor/context-mode/src/search/ctx-search-schema.ts

@@ -0,0 +1,143 @@
+/**
+ * ctx_search input-schema builder and project-scope resolver.
+ *
+ * Issue #737 introduces the optional `project:` parameter used by callers
+ * running in the shared-DB mode (`CONTEXT_MODE_PROJECT_DIR` is set). The
+ * field is registered conditionally so that in the default per-project DB
+ * mode the LLM physically cannot pass it — the parameter does not exist
+ * in the tool schema at all, which is a stronger guarantee than runtime
+ * validation that depends on the model honouring documentation.
+ *
+ * The handler in `src/server.ts` consumes both exports:
+ *   - {@link buildCtxSearchInputSchema} composes the Zod object used at
+ *     `registerTool` time, spreading the conditional `project` field only
+ *     when `isSharedMode` is true.
+ *   - {@link resolveProjectScope} normalises the raw param into the
+ *     three-state contract consumed by `searchAllSources`:
+ *       undefined → no filter
+ *       null      → explicit cross-project recall (no filter)
+ *       string    → restrict to that project directory
+ */
+
+import { z } from "zod";
+
+/**
+ * Helper that mirrors the Zod coercer used elsewhere in the server for
+ * array-shaped tool args. Kept inline so this module has no runtime
+ * dependency on `server.ts` (which would create a cycle).
+ *
+ * Behaviour mirrors `coerceJsonArray` in `server.ts`:
+ *   1. Empty / whitespace string → returned untouched so Zod surfaces the
+ *      "non-empty" error rather than masquerading as `[""]`.
+ *   2. Valid JSON array string → parsed and returned.
+ *   3. Any other plain string (a bare single query) → lifted to a
+ *      single-element array. Fixes #627 for the native OpenCode plugin
+ *      path where some providers deliver `queries: "search term"`.
+ */
+function coerceJsonArray(val: unknown): unknown {
+  if (typeof val === "string") {
+    const trimmed = val.trim();
+    if (trimmed.length === 0) return val;
+    try {
+      const parsed = JSON.parse(val);
+      if (Array.isArray(parsed)) return parsed;
+    } catch {
+      /* fall through — not JSON, treat as bare-string lift */
+    }
+    return [val];
+  }
+  return val;
+}
+
+/**
+ * Build the Zod object passed to `server.registerTool("ctx_search", …)`.
+ *
+ * The base fields (`queries`, `limit`, `source`, `contentType`, `sort`)
+ * are always present and mirror today's contract exactly. The `project`
+ * field is only spread in when `isSharedMode` is true. When the host runs
+ * with the default per-project DB layout the schema does not expose the
+ * field at all, which keeps the tool surface honest about what is
+ * actionable in that mode.
+ */
+export function buildCtxSearchInputSchema(isSharedMode: boolean) {
+  const projectField = isSharedMode
+    ? {
+        project: z
+          .string()
+          .optional()
+          .describe(
+            "Project scope. " +
+              "Default (omit): this session's project — auto-resolved from the host adapter. " +
+              "'global': span every project in the shared store (cross-project recall). " +
+              "<absolute-path>: scope to that specific project directory.",
+          ),
+      }
+    : ({} as Record<string, never>);
+
+  return z.object({
+    queries: z.preprocess(coerceJsonArray, z
+      .array(z.string())
+      .optional()
+      .describe("Array of search queries. Batch ALL questions in one call.")),
+    // limit: z.coerce.number() (not z.number()) — OpenCode's native
+    // plugin path delivers tool args straight from the LLM provider's
+    // tool-call JSON, where several providers stringify primitives
+    // (limit:"4" instead of limit:4). Since v1.0.139 / #621 we run
+    // inputSchema.parse() on that path, so a plain z.number() rejects
+    // "4" with "Expected number, received string". z.coerce mirrors what
+    // ctx_batch_execute / ctx_fetch_and_index / ctx_execute already do.
+    // Fixes #627.
+    limit: z
+      .coerce.number()
+      .optional()
+      .default(3)
+      .describe("Results per query (default: 3)"),
+    source: z
+      .string()
+      .optional()
+      .describe("Filter to a specific indexed source (partial match)."),
+    contentType: z
+      .enum(["code", "prose"])
+      .optional()
+      .describe("Filter results by content type: 'code' or 'prose'."),
+    sort: z
+      .enum(["relevance", "timeline"])
+      .optional()
+      .default("relevance")
+      .describe(
+        "Sort mode. 'relevance' (default): BM25 ranked, current session only. " +
+          "'timeline': chronological across current session, prior sessions, and auto-memory.",
+      ),
+    ...projectField,
+  });
+}
+
+/**
+ * Normalise the raw `project` value into the three-state contract consumed
+ * by {@link searchAllSources}.
+ *
+ *   - shared mode OFF                        → `undefined` (param ignored)
+ *   - shared mode ON, param `undefined`      → current project (`getProjectDirFn()`)
+ *   - shared mode ON, param `"global"`       → `null` (no filter — cross-project)
+ *   - shared mode ON, param `<string>`       → that string verbatim
+ *
+ * The function is pure so it stays trivially testable without spinning up
+ * the MCP server.
+ */
+export function resolveProjectScope(
+  raw: string | undefined,
+  isSharedMode: boolean,
+  getProjectDirFn: () => string,
+): string | null | undefined {
+  if (!isSharedMode) return undefined;
+  if (raw === undefined) return getProjectDirFn();
+  if (raw === "global") return null;
+  return raw;
+}
+
+/**
+ * Module-load snapshot of `CONTEXT_MODE_PROJECT_DIR`. Captured once so the
+ * tool schema registered with `server.registerTool` reflects the launch
+ * environment — the LLM-visible surface should never flip mid-session.
+ */
+export const CTX_SEARCH_SHARED_MODE = !!process.env.CONTEXT_MODE_PROJECT_DIR;

package/vendor/context-mode/src/search/flood-guard.ts

@@ -0,0 +1,111 @@
+/**
+ * ctx_search flood-guard — per-agent-context progressive throttle.
+ *
+ * Background (#79 / #155 / #697): ctx_search carries a progressive throttle
+ * so a single actor cannot spam dozens of individual searches and flood the
+ * context window instead of batching via ctx_batch_execute. The original
+ * implementation kept ONE module-global counter on the MCP server process.
+ *
+ * Issue #769: a parallel multi-agent fan-out (Claude Code Task/Workflow)
+ * runs N subagents concurrently against the SAME per-session MCP server
+ * process. With a single global counter their independent calls are summed
+ * into one budget, so legitimate fan-out ("10 agents x 2 calls") trips the
+ * guard that was only ever meant to catch ONE actor spamming. The budget is
+ * tool-availability state that is logically per-agent-context, so the counter
+ * must be keyed per agent-context — NOT removed. Single-actor flood
+ * protection is preserved exactly; only the bucketing changes.
+ *
+ * This module is pure and transport-free so the policy is unit-testable
+ * without spinning up the MCP server. `src/server.ts` owns the singleton and
+ * supplies the per-call agent key (the session/agent id from
+ * currentAttribution()).
+ */
+
+export interface FloodGuardConfig {
+  /** Rolling window length in ms. After this elapses a key's counter resets. */
+  windowMs: number;
+  /** After this many calls in the window, results taper to 1 per query. */
+  softCapAfter: number;
+  /** After this many calls in the window, the call is hard-blocked. */
+  blockAfter: number;
+}
+
+export interface FloodDecision {
+  /** This key's call count within the current rolling window (1-based). */
+  count: number;
+  /** Window start timestamp (ms) for this key — used for the "in Ns" message. */
+  windowStart: number;
+  /** True once count exceeds blockAfter — caller must refuse the search. */
+  blocked: boolean;
+  /** True once count exceeds softCapAfter — caller trims to 1 result/query. */
+  softCapped: boolean;
+}
+
+interface Bucket {
+  count: number;
+  windowStart: number;
+}
+
+/**
+ * A rolling-window call counter bucketed per agent-context key. Each key gets
+ * an independent window + counter, so concurrent subagents do not consume one
+ * another's budget while a single greedy actor is still throttled and blocked
+ * exactly as before.
+ */
+export class FloodGuard {
+  readonly #cfg: FloodGuardConfig;
+  readonly #buckets = new Map<string, Bucket>();
+  /**
+   * Hard ceiling on tracked keys — a defensive bound so a pathological host
+   * that mints unbounded distinct agent ids cannot grow the map without limit.
+   * When exceeded, the oldest-window bucket is evicted (its actor simply gets
+   * a fresh window on its next call — fail-open, never a false block).
+   */
+  readonly #maxKeys: number;
+
+  constructor(cfg: FloodGuardConfig, maxKeys = 4096) {
+    this.#cfg = cfg;
+    this.#maxKeys = Math.max(1, maxKeys);
+  }
+
+  /**
+   * Record one ctx_search call for `key` at time `now` (ms) and return the
+   * throttle decision. Pure aside from the internal per-key counter state.
+   */
+  record(key: string, now: number = Date.now()): FloodDecision {
+    let bucket = this.#buckets.get(key);
+
+    if (!bucket || now - bucket.windowStart > this.#cfg.windowMs) {
+      bucket = { count: 0, windowStart: now };
+      this.#buckets.set(key, bucket);
+      this.#evictIfNeeded();
+    }
+
+    bucket.count++;
+
+    return {
+      count: bucket.count,
+      windowStart: bucket.windowStart,
+      blocked: bucket.count > this.#cfg.blockAfter,
+      softCapped: bucket.count > this.#cfg.softCapAfter,
+    };
+  }
+
+  /** Test/diagnostics helper — number of distinct keys currently tracked. */
+  size(): number {
+    return this.#buckets.size;
+  }
+
+  #evictIfNeeded(): void {
+    if (this.#buckets.size <= this.#maxKeys) return;
+    let oldestKey: string | undefined;
+    let oldestStart = Infinity;
+    for (const [k, b] of this.#buckets) {
+      if (b.windowStart < oldestStart) {
+        oldestStart = b.windowStart;
+        oldestKey = k;
+      }
+    }
+    if (oldestKey !== undefined) this.#buckets.delete(oldestKey);
+  }
+}

package/vendor/context-mode/src/search/unified.ts

@@ -0,0 +1,176 @@
+/**
+ * Unified multi-source search — merges ContentStore, SessionDB, and
+ * auto-memory results into a single ranked or chronological result set.
+ *
+ * Used by ctx_search when sort="timeline" to search across all sources,
+ * or sort="relevance" (default) for ContentStore-only BM25 search.
+ */
+
+import type { ContentStore, SearchResult } from "../store.js";
+import type { SessionDB, StoredEvent } from "../session/db.js";
+import { searchAutoMemory, type AutoMemoryAdapter } from "./auto-memory.js";
+
+const DEBUG = process.env.DEBUG?.includes("context-mode");
+
+// ─────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────
+
+export interface UnifiedSearchResult {
+  title: string;
+  content: string;
+  source: string;
+  origin: "current-session" | "prior-session" | "auto-memory";
+  timestamp?: string;
+  rank?: number;
+  matchLayer?: string;
+  highlighted?: string;
+  contentType?: "code" | "prose";
+}
+
+export interface SearchAllSourcesOpts {
+  query: string;
+  limit: number;
+  store: ContentStore;
+  sort?: "relevance" | "timeline";
+  source?: string;
+  contentType?: "code" | "prose";
+  sessionDB?: SessionDB | null;
+  projectDir?: string;
+  configDir?: string;
+  /** Detected platform adapter — used for adapter-aware auto-memory. */
+  adapter?: AutoMemoryAdapter;
+  /**
+   * Per-project scope for the ContentStore filter (#737). Only honoured
+   * when a `sessionDB` is also supplied (the 2-step IN-clause needs the
+   * SessionDB to translate `project_dir` → list of session ids).
+   *
+   *   - `undefined` — no project filter, today's behaviour.
+   *   - `null`      — cross-project recall in shared-DB mode (also no filter).
+   *   - `string`    — restrict ContentStore results to chunks attributed to
+   *                   session ids whose events match this `project_dir`,
+   *                   plus legacy `session_id=''` chunks (public surface).
+   */
+  projectScope?: string | null;
+}
+
+// ─────────────────────────────────────────────────────────
+// Implementation
+// ─────────────────────────────────────────────────────────
+
+/**
+ * Search across all available sources.
+ *
+ * - sort="relevance" (default): BM25-ranked results from ContentStore only.
+ * - sort="timeline": chronological merge of ContentStore + SessionDB + auto-memory.
+ *
+ * Errors in any single source are caught and logged — partial results
+ * are always returned.
+ */
+export function searchAllSources(opts: SearchAllSourcesOpts): UnifiedSearchResult[] {
+  const {
+    query,
+    limit,
+    store,
+    sort = "relevance",
+    source,
+    contentType,
+    sessionDB,
+    projectDir,
+    configDir,
+    adapter,
+    projectScope,
+  } = opts;
+
+  const results: UnifiedSearchResult[] = [];
+
+  // Capture session start time once — used as proxy for ContentStore items
+  // (we don't know exact indexing time, but all content is from current session)
+  const sessionStartTime = new Date().toISOString();
+
+  // ── Project scope (#737) ──
+  // Resolve the per-project session-id allow-set ONCE, before the
+  // ContentStore call. `projectScope === null` means cross-project recall —
+  // an explicit "no filter" choice surfaced by the ctx_search caller — and
+  // `undefined` falls back to today's unfiltered behaviour.
+  let sessionIdAllowSet: Set<string> | undefined;
+  if (typeof projectScope === "string" && sessionDB) {
+    try {
+      sessionIdAllowSet = new Set(sessionDB.getSessionIdsForProject(projectScope));
+    } catch (e) {
+      if (DEBUG) process.stderr.write(`[ctx] getSessionIdsForProject failed: ${e}\n`);
+    }
+  }
+
+  // ── Source 1: ContentStore (always, both modes) ──
+  try {
+    const storeResults = store.searchWithFallback(
+      query,
+      limit,
+      source,
+      contentType,
+      "like",
+      sessionIdAllowSet,
+    );
+    results.push(
+      ...storeResults.map((r: SearchResult) => ({
+        title: r.title,
+        content: r.content,
+        source: r.source,
+        origin: "current-session" as const,
+        timestamp: r.timestamp || sessionStartTime,
+        rank: r.rank,
+        matchLayer: r.matchLayer,
+        highlighted: r.highlighted,
+        contentType: r.contentType,
+      })),
+    );
+  } catch (e) {
+    if (DEBUG) process.stderr.write(`[ctx] ContentStore search failed: ${e}\n`);
+  }
+
+  // ── Sources 2+3: timeline mode only ──
+  if (sort === "timeline") {
+    // Source 2: SessionDB — prior session events
+    try {
+      if (sessionDB) {
+        const dbResults = sessionDB.searchEvents(query, limit, projectDir || "", source);
+        results.push(
+          ...dbResults.map((r: Pick<StoredEvent, "id" | "session_id" | "category" | "type" | "data" | "created_at">) => ({
+            title: `[${r.category}] ${r.type}`,
+            content: r.data,
+            source: "prior-session",
+            origin: "prior-session" as const,
+            timestamp: r.created_at,
+          })),
+        );
+      }
+    } catch (e) {
+      if (DEBUG) process.stderr.write(`[ctx] SessionDB search failed: ${e}\n`);
+    }
+
+    // Source 3: Auto-memory
+    try {
+      const memResults = searchAutoMemory([query], limit, projectDir, configDir, adapter);
+      results.push(...memResults);
+    } catch (e) {
+      if (DEBUG) process.stderr.write(`[ctx] auto-memory search failed: ${e}\n`);
+    }
+  }
+
+  // ── Normalize timestamps for consistent sorting ──
+  // SQLite datetime('now') → "YYYY-MM-DD HH:MM:SS" (no T, no Z)
+  // ISO → "YYYY-MM-DDTHH:MM:SS.sssZ"
+  for (const r of results) {
+    if (r.timestamp && !r.timestamp.includes("T")) {
+      r.timestamp = r.timestamp.replace(" ", "T") + "Z";
+    }
+  }
+
+  // ── Sort ──
+  if (sort === "timeline") {
+    results.sort((a, b) => (a.timestamp || "").localeCompare(b.timestamp || ""));
+  }
+
+  return results.slice(0, limit);
+}