@gramatr/client 0.5.1

package/hooks/lib/transcript-parser.ts

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+/**
+ * transcript-parser.ts - Claude transcript parsing utilities
+ *
+ * Shared library for extracting content from Claude Code transcript files.
+ * Used by Stop hooks for voice, tab state, and response capture.
+ *
+ * CLI Usage:
+ *   bun transcript-parser.ts <transcript_path>
+ *   bun transcript-parser.ts <transcript_path> --voice
+ *   bun transcript-parser.ts <transcript_path> --plain
+ *   bun transcript-parser.ts <transcript_path> --structured
+ *   bun transcript-parser.ts <transcript_path> --state
+ *
+ * Module Usage:
+ *   import { parseTranscript, getLastAssistantMessage } from './transcript-parser'
+ */
+
+import { readFileSync } from 'fs';
+import { getIdentity } from './identity';
+
+const DA_IDENTITY = getIdentity();
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface StructuredResponse {
+  date?: string;
+  summary?: string;
+  analysis?: string;
+  actions?: string;
+  results?: string;
+  status?: string;
+  next?: string;
+  completed?: string;
+}
+
+export type ResponseState = 'awaitingInput' | 'completed' | 'error';
+
+export interface ParsedTranscript {
+  /** Raw transcript content */
+  raw: string;
+  /** Last assistant message text */
+  lastMessage: string;
+  /** Full text from current response turn (all assistant blocks combined) */
+  currentResponseText: string;
+  /** Voice completion text (for TTS) */
+  voiceCompletion: string;
+  /** Plain completion text (for tab title) */
+  plainCompletion: string;
+  /** Structured sections extracted from response */
+  structured: StructuredResponse;
+  /** Response state for tab coloring */
+  responseState: ResponseState;
+  /** Last real user prompt text */
+  lastUserPrompt: string;
+}
+
+// ============================================================================
+// Core Parsing Functions
+// ============================================================================
+
+/**
+ * Safely convert Claude content (string or array of blocks) to plain text.
+ */
+export function contentToText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map(c => {
+        if (typeof c === 'string') return c;
+        if (c?.text) return c.text;
+        if (c?.content) return contentToText(c.content);
+        return '';
+      })
+      .join(' ')
+      .trim();
+  }
+  return '';
+}
+
+/**
+ * Parse last assistant message from transcript content.
+ * Takes raw content string to avoid re-reading file.
+ */
+export function parseLastAssistantMessage(transcriptContent: string): string {
+  const lines = transcriptContent.trim().split('\n');
+  let lastAssistantMessage = '';
+
+  for (const line of lines) {
+    if (line.trim()) {
+      try {
+        const entry = JSON.parse(line) as any;
+        if (entry.type === 'assistant' && entry.message?.content) {
+          const text = contentToText(entry.message.content);
+          if (text) {
+            lastAssistantMessage = text;
+          }
+        }
+      } catch {
+        // Skip invalid JSON lines
+      }
+    }
+  }
+
+  return lastAssistantMessage;
+}
+
+/**
+ * Collect assistant text from the CURRENT response turn only.
+ * A "turn" is everything after the last human message in the transcript.
+ * This prevents voice/completion extraction from picking up stale lines
+ * from previous turns when the Stop hook fires.
+ *
+ * Within a single turn, there may be multiple assistant entries
+ * (text → tool_use → tool_result → more text). All are collected.
+ */
+export function collectCurrentResponseText(transcriptContent: string): string {
+  const lines = transcriptContent.trim().split('\n');
+
+  // Find the index of the last REAL user prompt.
+  // Claude Code transcript uses type='user' for both actual user prompts AND
+  // tool_result entries (which are mid-response). Real user prompts have at
+  // least one {type:'text'} content block. Tool results only have {type:'tool_result'}.
+  let lastHumanIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim()) {
+      try {
+        const entry = JSON.parse(lines[i]) as any;
+        if (entry.type === 'human' || entry.type === 'user') {
+          const content = entry.message?.content;
+          // String content = real user message
+          if (typeof content === 'string') {
+            lastHumanIndex = i;
+          } else if (Array.isArray(content)) {
+            // Check for text blocks — indicates a real user prompt
+            const hasText = content.some((b: any) => b?.type === 'text' && b?.text?.trim());
+            if (hasText) {
+              lastHumanIndex = i;
+            }
+          }
+        }
+      } catch {
+        // Skip invalid JSON lines
+      }
+    }
+  }
+
+  // Collect only assistant text AFTER the last human message
+  const textParts: string[] = [];
+  for (let i = lastHumanIndex + 1; i < lines.length; i++) {
+    if (lines[i].trim()) {
+      try {
+        const entry = JSON.parse(lines[i]) as any;
+        if (entry.type === 'assistant' && entry.message?.content) {
+          const text = contentToText(entry.message.content);
+          if (text) {
+            textParts.push(text);
+          }
+        }
+      } catch {
+        // Skip invalid JSON lines
+      }
+    }
+  }
+
+  return textParts.join('\n');
+}
+
+export function parseLastUserPrompt(transcriptContent: string): string {
+  const lines = transcriptContent.trim().split('\n');
+  let lastUserPrompt = '';
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    try {
+      const entry = JSON.parse(line) as any;
+      if (entry.type === 'human' || entry.type === 'user') {
+        const content = entry.message?.content;
+        if (typeof content === 'string' && content.trim()) {
+          lastUserPrompt = content.trim();
+        } else if (Array.isArray(content)) {
+          const text = content
+            .filter((block: any) => block?.type === 'text' && typeof block?.text === 'string')
+            .map((block: any) => block.text.trim())
+            .filter(Boolean)
+            .join('\n')
+            .trim();
+          if (text) lastUserPrompt = text;
+        }
+      }
+    } catch {
+      // Ignore malformed rows
+    }
+  }
+
+  return lastUserPrompt;
+}
+
+/**
+ * Get last assistant message from transcript file.
+ * Convenience function that reads file and parses.
+ */
+export function getLastAssistantMessage(transcriptPath: string): string {
+  try {
+    const content = readFileSync(transcriptPath, 'utf-8');
+    return parseLastAssistantMessage(content);
+  } catch (error) {
+    console.error('[TranscriptParser] Error reading transcript:', error);
+    return '';
+  }
+}
+
+// ============================================================================
+// Extraction Functions
+// ============================================================================
+
+/**
+ * Extract voice completion line for TTS.
+ * Uses LAST match to avoid capturing mentions in analysis text.
+ */
+export function extractVoiceCompletion(text: string): string {
+  // Remove system-reminder tags
+  text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '');
+
+  // Use global flag and find LAST match (voice line is at end of response)
+  const completedPatterns = [
+    new RegExp(`🗣️\\s*\\*{0,2}${DA_IDENTITY.name}:?\\*{0,2}\\s*(.+?)(?:\\n|$)`, 'gi'),
+    /🎯\s*\*{0,2}COMPLETED:?\*{0,2}\s*(.+?)(?:\n|$)/gi,
+  ];
+
+  for (const pattern of completedPatterns) {
+    const matches = [...text.matchAll(pattern)];
+    if (matches.length > 0) {
+      // Use LAST match - the actual voice line at end of response
+      const lastMatch = matches[matches.length - 1];
+      if (lastMatch && lastMatch[1]) {
+        let completed = lastMatch[1].trim();
+        // Clean up agent tags
+        completed = completed.replace(/^\[AGENT:\w+\]\s*/i, '');
+        // Voice server handles sanitization
+        return completed.trim();
+      }
+    }
+  }
+
+  // Don't say anything if no voice line found
+  return '';
+}
+
+/**
+ * Extract plain completion text for display/tab titles.
+ * Uses LAST match to avoid capturing mentions in analysis text.
+ */
+export function extractCompletionPlain(text: string): string {
+  text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '');
+
+  // Use global flag and find LAST match (voice line is at end of response)
+  const completedPatterns = [
+    new RegExp(`🗣️\\s*\\*{0,2}${DA_IDENTITY.name}:?\\*{0,2}\\s*(.+?)(?:\\n|$)`, 'gi'),
+    /🎯\s*\*{0,2}COMPLETED:?\*{0,2}\s*(.+?)(?:\n|$)/gi,
+  ];
+
+  for (const pattern of completedPatterns) {
+    const matches = [...text.matchAll(pattern)];
+    if (matches.length > 0) {
+      // Use LAST match - the actual voice line at end of response
+      const lastMatch = matches[matches.length - 1];
+      if (lastMatch && lastMatch[1]) {
+        let completed = lastMatch[1].trim();
+        completed = completed.replace(/^\[AGENT:\w+\]\s*/i, '');
+        completed = completed.replace(/\[.*?\]/g, '');
+        completed = completed.replace(/\*\*/g, '');
+        completed = completed.replace(/\*/g, '');
+        completed = completed.replace(/[\p{Emoji}\p{Emoji_Component}]/gu, '');
+        completed = completed.replace(/\s+/g, ' ').trim();
+        return completed;
+      }
+    }
+  }
+
+  // Fallback: try to extract something meaningful from the response
+  const summaryMatch = text.match(/📋\s*\*{0,2}SUMMARY:?\*{0,2}\s*(.+?)(?:\n|$)/i);
+  if (summaryMatch && summaryMatch[1]) {
+    let summary = summaryMatch[1].trim().slice(0, 30);
+    return summary.length > 27 ? summary.slice(0, 27) + '…' : summary;
+  }
+
+  // No voice line found — return empty, let downstream handle fallback
+  return '';
+}
+
+/**
+ * Extract structured sections from response.
+ */
+export function extractStructuredSections(text: string): StructuredResponse {
+  const result: StructuredResponse = {};
+
+  text = text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '');
+
+  const patterns: Record<keyof StructuredResponse, RegExp> = {
+    date: /📅\s*(.+?)(?:\n|$)/i,
+    summary: /📋\s*SUMMARY:\s*(.+?)(?:\n|$)/i,
+    analysis: /🔍\s*ANALYSIS:\s*(.+?)(?:\n|$)/i,
+    actions: /⚡\s*ACTIONS:\s*(.+?)(?:\n|$)/i,
+    results: /✅\s*RESULTS:\s*(.+?)(?:\n|$)/i,
+    status: /📊\s*STATUS:\s*(.+?)(?:\n|$)/i,
+    next: /➡️\s*NEXT:\s*(.+?)(?:\n|$)/i,
+    completed: new RegExp(`(?:🗣️\\s*${DA_IDENTITY.name}:|🎯\\s*COMPLETED:)\\s*(.+?)(?:\\n|$)`, 'i'),
+  };
+
+  for (const [key, pattern] of Object.entries(patterns)) {
+    const match = text.match(pattern);
+    if (match && match[1]) {
+      result[key as keyof StructuredResponse] = match[1].trim();
+    }
+  }
+
+  return result;
+}
+
+// ============================================================================
+// State Detection
+// ============================================================================
+
+/**
+ * Detect response state for tab coloring.
+ * Takes parsed content to avoid re-reading file.
+ */
+export function detectResponseState(lastMessage: string, transcriptContent: string): ResponseState {
+  try {
+    // Check if the LAST assistant message used AskUserQuestion
+    const lines = transcriptContent.trim().split('\n');
+    let lastAssistantEntry: any = null;
+
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry.type === 'assistant' && entry.message?.content) {
+          lastAssistantEntry = entry;
+        }
+      } catch {}
+    }
+
+    if (lastAssistantEntry?.message?.content) {
+      const content = Array.isArray(lastAssistantEntry.message.content)
+        ? lastAssistantEntry.message.content
+        : [];
+      for (const block of content) {
+        if (block.type === 'tool_use' && block.name === 'AskUserQuestion') {
+          return 'awaitingInput';
+        }
+      }
+    }
+  } catch (err) {
+    console.error('[TranscriptParser] Error detecting response state:', err);
+  }
+
+  // Check for error indicators
+  if (/📊\s*STATUS:.*(?:error|failed|broken|problem|issue)/i.test(lastMessage)) {
+    return 'error';
+  }
+
+  const hasErrorKeyword = /\b(?:error|failed|exception|crash|broken)\b/i.test(lastMessage);
+  const hasErrorEmoji = /❌|🚨|⚠️/.test(lastMessage);
+  if (hasErrorKeyword && hasErrorEmoji) {
+    return 'error';
+  }
+
+  return 'completed';
+}
+
+// ============================================================================
+// Unified Parser
+// ============================================================================
+
+/**
+ * Parse transcript and extract all relevant data in one pass.
+ * This is the main function for the orchestrator pattern.
+ */
+export function parseTranscript(transcriptPath: string): ParsedTranscript {
+  try {
+    const raw = readFileSync(transcriptPath, 'utf-8');
+    const lastMessage = parseLastAssistantMessage(raw);
+    // Collect assistant text from CURRENT response turn only.
+    // This prevents stale voice lines from previous turns being read
+    // when the Stop hook fires. Within the current turn, multiple
+    // assistant entries exist (text → tool_use → tool_result → more text).
+    const currentResponseText = collectCurrentResponseText(raw);
+
+    return {
+      raw,
+      lastMessage,
+      currentResponseText,
+      voiceCompletion: extractVoiceCompletion(currentResponseText),
+      plainCompletion: extractCompletionPlain(currentResponseText),
+      structured: extractStructuredSections(currentResponseText),
+      responseState: detectResponseState(lastMessage, raw),
+      lastUserPrompt: parseLastUserPrompt(raw),
+    };
+  } catch (error) {
+    console.error('[TranscriptParser] Error parsing transcript:', error);
+    return {
+      raw: '',
+      lastMessage: '',
+      currentResponseText: '',
+      voiceCompletion: '',
+      plainCompletion: '',
+      structured: {},
+      responseState: 'completed',
+      lastUserPrompt: '',
+    };
+  }
+}
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const transcriptPath = args.find(a => !a.startsWith('-'));
+
+  if (!transcriptPath) {
+    console.log(`Usage: bun transcript-parser.ts <transcript_path> [options]
+
+Options:
+  --voice       Output voice completion (for TTS)
+  --plain       Output plain completion (for tab titles)
+  --structured  Output structured sections as JSON
+  --state       Output response state
+  --all         Output full parsed transcript as JSON (default)
+`);
+    process.exit(1);
+  }
+
+  const parsed = parseTranscript(transcriptPath);
+
+  if (args.includes('--voice')) {
+    console.log(parsed.voiceCompletion);
+  } else if (args.includes('--plain')) {
+    console.log(parsed.plainCompletion);
+  } else if (args.includes('--structured')) {
+    console.log(JSON.stringify(parsed.structured, null, 2));
+  } else if (args.includes('--state')) {
+    console.log(parsed.responseState);
+  } else {
+    // Default: output everything
+    console.log(JSON.stringify(parsed, null, 2));
+  }
+}

package/hooks/session-end.hook.ts

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * session-end.hook.ts — gramatr SessionEnd Hook
+ *
+ * Replaces session-end.sh (176 lines). Tracks session completion,
+ * saves commit history, and registers handoff with gramatr server.
+ *
+ * TRIGGER: SessionEnd
+ * OUTPUT: stderr (user display)
+ *
+ * ZERO external CLI dependencies — no jq, sed, curl, awk.
+ */
+
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import {
+  readHookInput,
+  getGitContext,
+  deriveProjectId,
+  readGmtrConfig,
+  writeGmtrConfig,
+  resolveAuthToken,
+  callMcpToolRaw,
+  getCommitCountSince,
+  getCommitLogSince,
+  getCommitsSince,
+  getFilesChanged,
+  appendLine,
+  log,
+  now,
+} from './lib/gmtr-hook-utils.ts';
+
+async function main(): Promise<void> {
+  try {
+    log('\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501');
+    log('Claude Code Session Ending...');
+    log('\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501');
+
+    const input = await readHookInput();
+    const sessionId = input.session_id || 'unknown';
+    const reason = input.reason || 'other';
+    const timestamp = now();
+    const home = process.env.HOME || '';
+
+    const git = getGitContext();
+
+    if (git) {
+      const projectId = deriveProjectId(git.remote, git.projectName);
+
+      log(`Project: ${git.projectName} (${projectId})`);
+      log(`Session: ${sessionId}`);
+      log(`Reason: ${reason}`);
+
+      // Get commit stats
+      const config = readGmtrConfig(git.root);
+      const sessionStart =
+        config?.current_session?.last_updated || config?.metadata?.updated || '';
+
+      let commitsCount = 0;
+      if (sessionStart) {
+        commitsCount = getCommitCountSince(sessionStart);
+
+        if (commitsCount > 0) {
+          log(`  Commits made this session: ${commitsCount}`);
+
+          // Save commit summary for next session
+          const commitLog = getCommitLogSince(sessionStart);
+          const commitsFile = join(home, '.claude', 'last-session-commits.txt');
+          writeFileSync(commitsFile, commitLog.join('\n') + '\n');
+          log('  Commit history saved for next session');
+        } else {
+          log('  No commits this session');
+        }
+      }
+
+      // Write session end marker
+      const historyFile = join(home, '.claude', 'session-history.log');
+      appendLine(historyFile, `Session ended at ${timestamp} (reason: ${reason}, session: ${sessionId})`);
+
+      // Update settings.json
+      if (config) {
+        config.metadata = config.metadata || {};
+        config.metadata.updated = timestamp;
+        config.metadata.last_session_end_reason = reason;
+        config.project_id = projectId;
+        writeGmtrConfig(git.root, config);
+        log('  Updated settings.json');
+      }
+
+      // ── Automatic Handoff to gramatr ──
+      const token = resolveAuthToken();
+
+      if (token) {
+        // Build session summary from git data
+        let branch = 'unknown';
+        try {
+          const { execSync } = await import('child_process');
+          branch = execSync('git rev-parse --abbrev-ref HEAD', {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+          }).trim();
+        } catch {
+          // ignore
+        }
+
+        // Build structured handoff summary (5 required sections)
+        let commitList: string[] = [];
+        let modified: string[] = [];
+        if (commitsCount > 0 && sessionStart) {
+          commitList = getCommitsSince(sessionStart, 10);
+        }
+        if (commitsCount > 0) {
+          modified = getFilesChanged(`HEAD~${Math.min(commitsCount, 20)}`, 'HEAD', 15);
+        }
+
+        // Section 1: WHERE WE ARE
+        let summary = `Session ended (${reason}). Project: ${git.projectName} (${projectId}). Branch: ${branch}.`;
+        if (commitsCount > 0) {
+          summary += ` Commits: ${commitsCount}. ${commitList.join('; ')}`;
+        }
+        if (modified.length > 0) {
+          summary += ` Files: ${modified.join(', ')}`;
+        }
+
+        // Get session state from config
+        const sessionEntityId = config?.current_session?.gmtr_entity_id || '';
+        const interactionId = config?.current_session?.interaction_id || '';
+
+        log('');
+        log('Saving session state to gramatr...');
+
+        // Session lifecycle only — gmtr_session_end records git summary on the session entity.
+        // Handoffs are saved by the AGENT in the LEARN phase via gmtr_save_handoff (HARD GATE).
+        // The hook does NOT save handoffs — it lacks conversation context.
+        try {
+          const rawResult = await callMcpToolRaw('gmtr_session_end', {
+            entity_id: sessionEntityId || sessionId,
+            session_id: sessionId,
+            interaction_id: interactionId,
+            project_id: projectId,
+            summary: summary,
+            tool_call_count: 0,
+          });
+
+          if (rawResult && rawResult.includes('"status":"ended"')) {
+            log('  Session end recorded');
+          } else if (rawResult && rawResult.includes('"isError":true')) {
+            log('  Session end had errors (session may not have gmtr entity)');
+          } else {
+            log('  Session end uncertain (server may be unavailable)');
+          }
+        } catch {
+          log('  Session end uncertain (server may be unavailable)');
+        }
+      } else {
+        log('  No auth token \u2014 skipping gramatr handoff');
+      }
+    }
+
+    log('\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501');
+    log('Session cleanup complete');
+    log('\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501');
+  } catch (err) {
+    log(`[gramatr] session-end error: ${String(err)}`);
+  }
+}
+
+main();