@rkarim08/sia 1.0.0

package/src/mcp/tools/sia-ast-query.ts

@@ -0,0 +1,225 @@
+// Module: sia-ast-query — MCP tool handler for tree-sitter AST queries
+//
+// Parses a file with tree-sitter and runs a query (symbols, imports, calls)
+// against the AST. Returns structured results with bounded output.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getLanguageForFile, resolveLanguageConfig } from "@/ast/languages";
+import { TreeSitterService } from "@/ast/tree-sitter/service";
+import type { SiaQueryMatch } from "@/ast/tree-sitter/types";
+import type { TreeSitterConfig } from "@/shared/config";
+
+export interface SiaAstQueryInput {
+	file_path: string;
+	query_type: "symbols" | "imports" | "calls";
+	max_results?: number;
+}
+
+export interface AstSymbol {
+	name: string;
+	kind: string;
+	line: number;
+}
+
+export interface SiaAstQueryResult {
+	file_path: string;
+	language?: string;
+	symbols?: AstSymbol[];
+	imports?: string[];
+	calls?: string[];
+	error?: string;
+}
+
+const MAX_RESULTS = 100;
+// Resolve grammars relative to the package root, not process.cwd()
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const GRAMMARS_DIR = join(__dirname, "../../..", "grammars", "queries");
+
+const DEFAULT_TS_CONFIG: TreeSitterConfig = {
+	enabled: true,
+	preferNative: true,
+	parseTimeoutMs: 5000,
+	maxCachedTrees: 50,
+	wasmDir: "",
+	queryDir: "",
+};
+
+// Singleton service — avoids re-initialization on every call
+let serviceInstance: TreeSitterService | null = null;
+
+async function getService(): Promise<TreeSitterService> {
+	if (!serviceInstance) {
+		serviceInstance = new TreeSitterService(DEFAULT_TS_CONFIG);
+		await serviceInstance.initialize();
+	}
+	return serviceInstance;
+}
+
+/** Dispose the singleton service and allow re-initialization on next call. */
+export function resetAstQueryService(): void {
+	if (serviceInstance) {
+		serviceInstance.dispose();
+		serviceInstance = null;
+	}
+}
+
+/**
+ * Extract symbols from query matches. Symbols have @name and @kind captures.
+ */
+export function extractSymbols(matches: SiaQueryMatch[], maxResults: number): AstSymbol[] {
+	const symbols: AstSymbol[] = [];
+	for (const match of matches) {
+		if (symbols.length >= maxResults) break;
+
+		let name = "";
+		let kind = "";
+		let line = 0;
+
+		for (const cap of match.captures) {
+			if (cap.name === "name") {
+				name = cap.text;
+				line = cap.startPosition.row + 1;
+			} else if (cap.name === "kind" || cap.name === "definition") {
+				kind = cap.text;
+				line = line || cap.startPosition.row + 1;
+			}
+		}
+
+		// Fall back to the first capture if no @name
+		if (!name && match.captures.length > 0) {
+			const first = match.captures[0];
+			name = first.text;
+			line = first.startPosition.row + 1;
+			kind = first.name;
+		}
+
+		if (name) {
+			symbols.push({ name, kind, line });
+		}
+	}
+	return symbols;
+}
+
+/**
+ * Extract import paths from query matches. Imports have @source captures.
+ */
+export function extractImports(matches: SiaQueryMatch[], maxResults: number): string[] {
+	const imports: string[] = [];
+	for (const match of matches) {
+		if (imports.length >= maxResults) break;
+
+		for (const cap of match.captures) {
+			if (cap.name === "source" || cap.name === "path" || cap.name === "import") {
+				// Strip quotes from import paths
+				const cleaned = cap.text.replace(/^["']|["']$/g, "");
+				if (cleaned && !imports.includes(cleaned)) {
+					imports.push(cleaned);
+				}
+			}
+		}
+	}
+	return imports;
+}
+
+/**
+ * Extract call targets from query matches.
+ */
+export function extractCalls(matches: SiaQueryMatch[], maxResults: number): string[] {
+	const calls: string[] = [];
+	for (const match of matches) {
+		if (calls.length >= maxResults) break;
+
+		for (const cap of match.captures) {
+			if (cap.name === "name" || cap.name === "call" || cap.name === "function") {
+				if (cap.text && !calls.includes(cap.text)) {
+					calls.push(cap.text);
+				}
+			}
+		}
+	}
+	return calls;
+}
+
+/**
+ * Parse a file with tree-sitter and extract structured AST data.
+ */
+export async function handleSiaAstQuery(input: SiaAstQueryInput): Promise<SiaAstQueryResult> {
+	const cwd = process.cwd();
+	const filePath = resolve(cwd, input.file_path);
+	const maxResults = input.max_results ?? MAX_RESULTS;
+
+	// Prevent path traversal outside the project directory
+	if (!filePath.startsWith(`${cwd}/`) && filePath !== cwd) {
+		return { file_path: input.file_path, error: "Path must be within the project directory" };
+	}
+
+	if (!existsSync(filePath)) {
+		return { file_path: input.file_path, error: `File not found: ${input.file_path}` };
+	}
+
+	const langConfig = getLanguageForFile(input.file_path);
+	if (!langConfig) {
+		return { file_path: input.file_path, error: `Unsupported language for: ${input.file_path}` };
+	}
+
+	// Check that the query file exists for this language + query type
+	const resolved = resolveLanguageConfig(langConfig);
+	const queryPath = join(GRAMMARS_DIR, resolved.queryDir, `${input.query_type}.scm`);
+	if (!existsSync(queryPath)) {
+		return {
+			file_path: input.file_path,
+			language: langConfig.name,
+			error: `No ${input.query_type} query available for ${langConfig.name}`,
+		};
+	}
+
+	try {
+		const service = await getService();
+		if (service.backend === "unavailable") {
+			return {
+				file_path: input.file_path,
+				language: langConfig.name,
+				error: "Tree-sitter not available (neither native nor WASM backend loaded)",
+			};
+		}
+
+		const source = readFileSync(filePath, "utf-8");
+		const tree = await service.parse(source, langConfig.name);
+		if (!tree) {
+			return {
+				file_path: input.file_path,
+				language: langConfig.name,
+				error: `Failed to parse ${input.file_path}`,
+			};
+		}
+
+		const matches = service.query(tree, queryPath);
+
+		const result: SiaAstQueryResult = {
+			file_path: input.file_path,
+			language: langConfig.name,
+		};
+
+		switch (input.query_type) {
+			case "symbols":
+				result.symbols = extractSymbols(matches, maxResults);
+				break;
+			case "imports":
+				result.imports = extractImports(matches, maxResults);
+				break;
+			case "calls":
+				result.calls = extractCalls(matches, maxResults);
+				break;
+		}
+
+		return result;
+	} catch (err) {
+		return {
+			file_path: input.file_path,
+			language: langConfig.name,
+			error: `AST parse error: ${err instanceof Error ? err.message : String(err)}`,
+		};
+	}
+}

package/src/mcp/tools/sia-at-time.ts

@@ -0,0 +1,151 @@
+// Module: sia-at-time — Bi-temporal query: entities and edges as-of a point in time
+
+import type { z } from "zod";
+import type { SiaDb } from "@/graph/db-interface";
+import type { EdgeRow } from "@/graph/edges";
+import type { Entity } from "@/graph/entities";
+import type { SiaAtTimeInput as SiaAtTimeInputSchema } from "@/mcp/server";
+
+export type SiaAtTimeInput = z.infer<typeof SiaAtTimeInputSchema>;
+
+export interface SiaTemporalResult {
+	entities: Entity[];
+	invalidated_entities: Entity[];
+	invalidated_count: number;
+	edges: EdgeRow[];
+	edge_count: number;
+}
+
+/**
+ * Parse an `as_of` string into Unix milliseconds.
+ *
+ * Supports:
+ * - ISO 8601 strings (anything `new Date()` can parse)
+ * - Relative strings like "7 days ago", "3 months ago", "1 year ago"
+ */
+export function parseAsOf(asOf: string): number {
+	const relativePattern = /^(\d+)\s+(days?|weeks?|months?|years?)\s+ago$/i;
+	const match = asOf.trim().match(relativePattern);
+
+	if (match) {
+		const amount = Number.parseInt(match[1], 10);
+		const unit = match[2].toLowerCase().replace(/s$/, "");
+		const now = Date.now();
+
+		switch (unit) {
+			case "day":
+				return now - amount * 24 * 60 * 60 * 1000;
+			case "week":
+				return now - amount * 7 * 24 * 60 * 60 * 1000;
+			case "month":
+				return now - amount * 30 * 24 * 60 * 60 * 1000;
+			case "year":
+				return now - amount * 365 * 24 * 60 * 60 * 1000;
+			default:
+				throw new Error(`Unknown relative time unit: ${unit}`);
+		}
+	}
+
+	const parsed = new Date(asOf).getTime();
+	if (Number.isNaN(parsed)) {
+		throw new Error(`Cannot parse as_of timestamp: ${asOf}`);
+	}
+	return parsed;
+}
+
+/**
+ * Query the knowledge graph at a specific point in time.
+ *
+ * Returns entities that were active at `as_of`, entities that had been
+ * invalidated by that time, and edges that were active at that time.
+ */
+export async function handleSiaAtTime(
+	db: SiaDb,
+	input: SiaAtTimeInput,
+): Promise<SiaTemporalResult> {
+	const asOfMs = parseAsOf(input.as_of);
+	const rawLimit = input.limit ?? 20;
+	const limit = Math.min(Math.max(rawLimit, 1), 50);
+
+	// --- Build WHERE filters for entity_types and tags ---
+	const entityFilters: string[] = [];
+	const entityParams: unknown[] = [];
+
+	if (input.entity_types && input.entity_types.length > 0) {
+		const placeholders = input.entity_types.map(() => "?").join(", ");
+		entityFilters.push(`type IN (${placeholders})`);
+		entityParams.push(...input.entity_types);
+	}
+
+	if (input.tags && input.tags.length > 0) {
+		// Match any entity whose JSON tags array contains at least one of the requested tags.
+		// tags is stored as a JSON string array, e.g. '["auth","api"]'.
+		const tagClauses = input.tags.map(() => "tags LIKE ?");
+		entityFilters.push(`(${tagClauses.join(" OR ")})`);
+		for (const tag of input.tags) {
+			entityParams.push(`%${tag}%`);
+		}
+	}
+
+	const extraWhere = entityFilters.length > 0 ? ` AND ${entityFilters.join(" AND ")}` : "";
+
+	// --- Active entities at as_of ---
+	const activeQuery = `
+		SELECT * FROM graph_nodes
+		WHERE (t_valid_from IS NULL OR t_valid_from <= ?)
+		  AND (t_valid_until IS NULL OR t_valid_until > ?)
+		  AND archived_at IS NULL
+		  ${extraWhere}
+		LIMIT ?
+	`;
+	const activeParams = [asOfMs, asOfMs, ...entityParams, limit];
+	const activeResult = await db.execute(activeQuery, activeParams);
+	const entities = activeResult.rows as unknown as Entity[];
+
+	// --- Invalidated entities: those whose t_valid_until <= as_of ---
+	const invalidatedCountQuery = `
+		SELECT COUNT(*) AS cnt FROM graph_nodes
+		WHERE t_valid_until IS NOT NULL AND t_valid_until <= ?
+		  ${extraWhere}
+	`;
+	const invalidatedCountParams = [asOfMs, ...entityParams];
+	const countResult = await db.execute(invalidatedCountQuery, invalidatedCountParams);
+	const invalidatedCount = (countResult.rows[0] as { cnt: number }).cnt;
+
+	const invalidatedQuery = `
+		SELECT * FROM graph_nodes
+		WHERE t_valid_until IS NOT NULL AND t_valid_until <= ?
+		  ${extraWhere}
+		ORDER BY t_valid_until DESC
+		LIMIT ?
+	`;
+	const invalidatedParams = [asOfMs, ...entityParams, limit];
+	const invalidatedResult = await db.execute(invalidatedQuery, invalidatedParams);
+	const invalidatedEntities = invalidatedResult.rows as unknown as Entity[];
+
+	// --- Edges active at as_of (global, not per-entity), capped at 50 ---
+	const edgesCountQuery = `
+		SELECT COUNT(*) AS cnt FROM graph_edges
+		WHERE (t_valid_from IS NULL OR t_valid_from <= ?)
+		  AND (t_valid_until IS NULL OR t_valid_until > ?)
+	`;
+	const edgesCountResult = await db.execute(edgesCountQuery, [asOfMs, asOfMs]);
+	const edgeCount = (edgesCountResult.rows[0] as { cnt: number }).cnt;
+
+	const edgesQuery = `
+		SELECT * FROM graph_edges
+		WHERE (t_valid_from IS NULL OR t_valid_from <= ?)
+		  AND (t_valid_until IS NULL OR t_valid_until > ?)
+		LIMIT 50
+	`;
+	const edgesResult = await db.execute(edgesQuery, [asOfMs, asOfMs]);
+	const edges = edgesResult.rows as unknown as EdgeRow[];
+
+	return {
+		entities,
+		invalidated_entities: invalidatedEntities,
+		invalidated_count: invalidatedCount,
+		edges,
+		edge_count: edgeCount,
+	};
+}

package/src/mcp/tools/sia-backlinks.ts

@@ -0,0 +1,87 @@
+// Module: sia-backlinks — Backlink traversal for knowledge graph nodes
+
+import type { SiaDb } from "@/graph/db-interface";
+
+export interface SiaBacklinksInput {
+	node_id: string;
+	edge_types?: string[];
+}
+
+export interface BacklinkEntry {
+	id: string;
+	type: string;
+	name: string;
+	summary: string;
+	importance: number;
+	edge_type: string;
+}
+
+export interface SiaBacklinksResult {
+	target_id: string;
+	backlinks: Record<string, BacklinkEntry[]>; // grouped by edge_type
+	total_count: number;
+}
+
+/**
+ * Find all active incoming edges to a given node, grouped by edge type.
+ * Returns entities that reference the target node via active edges.
+ *
+ * Only considers edges where t_valid_until IS NULL (active edges) and
+ * source entities that are neither invalidated nor archived.
+ */
+export async function handleSiaBacklinks(
+	db: SiaDb,
+	input: SiaBacklinksInput,
+): Promise<SiaBacklinksResult> {
+	const params: unknown[] = [input.node_id];
+
+	let edgeTypeFilter = "";
+	if (input.edge_types && input.edge_types.length > 0) {
+		const placeholders = input.edge_types.map(() => "?").join(", ");
+		edgeTypeFilter = `AND e.type IN (${placeholders})`;
+		params.push(...input.edge_types);
+	}
+
+	const sql = `
+		SELECT
+			e.type AS edge_type,
+			ent.id, ent.type, ent.name, ent.summary, ent.importance
+		FROM graph_edges e
+		JOIN graph_nodes ent ON ent.id = e.from_id
+		WHERE e.to_id = ?
+			AND e.t_valid_until IS NULL
+			AND ent.t_valid_until IS NULL
+			AND ent.archived_at IS NULL
+			${edgeTypeFilter}
+		ORDER BY e.type, ent.importance DESC
+	`;
+
+	const result = await db.execute(sql, params);
+
+	const backlinks: Record<string, BacklinkEntry[]> = {};
+	let totalCount = 0;
+
+	for (const row of result.rows) {
+		const edgeType = row.edge_type as string;
+		const entry: BacklinkEntry = {
+			id: row.id as string,
+			type: row.type as string,
+			name: row.name as string,
+			summary: row.summary as string,
+			importance: row.importance as number,
+			edge_type: edgeType,
+		};
+
+		if (!backlinks[edgeType]) {
+			backlinks[edgeType] = [];
+		}
+		backlinks[edgeType].push(entry);
+		totalCount++;
+	}
+
+	return {
+		target_id: input.node_id,
+		backlinks,
+		total_count: totalCount,
+	};
+}

package/src/mcp/tools/sia-batch-execute.ts

@@ -0,0 +1,169 @@
+// Module: sia-batch-execute — Execute multiple operations in one call with precedes edges
+
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import type { Embedder } from "@/capture/embedder";
+import type { SiaDb } from "@/graph/db-interface";
+import { insertEdge } from "@/graph/edges";
+import type { ProgressiveThrottle } from "@/retrieval/throttle";
+import { buildSandboxEnv } from "@/sandbox/credential-pass";
+import { executeSubprocess } from "@/sandbox/executor";
+
+// ---------------------------------------------------------------------------
+// Input / Output types
+// ---------------------------------------------------------------------------
+
+const BatchOperation = z.union([
+	z.object({
+		type: z.literal("execute"),
+		code: z.string(),
+		language: z.string().optional(),
+		timeout: z.number().optional(),
+		env: z.record(z.string(), z.string()).optional(),
+	}),
+	z.object({
+		type: z.literal("search"),
+		query: z.string(),
+	}),
+]);
+
+export const SiaBatchExecuteInput = z.object({
+	operations: z.array(BatchOperation),
+});
+
+export interface OperationResult {
+	index: number;
+	type: string;
+	stdout?: string;
+	stderr?: string;
+	exitCode?: number | null;
+	error?: string;
+}
+
+export interface SiaBatchExecuteResult {
+	results: OperationResult[];
+	eventNodeIds: string[];
+	contextSavings: number;
+	error?: string;
+}
+
+const BATCH_MAX = 20;
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+// ---------------------------------------------------------------------------
+// handleSiaBatchExecute
+// ---------------------------------------------------------------------------
+
+export async function handleSiaBatchExecute(
+	db: SiaDb,
+	input: z.infer<typeof SiaBatchExecuteInput>,
+	_embedder: Embedder,
+	throttle: ProgressiveThrottle,
+	sessionId: string,
+	config?: { timeoutPerOp?: number },
+): Promise<SiaBatchExecuteResult> {
+	const { operations } = input;
+
+	// 1. Enforce batch size cap
+	if (operations.length > BATCH_MAX) {
+		return {
+			results: [],
+			eventNodeIds: [],
+			contextSavings: 0,
+			error: `Batch size ${operations.length} exceeds maximum of ${BATCH_MAX}`,
+		};
+	}
+
+	const timeoutPerOp = config?.timeoutPerOp ?? DEFAULT_TIMEOUT_MS;
+	const results: OperationResult[] = [];
+	const eventNodeIds: string[] = [];
+	const now = Date.now();
+	const nowStr = String(now);
+
+	// 2. Process each operation sequentially
+	for (let i = 0; i < operations.length; i++) {
+		const op = operations[i];
+		let opResult: OperationResult;
+
+		if (op.type === "execute") {
+			// Increment throttle counter for this execute op
+			await throttle.check(sessionId, "sia_execute");
+
+			const env = buildSandboxEnv(op.env);
+			try {
+				const subprocess = await executeSubprocess({
+					language: op.language,
+					code: op.code,
+					timeout: op.timeout ?? timeoutPerOp,
+					env,
+				});
+				opResult = {
+					index: i,
+					type: "execute",
+					stdout: subprocess.stdout,
+					stderr: subprocess.stderr || undefined,
+					exitCode: subprocess.exitCode,
+				};
+			} catch (err) {
+				opResult = {
+					index: i,
+					type: "execute",
+					error: err instanceof Error ? err.message : String(err),
+				};
+			}
+		} else if (op.type === "search") {
+			opResult = {
+				index: i,
+				type: "search",
+				error: "Search not yet wired",
+			};
+		} else {
+			opResult = {
+				index: i,
+				type: (op as { type: string }).type,
+				error: "Invalid operation",
+			};
+		}
+
+		results.push(opResult);
+
+		// 3. Create an EventNode for this operation
+		try {
+			const nodeId = randomUUID();
+			await db.execute(
+				`INSERT INTO graph_nodes (id, type, name, summary, content, trust_tier, confidence, base_confidence, importance, base_importance, access_count, edge_count, tags, file_paths, t_created, t_valid_from, created_by, created_at, last_accessed)
+			 VALUES (?, 'EventNode', ?, ?, ?, 3, 0.8, 0.8, 0.5, 0.5, 0, 0, '[]', '[]', ?, ?, 'sia-batch-execute', ?, ?)`,
+				[
+					nodeId,
+					`batch-op-${sessionId}-${i}`,
+					`Batch operation ${i} (${op.type})`,
+					JSON.stringify(opResult),
+					nowStr,
+					nowStr,
+					nowStr,
+					nowStr,
+				],
+			);
+			eventNodeIds.push(nodeId);
+			if (i > 0 && eventNodeIds[i - 1]) {
+				await insertEdge(db, {
+					from_id: eventNodeIds[i - 1],
+					to_id: nodeId,
+					type: "precedes",
+					weight: 1.0,
+					confidence: 1.0,
+					trust_tier: 3,
+				});
+			}
+		} catch (dbErr) {
+			// Record failed but execution result is still valid
+			console.error("[sia-batch] EventNode creation failed:", (dbErr as Error).message);
+		}
+	}
+
+	return {
+		results,
+		eventNodeIds,
+		contextSavings: 0,
+	};
+}