gramatr 0.3.0

package/hooks/GMTRToolTracker.hook.ts

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * GMTRToolTracker.hook.ts — grāmatr PostToolUse Hook
+ *
+ * Fires after any GMTR MCP tool call. Extracts execution metrics from
+ * tool_result and surfaces them as a user-visible status line.
+ *
+ * TRIGGER: PostToolUse (matcher: mcp__.*gramatr.*__)
+ * PERFORMANCE: <5ms. Outputs continue immediately, then processes.
+ *
+ * What it surfaces:
+ * - Tool name (short form, e.g., "search_semantic")
+ * - Classifier model + inference time (if intelligence layer was used)
+ * - Token savings ratio
+ * - Cache hit/miss
+ * - Total execution time
+ *
+ * Output format (to stderr, visible in Claude Code):
+ *   [GMTR] search_semantic | 1.4s | qwen2.5:14b 0.32s | saved 6K tokens (80%) | cache:MISS
+ */
+
+import { extractToolShortName, extractExecutionSummary, buildStatusLine } from './gmtr-tool-tracker-utils.js';
+import type { ExecutionSummary } from './gmtr-tool-tracker-utils.js';
+
+// ── Types ──
+
+interface HookInput {
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  tool_response: Array<{ type: string; text?: string }>;  // Claude Code sends tool_response (array), not tool_result (string)
+  session_id: string;
+  hook_event_name?: string;
+  tool_use_id?: string;
+}
+
+// ── Stdin Reader ──
+
+function readStdin(timeoutMs: number): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    const timer = setTimeout(() => resolve(data), timeoutMs);
+
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk: string) => { data += chunk; });
+    process.stdin.on('end', () => { clearTimeout(timer); resolve(data); });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(data); });
+    process.stdin.resume();
+  });
+}
+
+// ── Debug Logger ──
+
+async function debugLog(msg: string) {
+  try {
+    const { appendFileSync } = await import('fs');
+    appendFileSync('/tmp/gmtr-hook-debug.log', `[${new Date().toISOString()}] ${msg}\n`);
+  } catch {}
+}
+
+// ── Main ──
+
+async function main() {
+  // Step 1: Read stdin FIRST — data is already in pipe buffer from Claude Code.
+  // Writing stdout before reading stdin causes Claude Code to close the pipe,
+  // which means the hook never sees the tool_result data.
+  const raw = await readStdin(3000);
+
+  // Step 2: NOW output continue — never block Claude Code longer than necessary
+  console.log(JSON.stringify({ continue: true }));
+
+  await debugLog(`stdin=${raw.length}b`);
+
+  if (!raw.trim()) {
+    await debugLog('empty stdin, exiting');
+    return;
+  }
+
+  let input: HookInput;
+  try {
+    input = JSON.parse(raw);
+  } catch (e) {
+    await debugLog(`parse error: ${e}`);
+    return;
+  }
+
+  await debugLog(`tool=${input.tool_name} response=${input.tool_response?.length || 0} items`);
+
+  const { tool_name, tool_response } = input;
+  if (!tool_name || !tool_response) return;
+
+  // Extract short tool name and execution metrics
+  const shortName = extractToolShortName(tool_name);
+  const summary = extractExecutionSummary(tool_response);
+
+  // Build and emit status line to stderr (visible in Claude Code)
+  const status = buildStatusLine(shortName, summary);
+  process.stderr.write(`${status}\n`);
+
+  // Write metrics to temp file for status line script to read
+  const metricsFile = '/tmp/gmtr-last-op.json';
+  const metrics = {
+    tool: shortName,
+    model: summary?.qwen_model || null,
+    time_ms: summary?.execution_time_ms || null,
+    tokens_saved: summary?.tokens_saved || null,
+    cache_hit: summary?.cache_hit ?? null,
+    result_count: summary?.results_count || null,
+    timestamp: Date.now(),
+  };
+  const { writeFileSync, appendFileSync, readFileSync } = await import('fs');
+  try {
+    writeFileSync(metricsFile, JSON.stringify(metrics));
+  } catch {
+    // Non-critical — status line just won't show metrics
+  }
+
+  // Append to operation history (for sparkline/counts in status line)
+  const historyFile = '/tmp/gmtr-op-history.jsonl';
+  try {
+    const historyEntry = JSON.stringify({
+      tool: shortName,
+      model: summary?.qwen_model || null,
+      time_ms: summary?.execution_time_ms || 0,
+      tokens_saved: summary?.tokens_saved || 0,
+      cache_hit: summary?.cache_hit ?? false,
+      timestamp: Date.now(),
+    });
+    appendFileSync(historyFile, historyEntry + '\n');
+  } catch {
+    // Non-critical
+  }
+
+  // Extract and cache GMTR server stats from tool response (entity/obs counts etc.)
+  try {
+    // tool_response is already a parsed array: [{ type: "text", text: "..." }]
+    let resultData: Record<string, unknown> | null = null;
+    const textItem = tool_response.find((item: { type: string; text?: string }) => item.type === 'text' && item.text);
+    if (textItem?.text) {
+      try { resultData = JSON.parse(textItem.text); } catch {}
+    }
+
+    if (resultData) {
+      // Look for entity_count, observation_count etc. in search results
+      const statsFile = '/tmp/gmtr-stats.json';
+      let stats: Record<string, unknown> = {};
+      try { stats = JSON.parse(readFileSync(statsFile, 'utf8')); } catch {}
+
+      // Track search count
+      if (shortName.includes('search') || shortName === 'gmtr_execute_intent') {
+        stats.search_count = ((stats.search_count as number) || 0) + 1;
+      }
+
+      // Track entity/observation counts if returned in results
+      if (resultData.total_entities !== undefined) stats.entity_count = resultData.total_entities;
+      if (resultData.total_observations !== undefined) stats.observation_count = resultData.total_observations;
+      if (resultData.entity_count !== undefined) stats.entity_count = resultData.entity_count;
+
+      // Capture classifier progression data from execution_summary (Issue #34)
+      if (summary) {
+        if (summary.classifier_level !== undefined) stats.classifier_level = summary.classifier_level;
+        if (summary.classifier_model !== undefined) stats.classifier_model = summary.classifier_model;
+        if (summary.total_classifications !== undefined) stats.total_classifications = summary.total_classifications;
+        if (summary.total_feedback !== undefined) stats.total_feedback = summary.total_feedback;
+        if (summary.feedback_rate !== undefined) stats.feedback_rate = summary.feedback_rate;
+        if (summary.accuracy !== undefined) stats.accuracy = summary.accuracy;
+      }
+
+      // Track local classification count (increments on every GMTR call)
+      stats.local_call_count = ((stats.local_call_count as number) || 0) + 1;
+
+      stats.status = 'connected';
+      stats.last_seen = Date.now();
+
+      writeFileSync(statsFile, JSON.stringify(stats));
+    }
+  } catch {
+    // Non-critical
+  }
+}
+
+main().catch(() => {});

package/hooks/StopOrchestrator.hook.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * StopOrchestrator.hook.ts — Stop event handler (thin client)
+ *
+ * Fires when the user stops Claude. Reads the transcript and sends
+ * classification feedback to the gramatr server via HTTP.
+ *
+ * In the thin client, all other Stop handlers (TabState, RebuildSkill,
+ * AlgorithmEnrichment, DocCrossRefIntegrity) are server-side.
+ */
+
+import { readFileSync } from 'fs';
+import { parseTranscript } from './lib/transcript-parser';
+import { getGmtrDir } from './lib/paths';
+
+interface HookInput {
+  session_id: string;
+  transcript_path: string;
+}
+
+async function main() {
+  let input = '';
+  try {
+    for await (const chunk of process.stdin) {
+      input += chunk;
+    }
+  } catch { /* timeout ok */ }
+
+  if (!input.trim()) { process.exit(0); }
+
+  const hookInput: HookInput = JSON.parse(input);
+  if (!hookInput.transcript_path) { process.exit(0); }
+
+  // Parse transcript for classification feedback
+  const parsed = parseTranscript(hookInput.transcript_path);
+
+  // Read server URL and token for direct HTTP feedback
+  const gmtrDir = getGmtrDir();
+  let serverUrl = process.env.GMTR_URL || 'https://api.gramatr.com/mcp';
+  let token = '';
+
+  try {
+    const gmtrJson = JSON.parse(readFileSync(`${process.env.HOME}/.gmtr.json`, 'utf8'));
+    token = gmtrJson.token || '';
+  } catch { /* no token */ }
+
+  if (!token || !parsed) { process.exit(0); }
+
+  // Send classification feedback via MCP
+  try {
+    const baseUrl = serverUrl.replace(/\/mcp\/?$/, '');
+    await fetch(`${baseUrl}/mcp`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json, text/event-stream',
+        'Authorization': `Bearer ${token}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: {
+          name: 'gmtr_classification_feedback',
+          arguments: {
+            original_prompt: parsed.userMessages?.[0] || '',
+            session_id: hookInput.session_id,
+          },
+        },
+      }),
+      signal: AbortSignal.timeout(5000),
+    });
+  } catch { /* best effort */ }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/hooks/gmtr-tool-tracker-utils.ts

@@ -0,0 +1,105 @@
+/**
+ * gmtr-tool-tracker-utils.ts — Pure utility functions for the GMTR Tool Tracker hook.
+ *
+ * Extracted from GMTRToolTracker.hook.ts for testability. These are pure functions
+ * with no Bun dependencies, no I/O, no side effects.
+ */
+
+// ── Types ──
+
+export interface ExecutionSummary {
+  execution_time_ms?: number;
+  qwen_calls?: number;
+  qwen_time_ms?: number;
+  qwen_model?: string;
+  tokens_saved?: number;
+  savings_ratio?: number;
+  cache_hit?: boolean;
+  action?: string;
+  results_count?: number;
+  visual_query_detected?: boolean;
+  visual_results_count?: number;
+  classifier_level?: number;
+  classifier_model?: string;
+  total_classifications?: number;
+  total_feedback?: number;
+  feedback_rate?: number;
+  accuracy?: number;
+}
+
+// ── Helpers ──
+
+export function extractToolShortName(fullName: string): string {
+  // mcp__gramatr__search_semantic -> search_semantic
+  const parts = fullName.split('__');
+  return parts[parts.length - 1] || fullName;
+}
+
+export function formatTokens(n: number): string {
+  if (n >= 1000) return `${(n / 1000).toFixed(n >= 10000 ? 0 : 1)}K`;
+  return n.toString();
+}
+
+export function formatMs(ms: number): string {
+  if (ms >= 1000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.round(ms)}ms`;
+}
+
+export function extractExecutionSummary(toolResponse: Array<{ type: string; text?: string }>): ExecutionSummary | null {
+  try {
+    for (const item of toolResponse) {
+      if (item.type === 'text' && item.text) {
+        try {
+          const inner = JSON.parse(item.text);
+          if (inner.execution_summary) return inner.execution_summary;
+          if (inner.execution_time_ms !== undefined) return inner;
+        } catch {
+          // text wasn't JSON, skip
+        }
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function buildStatusLine(toolShortName: string, summary: ExecutionSummary | null): string {
+  const parts: string[] = [`[GMTR] ${toolShortName}`];
+
+  if (summary) {
+    if (summary.execution_time_ms) {
+      parts.push(formatMs(summary.execution_time_ms));
+    }
+
+    if (summary.qwen_calls && summary.qwen_calls > 0) {
+      const model = summary.qwen_model || 'qwen2.5:14b';
+      const time = summary.qwen_time_ms ? ` ${formatMs(summary.qwen_time_ms)}` : '';
+      parts.push(`${model}${time}`);
+    }
+
+    if (summary.tokens_saved && summary.tokens_saved > 0) {
+      const pct = summary.savings_ratio
+        ? ` (${Math.round(summary.savings_ratio * 100)}%)`
+        : '';
+      parts.push(`saved ${formatTokens(summary.tokens_saved)} tokens${pct}`);
+    }
+
+    if (summary.cache_hit !== undefined) {
+      parts.push(`cache:${summary.cache_hit ? 'HIT' : 'MISS'}`);
+    }
+
+    if (summary.visual_query_detected) {
+      const count = summary.visual_results_count || 0;
+      parts.push(`visual:${count}`);
+    }
+
+    if (summary.results_count !== undefined) {
+      parts.push(`${summary.results_count} results`);
+    }
+  } else {
+    parts.push('OK');
+  }
+
+  return parts.join(' | ');
+}