@rkarim08/sia 1.0.0

package/src/hooks/handlers/post-tool-use.ts

@@ -0,0 +1,403 @@
+// Module: post-tool-use — PostToolUse hook handler
+//
+// Receives events after each tool invocation and extracts knowledge:
+// - Write  → FileNode entity + TrackA code entities + knowledge patterns
+// - Edit   → EditEvent entity
+// - Bash   → ExecutionEvent entity + git commit detection + error detection
+// - Read   → touch for importance (no new entities)
+
+import { extractTrackA } from "@/capture/track-a-ast";
+import type { SiaDb } from "@/graph/db-interface";
+import { insertEntity } from "@/graph/entities";
+import { detectCommitPatterns, detectKnowledgePatterns } from "@/hooks/extractors/pattern-detector";
+import type { HookEvent, HookHandler, HookResponse } from "@/hooks/types";
+
+/** Extract the basename from a file path. */
+function basename(filePath: string): string {
+	const idx = filePath.lastIndexOf("/");
+	return idx === -1 ? filePath : filePath.slice(idx + 1);
+}
+
+/** Safely read a string field from tool_input. */
+function inputStr(event: HookEvent, key: string): string | undefined {
+	const val = event.tool_input?.[key];
+	return typeof val === "string" ? val : undefined;
+}
+
+/** Safely read tool_response as a string. */
+function responseStr(event: HookEvent): string {
+	if (typeof event.tool_response === "string") return event.tool_response;
+	if (event.tool_response != null) return String(event.tool_response);
+	return "";
+}
+
+// ---------------------------------------------------------------------------
+// Test failure parser
+// ---------------------------------------------------------------------------
+
+/** A structured test failure parsed from test runner output. */
+export interface TestFailure {
+	testName: string;
+	testFile: string;
+	errorMessage: string;
+	sourceFile?: string;
+	sourceLine?: number;
+}
+
+const TEST_COMMAND_RE = /\b(test|vitest|jest|pytest|mocha)\b/;
+
+/**
+ * Parse structured test failures from test runner output.
+ * Supports vitest/jest and pytest output formats.
+ */
+export function parseTestFailures(output: string, command: string): TestFailure[] {
+	if (!TEST_COMMAND_RE.test(command)) return [];
+
+	const failures: TestFailure[] = [];
+
+	// --- Vitest/Jest format ---
+	// Matches: ❯ path/to/test.ts (N tests | M failed)
+	// Then:    × test name
+	//          → ErrorType: message
+	//          ❯ source.ts:line:col
+	const vitestBlockRe = /❯\s+(\S+\.(?:test|spec)\.\S+)\s+\([^)]*failed[^)]*\)/g;
+	let blockMatch: RegExpExecArray | null = vitestBlockRe.exec(output);
+	while (blockMatch !== null) {
+		const testFile = blockMatch[1];
+		// Find the region of this test file block
+		const blockStart = blockMatch.index + blockMatch[0].length;
+		const nextBlock = output.indexOf("\n ❯ ", blockStart);
+		const blockEnd = nextBlock === -1 ? output.length : nextBlock;
+		const blockText = output.slice(blockStart, blockEnd);
+
+		// Find individual failed tests: × test name
+		const failRe = /×\s+(.+)/g;
+		let failMatch: RegExpExecArray | null = failRe.exec(blockText);
+		while (failMatch !== null) {
+			const testName = failMatch[1].trim();
+			// Look for error message after the test name (→ ErrorType: msg)
+			const afterFail = blockText.slice(failMatch.index + failMatch[0].length);
+			const errorLineMatch = afterFail.match(/→\s+(.+)/);
+			const errorMessage = errorLineMatch ? errorLineMatch[1].trim() : "Test failed";
+
+			// Look for source file in stack trace (❯ path:line:col, skip test files)
+			const stackLines = afterFail.match(/❯\s+(\S+):(\d+):\d+/g) ?? [];
+			let sourceFile: string | undefined;
+			let sourceLine: number | undefined;
+			for (const sl of stackLines) {
+				const m = sl.match(/❯\s+(\S+):(\d+):\d+/);
+				if (m && !m[1].match(/\.(test|spec)\./)) {
+					sourceFile = m[1];
+					sourceLine = Number.parseInt(m[2], 10);
+					break;
+				}
+			}
+
+			failures.push({ testName, testFile, errorMessage, sourceFile, sourceLine });
+			failMatch = failRe.exec(blockText);
+		}
+
+		blockMatch = vitestBlockRe.exec(output);
+	}
+
+	// --- Pytest format ---
+	// FAILED path::test_name - ErrorType: message
+	const pytestRe = /^FAILED\s+(\S+)::(\S+)\s+-\s+(.+)$/gm;
+	let pytestMatch: RegExpExecArray | null = pytestRe.exec(output);
+	while (pytestMatch !== null) {
+		failures.push({
+			testName: pytestMatch[2],
+			testFile: pytestMatch[1],
+			errorMessage: pytestMatch[3].trim(),
+		});
+		pytestMatch = pytestRe.exec(output);
+	}
+
+	return failures;
+}
+
+// ---------------------------------------------------------------------------
+// Tool-specific handlers
+// ---------------------------------------------------------------------------
+
+async function handleWrite(db: SiaDb, event: HookEvent): Promise<HookResponse> {
+	const filePath = inputStr(event, "file_path");
+	const content = inputStr(event, "content");
+
+	if (!filePath || !content) {
+		return { status: "skipped", nodes_created: 0 };
+	}
+
+	let nodesCreated = 0;
+
+	// 1. Insert a FileNode entity for the written file
+	await insertEntity(db, {
+		type: "FileNode",
+		name: basename(filePath),
+		content: content.slice(0, 2000),
+		summary: `File written: ${filePath}`,
+		file_paths: JSON.stringify([filePath]),
+		extraction_method: "hook:post-tool-use:write",
+		source_episode: event.session_id,
+	});
+	nodesCreated++;
+
+	// 2. Extract structural code entities via TrackA
+	const trackAFacts = extractTrackA(content, filePath);
+	for (const fact of trackAFacts) {
+		await insertEntity(db, {
+			type: fact.type,
+			name: fact.name,
+			content: fact.content,
+			summary: fact.summary,
+			tags: JSON.stringify(fact.tags),
+			file_paths: JSON.stringify(fact.file_paths),
+			trust_tier: fact.trust_tier,
+			confidence: fact.confidence,
+			extraction_method: "hook:post-tool-use:track-a",
+			source_episode: event.session_id,
+		});
+		nodesCreated++;
+	}
+
+	// 3. Detect knowledge patterns in the content
+	const patterns = detectKnowledgePatterns(content);
+	for (const p of patterns) {
+		await insertEntity(db, {
+			type: p.type,
+			name: `${p.type}: ${p.content.slice(0, 60)}`,
+			content: p.content,
+			summary: `${p.type} detected in ${basename(filePath)}`,
+			confidence: p.confidence,
+			file_paths: JSON.stringify([filePath]),
+			extraction_method: "hook:post-tool-use:pattern",
+			source_episode: event.session_id,
+		});
+		nodesCreated++;
+	}
+
+	return { status: "processed", nodes_created: nodesCreated };
+}
+
+async function handleEdit(db: SiaDb, event: HookEvent): Promise<HookResponse> {
+	const filePath = inputStr(event, "file_path");
+	const oldStr = inputStr(event, "old_string");
+	const newStr = inputStr(event, "new_string");
+
+	if (!filePath) {
+		return { status: "skipped", nodes_created: 0 };
+	}
+
+	let nodesCreated = 0;
+
+	const editContent = oldStr && newStr ? `--- ${oldStr}\n+++ ${newStr}` : "edit";
+
+	// 1. Always create the EditEvent entity (existing behavior)
+	await insertEntity(db, {
+		type: "CodeEntity",
+		name: `Edit: ${basename(filePath)}`,
+		content: editContent.slice(0, 2000),
+		summary: `Edit in ${filePath}`,
+		file_paths: JSON.stringify([filePath]),
+		extraction_method: "hook:post-tool-use:edit",
+		source_episode: event.session_id,
+		kind: "EditEvent",
+	});
+	nodesCreated++;
+
+	// 2. Extract structural code entities from new_string via TrackA (best-effort)
+	if (newStr) {
+		try {
+			const trackAFacts = extractTrackA(newStr, filePath);
+			for (const fact of trackAFacts) {
+				await insertEntity(db, {
+					type: fact.type,
+					name: fact.name,
+					content: fact.content,
+					summary: fact.summary,
+					tags: JSON.stringify(fact.tags),
+					file_paths: JSON.stringify(fact.file_paths),
+					trust_tier: fact.trust_tier,
+					confidence: fact.confidence,
+					extraction_method: "hook:post-tool-use:track-a",
+					source_episode: event.session_id,
+				});
+				nodesCreated++;
+			}
+		} catch {
+			// Best-effort — don't block EditEvent creation
+		}
+
+		// 3. Detect knowledge patterns in new_string (best-effort)
+		try {
+			const patterns = detectKnowledgePatterns(newStr);
+			for (const p of patterns) {
+				await insertEntity(db, {
+					type: p.type,
+					name: `${p.type}: ${p.content.slice(0, 60)}`,
+					content: p.content,
+					summary: `${p.type} detected in ${basename(filePath)}`,
+					confidence: p.confidence,
+					file_paths: JSON.stringify([filePath]),
+					extraction_method: "hook:post-tool-use:pattern",
+					source_episode: event.session_id,
+				});
+				nodesCreated++;
+			}
+		} catch {
+			// Best-effort — don't block EditEvent creation
+		}
+	}
+
+	return { status: "processed", nodes_created: nodesCreated };
+}
+
+async function handleBash(db: SiaDb, event: HookEvent): Promise<HookResponse> {
+	const command = inputStr(event, "command") ?? "";
+	const output = responseStr(event);
+
+	let nodesCreated = 0;
+
+	// Always create an ExecutionEvent for the command
+	await insertEntity(db, {
+		type: "CodeEntity",
+		name: `Bash: ${command.slice(0, 80)}`,
+		content: `$ ${command}\n${output.slice(0, 2000)}`,
+		summary: `Executed: ${command.slice(0, 120)}`,
+		extraction_method: "hook:post-tool-use:bash",
+		source_episode: event.session_id,
+		kind: "ExecutionEvent",
+	});
+	nodesCreated++;
+
+	// Detect git commit messages
+	const commitMatch = command.match(/git\s+commit\s+.*-m\s+["'](.+?)["']/);
+	if (commitMatch) {
+		const commitMsg = commitMatch[1];
+		const commitPatterns = detectCommitPatterns(commitMsg);
+		for (const p of commitPatterns) {
+			await insertEntity(db, {
+				type: p.type,
+				name: `${p.type}: ${commitMsg.slice(0, 60)}`,
+				content: commitMsg,
+				summary: `Commit: ${commitMsg.slice(0, 120)}`,
+				confidence: p.confidence,
+				extraction_method: "hook:post-tool-use:commit",
+				source_episode: event.session_id,
+			});
+			nodesCreated++;
+		}
+	}
+
+	// Detect structured test failures from test runner output
+	const testFailures = parseTestFailures(output, command);
+	for (const failure of testFailures) {
+		const filePaths = [failure.testFile];
+		if (failure.sourceFile) filePaths.push(failure.sourceFile);
+
+		const content = [
+			`Test: ${failure.testName}`,
+			`File: ${failure.testFile}`,
+			`Error: ${failure.errorMessage}`,
+			failure.sourceFile ? `Source: ${failure.sourceFile}:${failure.sourceLine ?? "?"}` : null,
+		]
+			.filter(Boolean)
+			.join("\n");
+
+		await insertEntity(db, {
+			type: "Bug",
+			name: `${failure.testName}: ${failure.errorMessage.slice(0, 60)}`,
+			content,
+			summary: `Test failure in ${failure.testFile}: ${failure.testName}`,
+			trust_tier: 2,
+			confidence: 0.95,
+			file_paths: JSON.stringify(filePaths),
+			extraction_method: "hook:post-tool-use:test-runner",
+			source_episode: event.session_id,
+			kind: "Bug",
+		});
+		nodesCreated++;
+	}
+
+	// Detect errors in output (skip if structured test failures were found)
+	if (testFailures.length === 0) {
+		const hasError =
+			/\bError\b/i.test(output) ||
+			/\bfailed\b/i.test(output) ||
+			/\bFATAL\b/.test(output) ||
+			/\bpanic\b/i.test(output);
+
+		if (hasError && !commitMatch) {
+			await insertEntity(db, {
+				type: "Bug",
+				name: `Error: ${command.slice(0, 60)}`,
+				content: output.slice(0, 2000),
+				summary: `Error detected running: ${command.slice(0, 100)}`,
+				confidence: 0.7,
+				extraction_method: "hook:post-tool-use:error",
+				source_episode: event.session_id,
+			});
+			nodesCreated++;
+		}
+	}
+
+	return { status: "processed", nodes_created: nodesCreated };
+}
+
+async function handleRead(db: SiaDb, event: HookEvent): Promise<HookResponse> {
+	const filePath = inputStr(event, "file_path");
+	if (!filePath) {
+		return { status: "processed", nodes_created: 0, context: [] };
+	}
+
+	const result = await db.execute(
+		`SELECT id, type, name, summary, kind, trust_tier, confidence
+		 FROM graph_nodes
+		 WHERE file_paths LIKE ?
+		   AND t_valid_until IS NULL
+		   AND archived_at IS NULL
+		 ORDER BY importance DESC
+		 LIMIT 5`,
+		[`%${filePath}%`],
+	);
+
+	const context = (result.rows as Array<Record<string, unknown>>).map((row) => ({
+		id: row.id,
+		type: row.type,
+		name: row.name,
+		summary: row.summary,
+		kind: row.kind,
+		trust_tier: row.trust_tier,
+		confidence: row.confidence,
+	}));
+
+	return { status: "processed", nodes_created: 0, context };
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a PostToolUse hook handler bound to the given graph database.
+ */
+export function createPostToolUseHandler(db: SiaDb): HookHandler {
+	return async (event: HookEvent): Promise<HookResponse> => {
+		if (!event.tool_name || !event.tool_input) {
+			return { status: "skipped", nodes_created: 0 };
+		}
+
+		switch (event.tool_name) {
+			case "Write":
+				return handleWrite(db, event);
+			case "Edit":
+				return handleEdit(db, event);
+			case "Bash":
+				return handleBash(db, event);
+			case "Read":
+				return handleRead(db, event);
+			default:
+				return { status: "skipped", nodes_created: 0 };
+		}
+	};
+}

package/src/hooks/handlers/pre-compact.ts

@@ -0,0 +1,100 @@
+// Module: pre-compact — PreCompact hook handler
+//
+// Fires before Claude Code compacts the context window. Reads the transcript
+// for any remaining unextracted knowledge (using pattern detection), then
+// creates a session snapshot in memory before the compaction discards detail.
+//
+// Returns { status: "processed", snapshot_nodes: N } where N is the count
+// of patterns captured from the pre-compaction transcript scan.
+
+import { readFileSync } from "node:fs";
+import type { SiaDb } from "@/graph/db-interface";
+import { insertEntity } from "@/graph/entities";
+import { detectKnowledgePatterns } from "@/hooks/extractors/pattern-detector";
+import type { HookEvent, HookResponse } from "@/hooks/types";
+
+/** How many lines from the tail of the transcript to scan before compaction. */
+const COMPACT_SEGMENT_SIZE = 100;
+
+/** Shape of a single JSONL transcript line. */
+interface TranscriptLine {
+	role?: string;
+	content?: string;
+	tool_calls?: Array<{ name?: string; input?: Record<string, unknown> }>;
+}
+
+/**
+ * Read and parse recent lines from a JSONL transcript file.
+ */
+function readTranscriptLines(path: string): TranscriptLine[] {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf-8");
+	} catch {
+		return [];
+	}
+
+	const allLines = raw.split("\n").filter((l) => l.trim().length > 0);
+	const recentLines = allLines.slice(-COMPACT_SEGMENT_SIZE);
+
+	const parsed: TranscriptLine[] = [];
+	for (const line of recentLines) {
+		try {
+			parsed.push(JSON.parse(line) as TranscriptLine);
+		} catch {
+			// Skip malformed lines
+		}
+	}
+
+	return parsed;
+}
+
+/**
+ * Collect assistant message content strings from transcript lines.
+ */
+function collectAssistantContent(lines: TranscriptLine[]): string[] {
+	const contents: string[] = [];
+	for (const line of lines) {
+		if (line.role === "assistant" && typeof line.content === "string") {
+			contents.push(line.content);
+		}
+	}
+	return contents;
+}
+
+/**
+ * Create a PreCompact hook handler bound to the given graph database.
+ *
+ * Scans the transcript tail for uncaptured knowledge patterns before
+ * the context window is compacted, ensuring no knowledge is lost.
+ */
+export function createPreCompactHandler(db: SiaDb): (event: HookEvent) => Promise<HookResponse> {
+	return async (event: HookEvent): Promise<HookResponse> => {
+		const lines = readTranscriptLines(event.transcript_path);
+
+		if (lines.length === 0) {
+			return { status: "processed", snapshot_nodes: 0 };
+		}
+
+		const assistantContents = collectAssistantContent(lines);
+		let snapshotNodes = 0;
+
+		for (const content of assistantContents) {
+			const patterns = detectKnowledgePatterns(content);
+			for (const p of patterns) {
+				await insertEntity(db, {
+					type: p.type,
+					name: `${p.type}: ${p.content.slice(0, 60)}`,
+					content: p.content,
+					summary: `${p.type} captured pre-compaction in session ${event.session_id}`,
+					confidence: p.confidence,
+					extraction_method: "hook:pre-compact:pattern",
+					source_episode: event.session_id,
+				});
+				snapshotNodes++;
+			}
+		}
+
+		return { status: "processed", snapshot_nodes: snapshotNodes };
+	};
+}

package/src/hooks/handlers/session-end.ts

@@ -0,0 +1,47 @@
+// Module: session-end — SessionEnd hook handler
+//
+// Fires when a Claude Code session ends (exit, sigint, or error).
+// Records session statistics and can update the session entity's
+// ended_at timestamp in the graph.
+//
+// Returns { status: "processed", nodes_this_session: N } where N is
+// the count of entities created during this session.
+
+import type { SiaDb } from "@/graph/db-interface";
+import type { HookEvent, HookResponse } from "@/hooks/types";
+
+/**
+ * Count the number of entities created during a given session.
+ * Looks up all entities whose source_episode matches the session_id.
+ */
+async function countSessionEntities(db: SiaDb, sessionId: string): Promise<number> {
+	const result = await db.execute(
+		"SELECT COUNT(*) as count FROM graph_nodes WHERE source_episode = ?",
+		[sessionId],
+	);
+
+	const row = result.rows[0];
+	if (!row) return 0;
+
+	const count = row.count as number | bigint;
+	return typeof count === "bigint" ? Number(count) : (count ?? 0);
+}
+
+/**
+ * Create a SessionEnd hook handler bound to the given graph database.
+ *
+ * On session end:
+ * 1. Counts all entities created during this session (via source_episode).
+ * 2. Returns session statistics for observability.
+ */
+export function createSessionEndHandler(db: SiaDb): (event: HookEvent) => Promise<HookResponse> {
+	return async (event: HookEvent): Promise<HookResponse> => {
+		const sessionId = event.session_id;
+		const nodesThisSession = await countSessionEntities(db, sessionId);
+
+		return {
+			status: "processed",
+			nodes_this_session: nodesThisSession,
+		};
+	};
+}

package/src/hooks/handlers/session-start.ts

@@ -0,0 +1,154 @@
+// Module: session-start — SessionStart command hook handler
+//
+// Fires when Claude Code starts a new session (or resumes an existing one).
+// This handler runs as a command hook — it writes context to stdout, which
+// Claude Code injects into the initial system prompt.
+//
+// Queries the graph for:
+//   - Recent Decisions (limit 5) — architectural choices made in prior sessions
+//   - All active Conventions — coding patterns the team follows
+//   - Unresolved Bugs/ErrorEvents (limit 3) — known issues to watch out for
+
+import type { SiaDb } from "@/graph/db-interface";
+import type { HookEvent } from "@/hooks/types";
+
+/** A single item summarised for session context injection. */
+export interface ContextItem {
+	name: string;
+	summary: string;
+}
+
+/** The structured context gathered at session start. */
+export interface SessionContext {
+	decisions: Array<ContextItem>;
+	conventions: Array<ContextItem>;
+	errors: Array<ContextItem>;
+	resuming: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Query active entities of a given type from the graph database.
+ * Returns rows mapped to { name, summary } pairs.
+ */
+async function queryByType(db: SiaDb, type: string, limit?: number): Promise<Array<ContextItem>> {
+	const sql = limit
+		? "SELECT name, summary FROM graph_nodes WHERE type = ? AND t_valid_until IS NULL AND archived_at IS NULL ORDER BY created_at DESC LIMIT ?"
+		: "SELECT name, summary FROM graph_nodes WHERE type = ? AND t_valid_until IS NULL AND archived_at IS NULL ORDER BY created_at DESC";
+
+	const params: unknown[] = limit ? [type, limit] : [type];
+	const result = await db.execute(sql, params);
+
+	return result.rows.map((row) => ({
+		name: (row.name as string) ?? "",
+		summary: (row.summary as string) ?? "",
+	}));
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Query the graph for relevant context and format for injection.
+ *
+ * - Decisions: most recent 5 (architectural choices)
+ * - Conventions: all active (coding patterns)
+ * - Errors: most recent 3 unresolved Bugs / ErrorEvents
+ */
+export async function buildSessionContext(
+	db: SiaDb,
+	_cwd: string,
+	isResume: boolean,
+): Promise<SessionContext> {
+	const [decisions, conventions, bugs, errorEvents] = await Promise.all([
+		queryByType(db, "Decision", 5),
+		queryByType(db, "Convention"),
+		queryByType(db, "Bug", 3),
+		queryByType(db, "ErrorEvent", 3),
+	]);
+
+	// Merge bugs and error events, keeping only 3 total
+	const errors = [...bugs, ...errorEvents].slice(0, 3);
+
+	return {
+		decisions,
+		conventions,
+		errors,
+		resuming: isResume,
+	};
+}
+
+/**
+ * Format the context as a concise markdown block for stdout output.
+ * Claude Code injects this as context at the top of the session.
+ */
+export function formatSessionContext(context: SessionContext): string {
+	const lines: string[] = [];
+
+	const header = context.resuming
+		? "## Sia — Resuming Session Context"
+		: "## Sia — Session Knowledge Context";
+
+	lines.push(header);
+	lines.push("");
+
+	if (context.decisions.length > 0) {
+		lines.push("### Recent Decisions");
+		for (const d of context.decisions) {
+			lines.push(`- **${d.name}**: ${d.summary}`);
+		}
+		lines.push("");
+	}
+
+	if (context.conventions.length > 0) {
+		lines.push("### Active Conventions");
+		for (const c of context.conventions) {
+			lines.push(`- **${c.name}**: ${c.summary}`);
+		}
+		lines.push("");
+	}
+
+	if (context.errors.length > 0) {
+		lines.push("### Known Issues");
+		for (const e of context.errors) {
+			lines.push(`- **${e.name}**: ${e.summary}`);
+		}
+		lines.push("");
+	}
+
+	if (
+		context.decisions.length === 0 &&
+		context.conventions.length === 0 &&
+		context.errors.length === 0
+	) {
+		lines.push("_No prior session knowledge found for this repository._");
+		lines.push("");
+	}
+
+	// Lightweight nudge — CLAUDE.md has the full behavioral spec
+	lines.push("---");
+	lines.push("Sia memory tools are active. See CLAUDE.md for tool selection guidance.");
+	lines.push("");
+
+	return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Main entry point for the `sia hook session-start` command.
+ * Reads hook event JSON from stdin, builds context, and writes to stdout.
+ * Claude Code reads the stdout output and injects it into the session.
+ */
+export async function runSessionStartHook(db: SiaDb, event: HookEvent): Promise<void> {
+	const isResume = event.source === "resume";
+	const context = await buildSessionContext(db, event.cwd, isResume);
+	const formatted = formatSessionContext(context);
+	process.stdout.write(formatted);
+}