@rkarim08/sia 1.0.0

package/src/mcp/tools/sia-by-file.ts

@@ -0,0 +1,89 @@
+// Module: sia-by-file — Retrieve knowledge graph entities associated with a file path
+
+import type { z } from "zod";
+import type { SiaDb } from "@/graph/db-interface";
+import type { Entity } from "@/graph/entities";
+import { annotateFreshness } from "@/mcp/freshness-annotator";
+import type { SiaByFileInput } from "@/mcp/server";
+import type { WorkspaceDeps } from "@/mcp/tools/sia-search";
+import { workspaceSearch } from "@/retrieval/workspace-search";
+
+/** Result shape — same as SiaSearchResult (array of entities). */
+export interface SiaByFileResult {
+	entities: Entity[];
+}
+
+/**
+ * Find active entities whose `file_paths` JSON array contains the given file path.
+ *
+ * 1. Exact match on `file_path` using json_each.
+ * 2. If no exact match, fall back to filename stem match (LIKE '%/<stem>%').
+ * 3. Results ordered by importance DESC, capped at `limit` (default 10).
+ */
+export async function handleSiaByFile(
+	db: SiaDb,
+	input: z.infer<typeof SiaByFileInput>,
+	workspaceDeps?: WorkspaceDeps,
+): Promise<SiaByFileResult> {
+	const limit = input.limit ?? 10;
+	const filePath = input.file_path;
+
+	// Workspace-scoped search
+	if (input.workspace && workspaceDeps) {
+		const result = await workspaceSearch({
+			primaryDb: db,
+			metaDb: workspaceDeps.metaDb,
+			bridgeDb: workspaceDeps.bridgeDb,
+			workspaceId: workspaceDeps.workspaceId,
+			primaryRepoId: workspaceDeps.primaryRepoId,
+			query: filePath,
+			siaHome: workspaceDeps.siaHome,
+			limit,
+		});
+		const annotated = await annotateFreshness(
+			result.entities as unknown as Record<string, unknown>[],
+			db,
+		);
+		return { entities: annotated as unknown as Entity[] };
+	}
+
+	// --- Exact match ---
+	const exactResult = await db.execute(
+		`SELECT * FROM graph_nodes
+		 WHERE EXISTS (SELECT 1 FROM json_each(file_paths) WHERE value = ?)
+		   AND t_valid_until IS NULL
+		   AND archived_at IS NULL
+		 ORDER BY importance DESC
+		 LIMIT ?`,
+		[filePath, limit],
+	);
+
+	if (exactResult.rows.length > 0) {
+		const annotated = await annotateFreshness(
+			exactResult.rows as unknown as Record<string, unknown>[],
+			db,
+		);
+		return { entities: annotated as unknown as Entity[] };
+	}
+
+	// --- Filename stem fallback ---
+	// Extract filename from the path (last segment after '/')
+	const parts = filePath.split("/");
+	const filename = parts[parts.length - 1] ?? filePath;
+
+	const stemResult = await db.execute(
+		`SELECT * FROM graph_nodes
+		 WHERE EXISTS (SELECT 1 FROM json_each(file_paths) WHERE value LIKE '%/' || ? || '%')
+		   AND t_valid_until IS NULL
+		   AND archived_at IS NULL
+		 ORDER BY importance DESC
+		 LIMIT ?`,
+		[filename, limit],
+	);
+
+	const annotated = await annotateFreshness(
+		stemResult.rows as unknown as Record<string, unknown>[],
+		db,
+	);
+	return { entities: annotated as unknown as Entity[] };
+}

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

@@ -0,0 +1,113 @@
+// Module: sia-community — Community-level summary retrieval for Phase 3
+//
+// Looks up communities by entity membership, text query (LIKE match),
+// level, and package_path.  Returns up to 3 CommunitySummary objects.
+// Full vector search upgrades arrive in Phase 7.
+
+import type { z } from "zod";
+import type { SiaDb } from "@/graph/db-interface";
+import type { SiaCommunityInput } from "@/mcp/server";
+
+/** Shape returned for each community in sia_community results. */
+export interface CommunitySummary {
+	id: string;
+	level: number;
+	summary: string | null;
+	member_count: number;
+	parent_id: string | null;
+	package_path: string | null;
+}
+
+/** Top-level result envelope for sia_community. */
+export interface SiaCommunityResult {
+	communities: CommunitySummary[];
+	global_unavailable?: boolean;
+}
+
+/** Maximum number of community results returned. */
+const MAX_RESULTS = 3;
+
+/**
+ * Execute the sia_community tool logic.
+ *
+ * Lookup strategies (applied in order of precedence):
+ *  1. `entity_id` — find the community containing that entity via community_members
+ *  2. `query`     — LIKE match against community summary text
+ *  3. Neither     — return all communities (subject to level/package_path filters)
+ *
+ * Additional filters applied on top:
+ *  - `level`        — exact match on community level (0 | 1 | 2)
+ *  - `package_path` — exact match on community package_path
+ *
+ * When the graph has no communities and the total entity count is < 100,
+ * returns `{ communities: [], global_unavailable: true }`.
+ */
+export async function handleSiaCommunity(
+	db: SiaDb,
+	input: z.infer<typeof SiaCommunityInput>,
+): Promise<SiaCommunityResult> {
+	const clauses: string[] = [];
+	const params: unknown[] = [];
+
+	// --- entity_id lookup via community_members join -----------------------
+	if (input.entity_id) {
+		clauses.push("c.id IN (SELECT community_id FROM community_members WHERE entity_id = ?)");
+		params.push(input.entity_id);
+	}
+
+	// --- query: simple LIKE match on summary text --------------------------
+	if (input.query) {
+		clauses.push("c.summary LIKE ?");
+		params.push(`%${input.query}%`);
+	}
+
+	// --- level filter ------------------------------------------------------
+	if (input.level !== undefined) {
+		clauses.push("c.level = ?");
+		params.push(input.level);
+	}
+
+	// --- package_path filter -----------------------------------------------
+	if (input.package_path) {
+		clauses.push("c.package_path = ?");
+		params.push(input.package_path);
+	}
+
+	const whereClause = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+	params.push(MAX_RESULTS);
+
+	const sql = `SELECT c.id, c.level, c.summary, c.member_count, c.parent_id, c.package_path
+		FROM communities c
+		${whereClause}
+		ORDER BY c.member_count DESC
+		LIMIT ?`;
+
+	const result = await db.execute(sql, params);
+
+	const communities: CommunitySummary[] = result.rows.map((row) => ({
+		id: row.id as string,
+		level: row.level as number,
+		summary: (row.summary as string | null) ?? null,
+		member_count: (row.member_count as number) ?? 0,
+		parent_id: (row.parent_id as string | null) ?? null,
+		package_path: (row.package_path as string | null) ?? null,
+	}));
+
+	// If no communities found, check whether this is because the graph is too
+	// small (< 100 entities) to have generated communities at all.
+	if (communities.length === 0) {
+		const countResult = await db.execute("SELECT COUNT(*) AS cnt FROM communities", []);
+		const totalCommunities = (countResult.rows[0]?.cnt as number) ?? 0;
+
+		if (totalCommunities === 0) {
+			const entityCountResult = await db.execute("SELECT COUNT(*) AS cnt FROM graph_nodes", []);
+			const totalEntities = (entityCountResult.rows[0]?.cnt as number) ?? 0;
+
+			if (totalEntities < 100) {
+				return { communities: [], global_unavailable: true };
+			}
+		}
+	}
+
+	return { communities };
+}

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

@@ -0,0 +1,73 @@
+// Module: sia-doctor — Handler for the sia_doctor diagnostic tool
+
+import type { z } from "zod";
+import type { SiaDb } from "@/graph/db-interface";
+import type { SiaDoctorInput } from "@/mcp/server";
+import { RUNTIME_MAP } from "@/sandbox/executor";
+import {
+	checkFts5,
+	checkOrphanEdges,
+	checkRuntime,
+	checkTemporalInvariants,
+	type DiagnosticCheck,
+} from "@/shared/diagnostics";
+
+// ---------------------------------------------------------------------------
+// SiaDoctorResult
+// ---------------------------------------------------------------------------
+
+export interface SiaDoctorResult {
+	checks: DiagnosticCheck[];
+	healthy: boolean;
+	warnings: string[];
+}
+
+// ---------------------------------------------------------------------------
+// handleSiaDoctor
+// ---------------------------------------------------------------------------
+
+export async function handleSiaDoctor(
+	db: SiaDb,
+	input: z.infer<typeof SiaDoctorInput>,
+): Promise<SiaDoctorResult> {
+	const requested = input.checks ?? ["all"];
+	const runAll = requested.includes("all");
+
+	const checks: DiagnosticCheck[] = [];
+
+	// -----------------------------------------------------------------------
+	// Runtimes (14 entries from RUNTIME_MAP)
+	// -----------------------------------------------------------------------
+	if (runAll || requested.includes("runtimes")) {
+		const runtimeChecks = await Promise.all(
+			Object.entries(RUNTIME_MAP).map(([lang, def]) => checkRuntime(lang, def.cmd)),
+		);
+		checks.push(...runtimeChecks);
+	}
+
+	// -----------------------------------------------------------------------
+	// FTS5
+	// -----------------------------------------------------------------------
+	if (runAll || requested.includes("fts5")) {
+		checks.push(await checkFts5(db));
+	}
+
+	// -----------------------------------------------------------------------
+	// Graph integrity: orphan edges + temporal invariants
+	// -----------------------------------------------------------------------
+	if (runAll || requested.includes("graph_integrity")) {
+		const [orphanResult, temporalResult] = await Promise.all([
+			checkOrphanEdges(db),
+			checkTemporalInvariants(db),
+		]);
+		checks.push(orphanResult, temporalResult);
+	}
+
+	// -----------------------------------------------------------------------
+	// Aggregate
+	// -----------------------------------------------------------------------
+	const healthy = checks.every((c) => c.status === "ok");
+	const warnings = checks.filter((c) => c.status !== "ok").map((c) => c.message);
+
+	return { checks, healthy, warnings };
+}

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

@@ -0,0 +1,122 @@
+// Module: sia-execute-file — Execute an existing file in a sandbox subprocess with throttle + context mode
+// Raw file content never enters the agent's context window — it is copied to a temp dir and executed from there.
+
+import { copyFileSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import type { z } from "zod";
+import type { Embedder } from "@/capture/embedder";
+import type { SiaDb } from "@/graph/db-interface";
+import type { SiaExecuteFileInput as SiaExecuteFileInputSchema } from "@/mcp/server";
+import type { ProgressiveThrottle } from "@/retrieval/throttle";
+import type { ContextModeResult } from "@/sandbox/context-mode";
+import { applyContextMode, lineChunker } from "@/sandbox/context-mode";
+import { buildSandboxEnv } from "@/sandbox/credential-pass";
+import { executeSubprocess } from "@/sandbox/executor";
+
+export type SiaExecuteFileInput = z.infer<typeof SiaExecuteFileInputSchema>;
+
+export interface SiaExecuteFileConfig {
+	sandboxTimeoutMs: number;
+	sandboxOutputMaxBytes: number;
+	contextModeThreshold: number;
+	contextModeTopK: number;
+}
+
+const DEFAULT_CONFIG: SiaExecuteFileConfig = {
+	sandboxTimeoutMs: 30_000,
+	sandboxOutputMaxBytes: 1_048_576,
+	contextModeThreshold: 10_240,
+	contextModeTopK: 5,
+};
+
+export interface SiaExecuteFileResult {
+	stdout?: string;
+	stderr?: string;
+	exitCode?: number | null;
+	timedOut?: boolean;
+	runtimeMs?: number;
+	contextMode?: ContextModeResult;
+	error?: string;
+}
+
+/**
+ * Handle a sia_execute_file request: validate file exists, throttle check,
+ * copy to sandbox temp dir, execute, apply optional context mode.
+ */
+export async function handleSiaExecuteFile(
+	db: SiaDb,
+	input: SiaExecuteFileInput,
+	embedder: Embedder,
+	throttle: ProgressiveThrottle,
+	sessionId: string,
+	config?: Partial<SiaExecuteFileConfig>,
+): Promise<SiaExecuteFileResult> {
+	const cfg: SiaExecuteFileConfig = { ...DEFAULT_CONFIG, ...config };
+
+	// 1. Validate file exists
+	if (!existsSync(input.file_path)) {
+		return { error: `File not found: ${input.file_path}` };
+	}
+
+	// 2. Throttle check — if blocked, return error
+	const throttleResult = await throttle.check(sessionId, "sia_execute_file");
+	if (throttleResult.mode === "blocked") {
+		return { error: throttleResult.warning ?? "Tool blocked for this session." };
+	}
+
+	// 3. Copy file to sandbox temp dir so raw content stays on disk, not in context
+	const sandboxDir = mkdtempSync(join(tmpdir(), "sia-exec-file-"));
+	const copiedPath = join(sandboxDir, basename(input.file_path));
+	copyFileSync(input.file_path, copiedPath);
+
+	// 4. Build sandbox env
+	const env = buildSandboxEnv();
+
+	// 5. Execute subprocess using the copied file path
+	const result = await executeSubprocess({
+		language: input.language,
+		filePath: copiedPath,
+		code: "",
+		timeout: input.timeout ?? cfg.sandboxTimeoutMs,
+		cwd: sandboxDir,
+		env,
+		outputMaxBytes: cfg.sandboxOutputMaxBytes,
+	});
+	try {
+		rmSync(sandboxDir, { recursive: true, force: true });
+	} catch (e) {
+		console.error("[sia-execute-file] cleanup failed:", (e as Error).message);
+	}
+
+	// 6. Apply context mode if output large + intent provided
+	if (result.stdout.length > cfg.contextModeThreshold && input.intent !== undefined) {
+		const contextMode = await applyContextMode(
+			result.stdout,
+			input.intent,
+			lineChunker,
+			db,
+			embedder,
+			sessionId,
+			{ threshold: cfg.contextModeThreshold, topK: cfg.contextModeTopK },
+		);
+
+		return {
+			...(contextMode.applied ? {} : { stdout: result.stdout }),
+			stderr: result.stderr || undefined,
+			exitCode: result.exitCode,
+			timedOut: result.timedOut || undefined,
+			runtimeMs: result.runtimeMs,
+			contextMode,
+		};
+	}
+
+	// 7. Return plain result
+	return {
+		stdout: result.stdout,
+		stderr: result.stderr || undefined,
+		exitCode: result.exitCode,
+		timedOut: result.timedOut || undefined,
+		runtimeMs: result.runtimeMs,
+	};
+}

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

@@ -0,0 +1,104 @@
+// Module: sia-execute — Execute code in a sandbox subprocess with throttle + context mode
+
+import type { z } from "zod";
+import type { Embedder } from "@/capture/embedder";
+import type { SiaDb } from "@/graph/db-interface";
+import type { SiaExecuteInput as SiaExecuteInputSchema } from "@/mcp/server";
+import type { ProgressiveThrottle } from "@/retrieval/throttle";
+import type { ContextModeResult } from "@/sandbox/context-mode";
+import { applyContextMode, lineChunker } from "@/sandbox/context-mode";
+import { buildSandboxEnv } from "@/sandbox/credential-pass";
+import { executeSubprocess } from "@/sandbox/executor";
+
+export type SiaExecuteInput = z.infer<typeof SiaExecuteInputSchema>;
+
+export interface SiaExecuteConfig {
+	sandboxTimeoutMs: number;
+	sandboxOutputMaxBytes: number;
+	contextModeThreshold: number;
+	contextModeTopK: number;
+}
+
+const DEFAULT_CONFIG: SiaExecuteConfig = {
+	sandboxTimeoutMs: 30_000,
+	sandboxOutputMaxBytes: 1_048_576,
+	contextModeThreshold: 10_240,
+	contextModeTopK: 5,
+};
+
+export interface SiaExecuteResult {
+	stdout?: string;
+	stderr?: string;
+	exitCode?: number | null;
+	timedOut?: boolean;
+	truncated?: boolean;
+	runtimeMs?: number;
+	contextMode?: ContextModeResult;
+	error?: string;
+}
+
+/**
+ * Handle a sia_execute request: throttle check, sandbox execution, optional context mode.
+ */
+export async function handleSiaExecute(
+	db: SiaDb,
+	input: SiaExecuteInput,
+	embedder: Embedder,
+	throttle: ProgressiveThrottle,
+	sessionId: string,
+	config?: Partial<SiaExecuteConfig>,
+): Promise<SiaExecuteResult> {
+	const cfg: SiaExecuteConfig = { ...DEFAULT_CONFIG, ...config };
+
+	// 1. Throttle check — if blocked, return error
+	const throttleResult = await throttle.check(sessionId, "sia_execute");
+	if (throttleResult.mode === "blocked") {
+		return { error: throttleResult.warning ?? "Tool blocked for this session." };
+	}
+
+	// 2. Build sandbox env
+	const env = buildSandboxEnv(input.env);
+
+	// 3. Execute subprocess
+	const result = await executeSubprocess({
+		language: input.language,
+		code: input.code,
+		timeout: input.timeout ?? cfg.sandboxTimeoutMs,
+		env,
+		outputMaxBytes: cfg.sandboxOutputMaxBytes,
+	});
+
+	// 4. Apply context mode if output large + intent provided
+	if (result.stdout.length > cfg.contextModeThreshold && input.intent !== undefined) {
+		const contextMode = await applyContextMode(
+			result.stdout,
+			input.intent,
+			lineChunker,
+			db,
+			embedder,
+			sessionId,
+			{ threshold: cfg.contextModeThreshold, topK: cfg.contextModeTopK },
+		);
+
+		return {
+			// Omit stdout when context mode was applied
+			...(contextMode.applied ? {} : { stdout: result.stdout }),
+			stderr: result.stderr || undefined,
+			exitCode: result.exitCode,
+			timedOut: result.timedOut || undefined,
+			truncated: result.truncated || undefined,
+			runtimeMs: result.runtimeMs,
+			contextMode,
+		};
+	}
+
+	// 5. Return plain result
+	return {
+		stdout: result.stdout,
+		stderr: result.stderr || undefined,
+		exitCode: result.exitCode,
+		timedOut: result.timedOut || undefined,
+		truncated: result.truncated || undefined,
+		runtimeMs: result.runtimeMs,
+	};
+}

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

@@ -0,0 +1,158 @@
+// Module: sia-expand — BFS neighbourhood expansion from an entity in the knowledge graph
+
+import type { z } from "zod";
+import { getOrCreateLevel1Summary } from "@/community/raptor";
+import type { SiaDb } from "@/graph/db-interface";
+import type { EdgeRow } from "@/graph/edges";
+import type { Entity } from "@/graph/entities";
+import { annotateFreshness } from "@/mcp/freshness-annotator";
+import type { SiaExpandInput } from "@/mcp/server";
+
+/** Result shape for sia_expand. */
+export interface SiaExpandResult {
+	entity: Entity;
+	neighbors: Entity[];
+	edges: EdgeRow[];
+	edge_count: number;
+}
+
+/** Error result when root entity is not found. */
+export interface SiaExpandError {
+	error: string;
+}
+
+const MAX_ENTITIES = 50;
+const MAX_EDGES = 200;
+
+/**
+ * BFS expansion from `entity_id` through active edges.
+ *
+ * - Configurable depth (default 1, max 3).
+ * - Hard cap of 50 entities in the result.
+ * - Optional `edge_types` filter restricts which edge types are traversed.
+ * - `edge_count` is the total number of active edges found (before the 200 cap).
+ * - `edges[]` is capped at 200 entries.
+ * - Returns an error object if the root entity does not exist or is inactive.
+ */
+export async function handleSiaExpand(
+	db: SiaDb,
+	input: z.infer<typeof SiaExpandInput>,
+): Promise<SiaExpandResult | SiaExpandError> {
+	const depth = input.depth ?? 1;
+	const edgeTypes = input.edge_types;
+
+	// --- Fetch root entity ---
+	const rootResult = await db.execute(
+		"SELECT * FROM graph_nodes WHERE id = ? AND t_valid_until IS NULL AND archived_at IS NULL",
+		[input.entity_id],
+	);
+
+	if (rootResult.rows.length === 0) {
+		return { error: `Entity not found or inactive: ${input.entity_id}` };
+	}
+
+	const rootEntity = rootResult.rows[0] as unknown as Entity;
+
+	// Fire-and-forget: lazily generate Level 1 summary for this entity
+	void getOrCreateLevel1Summary(db, input.entity_id);
+
+	// --- BFS ---
+	const visited = new Set<string>([input.entity_id]);
+	const allEdges: EdgeRow[] = [];
+	let totalEdgeCount = 0;
+
+	// Current frontier of entity IDs to expand
+	let frontier = [input.entity_id];
+
+	for (let d = 0; d < depth; d++) {
+		if (frontier.length === 0) break;
+		if (visited.size >= MAX_ENTITIES) break;
+
+		const nextFrontier: string[] = [];
+
+		for (const entityId of frontier) {
+			if (visited.size >= MAX_ENTITIES) break;
+
+			// Build edge query with optional type filter
+			let edgeSql: string;
+			let edgeParams: unknown[];
+
+			if (edgeTypes && edgeTypes.length > 0) {
+				const placeholders = edgeTypes.map(() => "?").join(", ");
+				edgeSql = `SELECT * FROM graph_edges
+					WHERE (from_id = ? OR to_id = ?)
+					  AND t_valid_until IS NULL
+					  AND type IN (${placeholders})`;
+				edgeParams = [entityId, entityId, ...edgeTypes];
+			} else {
+				edgeSql = `SELECT * FROM graph_edges
+					WHERE (from_id = ? OR to_id = ?)
+					  AND t_valid_until IS NULL`;
+				edgeParams = [entityId, entityId];
+			}
+
+			const edgeResult = await db.execute(edgeSql, edgeParams);
+			const edges = edgeResult.rows as unknown as EdgeRow[];
+
+			for (const edge of edges) {
+				totalEdgeCount++;
+
+				// Track the edge (up to cap)
+				if (allEdges.length < MAX_EDGES) {
+					// Avoid duplicate edges
+					if (!allEdges.some((e) => e.id === edge.id)) {
+						allEdges.push(edge);
+					}
+				}
+
+				// Determine the neighbor on the other side
+				const neighborId = edge.from_id === entityId ? edge.to_id : edge.from_id;
+
+				if (!visited.has(neighborId) && visited.size < MAX_ENTITIES) {
+					visited.add(neighborId);
+					nextFrontier.push(neighborId);
+				}
+			}
+		}
+
+		frontier = nextFrontier;
+	}
+
+	// --- Fetch neighbor entities (active only) ---
+	const neighborIds = [...visited].filter((id) => id !== input.entity_id);
+	const neighbors: Entity[] = [];
+
+	for (const nid of neighborIds) {
+		const nResult = await db.execute(
+			"SELECT * FROM graph_nodes WHERE id = ? AND t_valid_until IS NULL AND archived_at IS NULL",
+			[nid],
+		);
+		if (nResult.rows.length > 0) {
+			neighbors.push(nResult.rows[0] as unknown as Entity);
+		}
+	}
+
+	// Deduplicate allEdges by id (edges may have been encountered from both sides)
+	const seenEdgeIds = new Set<string>();
+	const dedupedEdges: EdgeRow[] = [];
+	for (const edge of allEdges) {
+		if (!seenEdgeIds.has(edge.id)) {
+			seenEdgeIds.add(edge.id);
+			dedupedEdges.push(edge);
+		}
+	}
+
+	const allEntities = [rootEntity, ...neighbors];
+	const annotated = await annotateFreshness(
+		allEntities as unknown as Record<string, unknown>[],
+		db,
+	);
+	const [annotatedRoot, ...annotatedNeighbors] = annotated;
+
+	return {
+		entity: annotatedRoot as unknown as Entity,
+		neighbors: annotatedNeighbors as unknown as Entity[],
+		edges: dedupedEdges.slice(0, MAX_EDGES),
+		edge_count: totalEdgeCount,
+	};
+}