laminark 0.1.0

package/plugin/dist/analysis/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","names":[],"sources":["../../../src/analysis/engines/local-onnx.ts","../../../src/analysis/engines/keyword-only.ts","../../../src/analysis/embedder.ts","../../../src/analysis/worker.ts"],"sourcesContent":["/**\n * Local ONNX embedding engine using @huggingface/transformers.\n *\n * Loads BGE Small EN v1.5 (quantized q8) via dynamic import() for\n * zero startup cost (DQ-04). Model files are cached in ~/.laminark/models/.\n */\n\nimport { join } from 'node:path';\n\nimport { getConfigDir } from '../../shared/config.js';\nimport type { EmbeddingEngine } from '../embedder.js';\n\n// Pipeline type from @huggingface/transformers -- kept as `unknown` to avoid\n// hard dependency on the library's type definitions at import time.\ntype Pipeline = (\n  text: string,\n  options?: { pooling?: string; normalize?: boolean },\n) => Promise<{ data: ArrayLike<number> }>;\n\n/**\n * Embedding engine backed by BGE Small EN v1.5 running locally via ONNX Runtime.\n *\n * All public methods catch errors internally and return null/false.\n */\nexport class LocalOnnxEngine implements EmbeddingEngine {\n  private pipe: Pipeline | null = null;\n  private ready = false;\n\n  /**\n   * Lazily loads the model via dynamic import().\n   *\n   * - Uses `@huggingface/transformers` loaded at runtime (not bundled)\n   * - Caches model files in ~/.laminark/models/\n   * - Returns false on any error (missing runtime, download failure, etc.)\n   */\n  async initialize(): Promise<boolean> {\n    try {\n      const { pipeline, env } = await import('@huggingface/transformers');\n\n      // Cache models in user config directory\n      env.cacheDir = join(getConfigDir(), 'models');\n\n      this.pipe = (await pipeline('feature-extraction', 'Xenova/bge-small-en-v1.5', {\n        dtype: 'q8',\n      })) as unknown as Pipeline;\n\n      this.ready = true;\n      return true;\n    } catch {\n      this.ready = false;\n      return false;\n    }\n  }\n\n  /**\n   * Embeds a single text string into a 384-dimensional vector.\n   *\n   * Returns null if:\n   * - Engine not initialized\n   * - Input is empty/whitespace\n   * - Pipeline throws\n   */\n  async embed(text: string): Promise<Float32Array | null> {\n    if (!this.ready || !this.pipe) {\n      return null;\n    }\n\n    if (!text || text.trim().length === 0) {\n      return null;\n    }\n\n    try {\n      const output = await this.pipe(text, { pooling: 'cls', normalize: true });\n      return Float32Array.from(output.data);\n    } catch {\n      return null;\n    }\n  }\n\n  /**\n   * Embeds multiple texts, preserving order.\n   *\n   * Returns null for any text that was empty or failed.\n   */\n  async embedBatch(texts: string[]): Promise<(Float32Array | null)[]> {\n    const results: (Float32Array | null)[] = [];\n\n    for (const text of texts) {\n      if (!text || text.trim().length === 0) {\n        results.push(null);\n      } else {\n        results.push(await this.embed(text));\n      }\n    }\n\n    return results;\n  }\n\n  /** BGE Small EN v1.5 produces 384-dimensional embeddings. */\n  dimensions(): number {\n    return 384;\n  }\n\n  /** Engine identifier. */\n  name(): string {\n    return 'bge-small-en-v1.5-q8';\n  }\n\n  /** Whether the model loaded successfully. */\n  isReady(): boolean {\n    return this.ready;\n  }\n}\n","/**\n * Null fallback embedding engine for graceful degradation (DQ-03).\n *\n * Used when the ONNX runtime or model is unavailable.\n * All embedding methods return null -- search falls back to keyword-only (FTS5).\n */\n\nimport type { EmbeddingEngine } from '../embedder.js';\n\n/**\n * Embedding engine that produces no embeddings.\n *\n * Acts as a silent fallback so that the rest of the system can\n * operate in keyword-only mode without special-casing missing engines.\n */\nexport class KeywordOnlyEngine implements EmbeddingEngine {\n  /** Always returns null -- no model available. */\n  async embed(): Promise<Float32Array | null> {\n    return null;\n  }\n\n  /** Returns array of nulls matching input length. */\n  async embedBatch(texts: string[]): Promise<(Float32Array | null)[]> {\n    return texts.map(() => null);\n  }\n\n  /** No dimensions -- no model. */\n  dimensions(): number {\n    return 0;\n  }\n\n  /** Engine identifier. */\n  name(): string {\n    return 'keyword-only';\n  }\n\n  /** Intentionally returns false -- this engine has no model. */\n  async initialize(): Promise<boolean> {\n    return false;\n  }\n\n  /** Always false -- no model loaded. */\n  isReady(): boolean {\n    return false;\n  }\n}\n","/**\n * EmbeddingEngine interface and factory.\n *\n * Defines the pluggable abstraction for text embedding.\n * All consumers depend on this interface -- never on concrete engines.\n */\n\nimport { LocalOnnxEngine } from './engines/local-onnx.js';\nimport { KeywordOnlyEngine } from './engines/keyword-only.js';\n\n/**\n * Pluggable embedding engine abstraction.\n *\n * All methods that can fail return null/false -- engines NEVER throw.\n * This is critical for graceful degradation (DQ-03).\n */\nexport interface EmbeddingEngine {\n  /** Embed a single text string. Returns null on failure or empty input. */\n  embed(text: string): Promise<Float32Array | null>;\n\n  /** Embed multiple texts. Returns null for any that failed or were empty. */\n  embedBatch(texts: string[]): Promise<(Float32Array | null)[]>;\n\n  /** Embedding dimensions (384 for BGE Small, 0 for keyword-only). */\n  dimensions(): number;\n\n  /** Engine identifier string. */\n  name(): string;\n\n  /** Lazy initialization. Returns true on success, false on failure. */\n  initialize(): Promise<boolean>;\n\n  /** Whether initialize() has been called and succeeded. */\n  isReady(): boolean;\n}\n\n/**\n * Creates and initializes an embedding engine.\n *\n * Attempts LocalOnnxEngine first. If initialization fails (missing model,\n * ONNX runtime unavailable, etc.), falls back to KeywordOnlyEngine.\n *\n * Never throws -- always returns a valid engine.\n */\nexport async function createEmbeddingEngine(): Promise<EmbeddingEngine> {\n  const onnxEngine = new LocalOnnxEngine();\n  const success = await onnxEngine.initialize();\n\n  if (success) {\n    return onnxEngine;\n  }\n\n  return new KeywordOnlyEngine();\n}\n","/**\n * Worker thread entry point for off-main-thread embedding.\n *\n * Receives embed/embed_batch/shutdown messages from the main thread via\n * parentPort, runs the embedding engine, and responds with Float32Array\n * results using zero-copy transfer.\n *\n * Compiled as a separate tsdown entry point to dist/analysis/worker.js.\n */\n\nimport { parentPort } from 'node:worker_threads';\nimport { createEmbeddingEngine } from './embedder.js';\n\nif (!parentPort) {\n  throw new Error('worker.ts must be run as a Worker thread');\n}\n\nconst port = parentPort;\n\ninterface EmbedMessage {\n  type: 'embed';\n  id: string;\n  text: string;\n}\n\ninterface EmbedBatchMessage {\n  type: 'embed_batch';\n  id: string;\n  texts: string[];\n}\n\ninterface ShutdownMessage {\n  type: 'shutdown';\n}\n\ntype WorkerMessage = EmbedMessage | EmbedBatchMessage | ShutdownMessage;\n\nasync function init(): Promise<void> {\n  let engineName = 'keyword-only';\n  let dimensions = 0;\n\n  try {\n    const engine = await createEmbeddingEngine();\n    engineName = engine.name();\n    dimensions = engine.dimensions();\n\n    port.postMessage({ type: 'ready', engineName, dimensions });\n\n    port.on('message', async (msg: WorkerMessage) => {\n      if (msg.type === 'embed') {\n        try {\n          const embedding = await engine.embed(msg.text);\n\n          if (embedding === null) {\n            port.postMessage({ type: 'embed_result', id: msg.id, embedding: null });\n          } else {\n            // Zero-copy transfer of the underlying ArrayBuffer\n            const buf = embedding.buffer as ArrayBuffer;\n            port.postMessage(\n              { type: 'embed_result', id: msg.id, embedding },\n              [buf],\n            );\n          }\n        } catch {\n          port.postMessage({ type: 'embed_result', id: msg.id, embedding: null });\n        }\n      } else if (msg.type === 'embed_batch') {\n        try {\n          const embeddings = await engine.embedBatch(msg.texts);\n\n          // Collect non-null buffers for zero-copy transfer\n          const transferList: ArrayBuffer[] = [];\n          for (const emb of embeddings) {\n            if (emb !== null) {\n              transferList.push(emb.buffer as ArrayBuffer);\n            }\n          }\n\n          port.postMessage(\n            { type: 'embed_batch_result', id: msg.id, embeddings },\n            transferList,\n          );\n        } catch {\n          port.postMessage({\n            type: 'embed_batch_result',\n            id: msg.id,\n            embeddings: msg.texts.map(() => null),\n          });\n        }\n      } else if (msg.type === 'shutdown') {\n        process.exit(0);\n      }\n    });\n  } catch {\n    // Engine creation failed -- still report ready with keyword-only fallback\n    port.postMessage({ type: 'ready', engineName, dimensions });\n\n    port.on('message', (msg: WorkerMessage) => {\n      if (msg.type === 'embed') {\n        port.postMessage({ type: 'embed_result', id: msg.id, embedding: null });\n      } else if (msg.type === 'embed_batch') {\n        port.postMessage({\n          type: 'embed_batch_result',\n          id: msg.id,\n          embeddings: msg.texts.map(() => null),\n        });\n      } else if (msg.type === 'shutdown') {\n        process.exit(0);\n      }\n    });\n  }\n}\n\ninit();\n"],"mappings":"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"}

package/plugin/dist/config-t8LZeB-u.mjs

@@ -0,0 +1,90 @@
+import { mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+
+//#region src/shared/config.ts
+/**
+* Cached debug-enabled flag.
+* Resolved once per process -- debug mode does not change at runtime.
+*/
+let _debugCached = null;
+/**
+* Returns whether debug logging is enabled for this process.
+*
+* Resolution order:
+* 1. `LAMINARK_DEBUG` env var -- `"1"` or `"true"` enables debug mode
+* 2. `~/.laminark/config.json` -- `{ "debug": true }` enables debug mode
+* 3. Default: disabled
+*
+* The result is cached after the first call.
+*/
+function isDebugEnabled() {
+	if (_debugCached !== null) return _debugCached;
+	const envVal = process.env.LAMINARK_DEBUG;
+	if (envVal === "1" || envVal === "true") {
+		_debugCached = true;
+		return true;
+	}
+	try {
+		const raw = readFileSync(join(getConfigDir(), "config.json"), "utf-8");
+		if (JSON.parse(raw).debug === true) {
+			_debugCached = true;
+			return true;
+		}
+	} catch {}
+	_debugCached = false;
+	return false;
+}
+/**
+* Default busy timeout in milliseconds.
+* Must be >= 5000ms to prevent SQLITE_BUSY under concurrent load.
+* Source: SQLite docs + better-sqlite3 performance recommendations.
+*/
+const DEFAULT_BUSY_TIMEOUT = 5e3;
+/**
+* Returns the Laminark data directory.
+* Default: ~/.claude/plugins/cache/laminark/data/
+* Creates the directory recursively if it does not exist.
+*
+* Supports LAMINARK_DATA_DIR env var override for testing --
+* redirects all data storage to a custom directory without
+* affecting the real plugin data.
+*/
+function getConfigDir() {
+	const dir = process.env.LAMINARK_DATA_DIR || join(homedir(), ".claude", "plugins", "cache", "laminark", "data");
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+/**
+* Returns the path to the single Laminark database file.
+* Single database at ~/.claude/plugins/cache/laminark/data/data.db for ALL projects.
+*/
+function getDbPath() {
+	return join(getConfigDir(), "data.db");
+}
+/**
+* Creates a deterministic SHA-256 hash of a project directory path.
+* Uses realpathSync to canonicalize (resolves symlinks) to prevent
+* multiple hashes for the same directory via different paths.
+*
+* @param projectDir - The project directory path to hash
+* @returns First 16 hex characters of the SHA-256 hash
+*/
+function getProjectHash(projectDir) {
+	const canonical = realpathSync(resolve(projectDir));
+	return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+/**
+* Returns the default database configuration.
+*/
+function getDatabaseConfig() {
+	return {
+		dbPath: getDbPath(),
+		busyTimeout: DEFAULT_BUSY_TIMEOUT
+	};
+}
+
+//#endregion
+export { isDebugEnabled as a, getProjectHash as i, getDatabaseConfig as n, getDbPath as r, getConfigDir as t };
+//# sourceMappingURL=config-t8LZeB-u.mjs.map

package/plugin/dist/config-t8LZeB-u.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-t8LZeB-u.mjs","names":[],"sources":["../../src/shared/config.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\nimport { mkdirSync, readFileSync, realpathSync } from 'node:fs';\nimport { homedir } from 'node:os';\nimport { join, resolve } from 'node:path';\n\nimport type { DatabaseConfig } from './types.js';\n\n/**\n * Cached debug-enabled flag.\n * Resolved once per process -- debug mode does not change at runtime.\n */\nlet _debugCached: boolean | null = null;\n\n/**\n * Returns whether debug logging is enabled for this process.\n *\n * Resolution order:\n * 1. `LAMINARK_DEBUG` env var -- `\"1\"` or `\"true\"` enables debug mode\n * 2. `~/.laminark/config.json` -- `{ \"debug\": true }` enables debug mode\n * 3. Default: disabled\n *\n * The result is cached after the first call.\n */\nexport function isDebugEnabled(): boolean {\n  if (_debugCached !== null) {\n    return _debugCached;\n  }\n\n  // Check environment variable first\n  const envVal = process.env.LAMINARK_DEBUG;\n  if (envVal === '1' || envVal === 'true') {\n    _debugCached = true;\n    return true;\n  }\n\n  // Check config.json\n  try {\n    const configPath = join(getConfigDir(), 'config.json');\n    const raw = readFileSync(configPath, 'utf-8');\n    const config = JSON.parse(raw) as Record<string, unknown>;\n    if (config.debug === true) {\n      _debugCached = true;\n      return true;\n    }\n  } catch {\n    // Config file doesn't exist or is invalid -- that's fine\n  }\n\n  _debugCached = false;\n  return false;\n}\n\n/**\n * Default busy timeout in milliseconds.\n * Must be >= 5000ms to prevent SQLITE_BUSY under concurrent load.\n * Source: SQLite docs + better-sqlite3 performance recommendations.\n */\nexport const DEFAULT_BUSY_TIMEOUT = 5000;\n\n/**\n * Returns the Laminark data directory.\n * Default: ~/.claude/plugins/cache/laminark/data/\n * Creates the directory recursively if it does not exist.\n *\n * Supports LAMINARK_DATA_DIR env var override for testing --\n * redirects all data storage to a custom directory without\n * affecting the real plugin data.\n */\nexport function getConfigDir(): string {\n  const dir = process.env.LAMINARK_DATA_DIR || join(homedir(), '.claude', 'plugins', 'cache', 'laminark', 'data');\n  mkdirSync(dir, { recursive: true });\n  return dir;\n}\n\n/**\n * Returns the path to the single Laminark database file.\n * Single database at ~/.claude/plugins/cache/laminark/data/data.db for ALL projects.\n */\nexport function getDbPath(): string {\n  return join(getConfigDir(), 'data.db');\n}\n\n/**\n * Creates a deterministic SHA-256 hash of a project directory path.\n * Uses realpathSync to canonicalize (resolves symlinks) to prevent\n * multiple hashes for the same directory via different paths.\n *\n * @param projectDir - The project directory path to hash\n * @returns First 16 hex characters of the SHA-256 hash\n */\nexport function getProjectHash(projectDir: string): string {\n  const canonical = realpathSync(resolve(projectDir));\n  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);\n}\n\n/**\n * Returns the default database configuration.\n */\nexport function getDatabaseConfig(): DatabaseConfig {\n  return {\n    dbPath: getDbPath(),\n    busyTimeout: DEFAULT_BUSY_TIMEOUT,\n  };\n}\n"],"mappings":";;;;;;;;;;AAWA,IAAI,eAA+B;;;;;;;;;;;AAYnC,SAAgB,iBAA0B;AACxC,KAAI,iBAAiB,KACnB,QAAO;CAIT,MAAM,SAAS,QAAQ,IAAI;AAC3B,KAAI,WAAW,OAAO,WAAW,QAAQ;AACvC,iBAAe;AACf,SAAO;;AAIT,KAAI;EAEF,MAAM,MAAM,aADO,KAAK,cAAc,EAAE,cAAc,EACjB,QAAQ;AAE7C,MADe,KAAK,MAAM,IAAI,CACnB,UAAU,MAAM;AACzB,kBAAe;AACf,UAAO;;SAEH;AAIR,gBAAe;AACf,QAAO;;;;;;;AAQT,MAAa,uBAAuB;;;;;;;;;;AAWpC,SAAgB,eAAuB;CACrC,MAAM,MAAM,QAAQ,IAAI,qBAAqB,KAAK,SAAS,EAAE,WAAW,WAAW,SAAS,YAAY,OAAO;AAC/G,WAAU,KAAK,EAAE,WAAW,MAAM,CAAC;AACnC,QAAO;;;;;;AAOT,SAAgB,YAAoB;AAClC,QAAO,KAAK,cAAc,EAAE,UAAU;;;;;;;;;;AAWxC,SAAgB,eAAe,YAA4B;CACzD,MAAM,YAAY,aAAa,QAAQ,WAAW,CAAC;AACnD,QAAO,WAAW,SAAS,CAAC,OAAO,UAAU,CAAC,OAAO,MAAM,CAAC,MAAM,GAAG,GAAG;;;;;AAM1E,SAAgB,oBAAoC;AAClD,QAAO;EACL,QAAQ,WAAW;EACnB,aAAa;EACd"}

package/plugin/dist/hooks/handler.d.ts

@@ -0,0 +1,286 @@
+import { t as ObservationRepository } from "../observations-CorAAc1A.mjs";
+import * as better_sqlite30 from "better-sqlite3";
+import Database from "better-sqlite3";
+
+//#region src/storage/research-buffer.d.ts
+/**
+ * Lightweight buffer for exploration tool events (Read, Glob, Grep).
+ *
+ * Instead of creating full observations for these low-signal tools,
+ * they are stored in a temporary buffer. When a Write/Edit observation
+ * is created, the recent buffer entries are attached as research context,
+ * creating provenance links between exploration and changes.
+ *
+ * Buffer entries are flushed after 30 minutes.
+ */
+declare class ResearchBufferRepository {
+  private readonly db;
+  private readonly projectHash;
+  private readonly stmtInsert;
+  private readonly stmtGetRecent;
+  private readonly stmtFlush;
+  constructor(db: Database.Database, projectHash: string);
+  /**
+   * Records a research tool event in the buffer.
+   */
+  add(entry: {
+    sessionId: string | null;
+    toolName: string;
+    target: string;
+  }): void;
+  /**
+   * Returns recent buffer entries for a session within a time window.
+   */
+  getRecent(sessionId: string, windowMinutes?: number): Array<{
+    toolName: string;
+    target: string;
+    createdAt: string;
+  }>;
+  /**
+   * Deletes buffer entries older than the specified number of minutes.
+   */
+  flush(olderThanMinutes?: number): number;
+}
+//#endregion
+//#region src/shared/tool-types.d.ts
+/**
+ * Tool type classification based on how the tool is provided.
+ */
+type ToolType = 'mcp_server' | 'mcp_tool' | 'slash_command' | 'skill' | 'plugin' | 'builtin' | 'unknown';
+/**
+ * Scope origin of a tool -- where it was discovered from.
+ */
+type ToolScope = 'global' | 'project' | 'plugin';
+/**
+ * A tool discovered during config scanning (SessionStart).
+ * Used as input to ToolRegistryRepository.upsert().
+ */
+interface DiscoveredTool {
+  name: string;
+  toolType: ToolType;
+  scope: ToolScope;
+  source: string;
+  projectHash: string | null;
+  description: string | null;
+  serverName: string | null;
+  triggerHints: string | null;
+}
+/**
+ * Raw database row from the tool_registry table (snake_case).
+ */
+interface ToolRegistryRow {
+  id: number;
+  name: string;
+  tool_type: string;
+  scope: string;
+  source: string;
+  project_hash: string | null;
+  description: string | null;
+  server_name: string | null;
+  trigger_hints: string | null;
+  usage_count: number;
+  last_used_at: string | null;
+  discovered_at: string;
+  updated_at: string;
+  status: string;
+}
+/**
+ * Aggregated usage stats for temporal queries.
+ */
+interface ToolUsageStats {
+  tool_name: string;
+  usage_count: number;
+  last_used: string;
+}
+/**
+ * A search result from hybrid tool search (FTS5 + vector via RRF).
+ */
+interface ToolSearchResult {
+  tool: ToolRegistryRow;
+  score: number;
+  matchType: 'fts' | 'vector' | 'hybrid';
+}
+//#endregion
+//#region src/storage/tool-registry.d.ts
+/**
+ * Repository for tool registry CRUD operations.
+ *
+ * Unlike ObservationRepository, this is NOT scoped to a single project --
+ * the tool registry spans all scopes (global, project, plugin) and is
+ * queried cross-project for tool discovery and routing.
+ *
+ * All SQL statements are prepared once in the constructor and reused for
+ * every call (better-sqlite3 performance best practice).
+ */
+declare class ToolRegistryRepository {
+  private readonly db;
+  private readonly stmtUpsert;
+  private readonly stmtRecordUsage;
+  private readonly stmtGetByScope;
+  private readonly stmtGetByName;
+  private readonly stmtGetAll;
+  private readonly stmtCount;
+  private readonly stmtGetAvailableForSession;
+  private readonly stmtInsertEvent;
+  private readonly stmtGetUsageForTool;
+  private readonly stmtGetUsageForSession;
+  private readonly stmtGetUsageSince;
+  private readonly stmtGetRecentUsage;
+  private readonly stmtMarkStale;
+  private readonly stmtMarkDemoted;
+  private readonly stmtMarkActive;
+  private readonly stmtGetConfigSourced;
+  private readonly stmtGetRecentEventsForTool;
+  constructor(db: Database.Database);
+  /**
+   * Inserts or updates a discovered tool in the registry.
+   * On conflict (same name + project_hash), updates description and source.
+   */
+  upsert(tool: DiscoveredTool): void;
+  /**
+   * Increments usage_count and updates last_used_at for a tool.
+   * Called from organic PostToolUse discovery to track usage.
+   */
+  recordUsage(name: string, projectHash: string | null): void;
+  /**
+   * Records usage for an existing tool, or creates it if not yet in the registry.
+   * This is the entry point for organic discovery -- an upsert-and-increment-if-exists pattern.
+   *
+   * First tries recordUsage. If the tool is not in the registry (changes === 0),
+   * calls upsert with the full tool info, which initializes it with usage_count = 0.
+   */
+  recordOrCreate(name: string, defaults: Omit<DiscoveredTool, 'name'>, sessionId?: string | null, success?: boolean): void;
+  /**
+   * Returns global tools plus project-specific tools for the given project.
+   */
+  getForProject(projectHash: string): ToolRegistryRow[];
+  /**
+   * Returns tools available in the resolved scope for a given project.
+   * Implements SCOP-01/SCOP-02/SCOP-03 scope resolution rules.
+   */
+  getAvailableForSession(projectHash: string): ToolRegistryRow[];
+  /**
+   * Returns the top-usage entry for a given tool name.
+   */
+  getByName(name: string): ToolRegistryRow | null;
+  /**
+   * Returns all tools in the registry (for debugging/admin).
+   */
+  getAll(): ToolRegistryRow[];
+  /**
+   * Returns total number of tools in the registry.
+   */
+  count(): number;
+  /**
+   * Returns usage stats for a specific tool within a time window.
+   * @param timeModifier - SQLite datetime modifier, e.g., '-7 days', '-30 days'
+   */
+  getUsageForTool(toolName: string, projectHash: string, timeModifier?: string): ToolUsageStats | null;
+  /**
+   * Returns per-tool usage stats for a specific session.
+   */
+  getUsageForSession(sessionId: string): ToolUsageStats[];
+  /**
+   * Returns per-tool usage stats since a time offset for a project.
+   * @param timeModifier - SQLite datetime modifier, e.g., '-7 days', '-30 days'
+   */
+  getUsageSince(projectHash: string, timeModifier?: string): ToolUsageStats[];
+  /**
+   * Returns per-tool usage stats from the last N events for a project.
+   * Event-count-based window instead of time-based — immune to usage gaps.
+   * @param limit - Number of recent events to consider (default 200)
+   */
+  getRecentUsage(projectHash: string, limit?: number): ToolUsageStats[];
+  /**
+   * Marks a tool as stale (no longer in config but still in registry).
+   * Idempotent -- no-op if already stale.
+   */
+  markStale(name: string, projectHash: string | null): void;
+  /**
+   * Marks a tool as demoted (high failure rate detected).
+   */
+  markDemoted(name: string, projectHash: string | null): void;
+  /**
+   * Marks a tool as active (restored from stale/demoted).
+   * Idempotent -- no-op if already active.
+   */
+  markActive(name: string, projectHash: string | null): void;
+  /**
+   * Returns all config-sourced active tools for a given project (or global).
+   * Used by staleness detection to compare against current config state.
+   */
+  getConfigSourcedTools(projectHash: string): ToolRegistryRow[];
+  /**
+   * Returns recent success/failure events for a specific tool.
+   * Used by failure-driven demotion to check failure rate.
+   * @param limit - Number of recent events to check (default 5)
+   */
+  getRecentEventsForTool(toolName: string, projectHash: string, limit?: number): Array<{
+    success: number;
+  }>;
+  /**
+   * Sanitizes a user query for safe FTS5 MATCH usage.
+   * Removes FTS5 operators and special characters to prevent syntax errors.
+   * Returns null if the query is empty after sanitization.
+   */
+  private sanitizeQuery;
+  /**
+   * FTS5 keyword search on tool_registry_fts (name + description).
+   * Returns ranked results using BM25 with name weighted 2x over description.
+   */
+  searchByKeyword(query: string, options?: {
+    scope?: string;
+    limit?: number;
+  }): ToolSearchResult[];
+  /**
+   * Vector similarity search on tool_registry_embeddings using vec0 KNN.
+   * Returns tool IDs and distances sorted by cosine similarity.
+   */
+  searchByVector(queryEmbedding: Float32Array, options?: {
+    scope?: string;
+    limit?: number;
+  }): Array<{
+    tool_id: number;
+    distance: number;
+  }>;
+  /**
+   * Hybrid search combining FTS5 keyword and vec0 vector results via
+   * reciprocal rank fusion (RRF). Falls back to FTS5-only when vector
+   * search is unavailable (no worker, no sqlite-vec, no embeddings).
+   */
+  searchTools(query: string, options?: {
+    scope?: string;
+    limit?: number;
+    worker?: {
+      isReady(): boolean;
+      embed(text: string): Promise<Float32Array | null>;
+    } | null;
+    hasVectorSupport?: boolean;
+  }): Promise<ToolSearchResult[]>;
+  /**
+   * Stores an embedding vector for a tool in tool_registry_embeddings.
+   * Used by the background embedding loop to index tool descriptions.
+   */
+  storeEmbedding(toolId: number, embedding: Float32Array): void;
+  /**
+   * Returns tools that have descriptions but no embedding yet.
+   * Used by the background embedding loop to find work.
+   */
+  findUnembeddedTools(limit?: number): Array<{
+    id: number;
+    name: string;
+    description: string;
+  }>;
+}
+//#endregion
+//#region src/hooks/handler.d.ts
+/**
+ * Processes a PostToolUse or PostToolUseFailure event through the full
+ * filter pipeline: route research tools -> extract -> privacy -> admission -> store.
+ *
+ * Exported for unit testing of the pipeline logic.
+ */
+declare function processPostToolUseFiltered(input: Record<string, unknown>, obsRepo: ObservationRepository, researchBuffer?: ResearchBufferRepository, toolRegistry?: ToolRegistryRepository, projectHash?: string, db?: better_sqlite30.Database): void;
+//#endregion
+export { processPostToolUseFiltered };
+//# sourceMappingURL=handler.d.ts.map

package/plugin/dist/hooks/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","names":[],"sources":["../../../src/storage/research-buffer.ts","../../../src/shared/tool-types.ts","../../../src/storage/tool-registry.ts","../../../src/hooks/handler.ts"],"mappings":";;;;;;;;;AAcA;;;;;;cAAa,wBAAA;EAAA,iBACM,EAAA;EAAA,iBACA,WAAA;EAAA,iBAEA,UAAA;EAAA,iBACA,aAAA;EAAA,iBACA,SAAA;cAEL,EAAA,EAAI,QAAA,CAAc,QAAA,EAAU,WAAA;EAAA;;;EA2BxC,GAAA,CAAI,KAAA;IACF,SAAA;IACA,QAAA;IACA,MAAA;EAAA;EAmBA;;;EAFF,SAAA,CACE,SAAA,UACA,aAAA,YACC,KAAA;IAAQ,QAAA;IAAkB,MAAA;IAAgB,SAAA;EAAA;EAiBV;;;EAAnC,KAAA,CAAM,gBAAA;AAAA;;;;;;KCtFI,QAAA;;ADWZ;;KCNY,SAAA;;;;;UAMK,cAAA;EACf,IAAA;EACA,QAAA,EAAU,QAAA;EACV,KAAA,EAAO,SAAA;EACP,MAAA;EACA,WAAA;EACA,WAAA;EACA,UAAA;EACA,YAAA;AAAA;;;;UAMe,eAAA;EACf,EAAA;EACA,IAAA;EACA,SAAA;EACA,KAAA;EACA,MAAA;EACA,YAAA;EACA,WAAA;EACA,WAAA;EACA,aAAA;EACA,WAAA;EACA,YAAA;EACA,aAAA;EACA,UAAA;EACA,MAAA;AAAA;;;;UAkBe,cAAA;EACf,SAAA;EACA,WAAA;EACA,SAAA;AAAA;;;;UAMe,gBAAA;EACf,IAAA,EAAM,eAAA;EACN,KAAA;EACA,SAAA;AAAA;;;;;;AD1DF;;;;;;;cEEa,sBAAA;EAAA,iBACM,EAAA;EAAA,iBAGA,UAAA;EAAA,iBACA,eAAA;EAAA,iBACA,cAAA;EAAA,iBACA,aAAA;EAAA,iBACA,UAAA;EAAA,iBACA,SAAA;EAAA,iBACA,0BAAA;EAAA,iBACA,eAAA;EAAA,iBACA,mBAAA;EAAA,iBACA,sBAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,kBAAA;EAAA,iBACA,aAAA;EAAA,iBACA,eAAA;EAAA,iBACA,cAAA;EAAA,iBACA,oBAAA;EAAA,iBACA,0BAAA;cAEL,EAAA,EAAI,QAAA,CAAc,QAAA;EFmDxB;;;;EE4GN,MAAA,CAAO,IAAA,EAAM,cAAA;;ADlMf;;;ECwNE,WAAA,CAAY,IAAA,UAAc,WAAA;EDxNR;AAKpB;;;;;AAMA;EC6NE,cAAA,CACE,IAAA,UACA,QAAA,EAAU,IAAA,CAAK,cAAA,WACf,SAAA,kBACA,OAAA;;;;EAqBF,aAAA,CAAc,WAAA,WAAsB,eAAA;EDpP1B;;;;EC4PV,sBAAA,CAAuB,WAAA,WAAsB,eAAA;EDxP7C;;;EC+PA,SAAA,CAAU,IAAA,WAAe,eAAA;ED7Pb;AAMd;;EC+PE,MAAA,CAAA,GAAU,eAAA;ED/PoB;;;ECsQ9B,KAAA,CAAA;EDlQA;;;;EC2QA,eAAA,CAAgB,QAAA,UAAkB,WAAA,UAAqB,YAAA,YAAmC,cAAA;EDtQ1F;;;EC8QA,kBAAA,CAAmB,SAAA,WAAoB,cAAA;ED1QvC;;;;ECkRA,aAAA,CAAc,WAAA,UAAqB,YAAA,YAAmC,cAAA;ED/PzC;;;;;ECwQ7B,cAAA,CAAe,WAAA,UAAqB,KAAA,YAAsB,cAAA;EDrQjD;;AAMX;;EC2QE,SAAA,CAAU,IAAA,UAAc,WAAA;ED1QH;;;ECsRrB,WAAA,CAAY,IAAA,UAAc,WAAA;EDpR1B;;;;ECiSA,UAAA,CAAW,IAAA,UAAc,WAAA;;AAzV3B;;;EAsWE,qBAAA,CAAsB,WAAA,WAAsB,eAAA;EAjL/B;;;;;EA+Lb,sBAAA,CAAuB,QAAA,UAAkB,WAAA,UAAqB,KAAA,YAAoB,KAAA;IAAQ,OAAA;EAAA;EAjFnD;;;;;EAAA,QAmG/B,aAAA;EAyDuB;;;;EAtC/B,eAAA,CAAgB,KAAA,UAAe,OAAA;IAAY,KAAA;IAAgB,KAAA;EAAA,IAAmB,gBAAA;EAkKjC;;;;EA5H7C,cAAA,CAAe,cAAA,EAAgB,YAAA,EAAc,OAAA;IAAY,KAAA;IAAgB,KAAA;EAAA,IAAmB,KAAA;IAAQ,OAAA;IAAiB,QAAA;EAAA;EAnbpG;;;;;EAwdX,WAAA,CACJ,KAAA,UACA,OAAA;IACE,KAAA;IACA,KAAA;IACA,MAAA;MAAW,OAAA;MAAoB,KAAA,CAAM,IAAA,WAAe,OAAA,CAAQ,YAAA;IAAA;IAC5D,gBAAA;EAAA,IAED,OAAA,CAAQ,gBAAA;EAvTE;;;;EAwXb,cAAA,CAAe,MAAA,UAAgB,SAAA,EAAW,YAAA;EAlV1C;;;;EAgWA,mBAAA,CAAoB,KAAA,YAAoB,KAAA;IAAQ,EAAA;IAAY,IAAA;IAAc,WAAA;EAAA;AAAA;;;;;AF7jB5E;;;;iBGkDgB,0BAAA,CACd,KAAA,EAAO,MAAA,mBACP,OAAA,EAAS,qBAAA,EACT,cAAA,GAAiB,wBAAA,EACjB,YAAA,GAAe,sBAAA,EACf,WAAA,WACA,EAAA,GAFqC,eAAA,CAEP,QAAA"}