@bacnh85/pi-serena 0.4.2 → 0.5.0

package/index.ts

@@ -4,6 +4,7 @@ import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import path from "node:path";
 import { SerenaWorkerClient, type SerenaWorkerResponse } from "./worker";
 import { SEMANTIC_MISS_THRESHOLD, pathLooksLikeCode, pathLooksNonSemantic, commandLooksLikeSemanticCodeSearch } from "./lib/detect";
+import { normalizeProject, normalizeContext, normalizeTimeoutMs, stripControlParams, normalizeSearchPatternParams, normalizeFindReferencesParams, normalizeReplaceContentParams, validateReplaceContentParams } from "./lib/normalize";
 
 const DEFAULT_CONTEXT = "ide";
 
@@ -145,77 +146,12 @@ const replaceContentSchema = Type.Object({
 	needle: Type.Optional(Type.String({ description: "Exact text or regex pattern to replace." })),
 	repl: Type.Optional(Type.String({ description: "Replacement text." })),
 	mode: Type.Optional(Type.Union([Type.Literal("literal"), Type.Literal("regex")], { description: "Interpret needle as exact text or as a Python regex." })),
-	old_string: Type.Optional(Type.String({ description: "Deprecated alias for literal needle." })),
-	new_string: Type.Optional(Type.String({ description: "Deprecated alias for repl with old_string." })),
-	content: Type.Optional(Type.String({ description: "Deprecated alias for repl with regex." })),
-	regex: Type.Optional(Type.String({ description: "Deprecated alias for regex needle." })),
 	allow_multiple_occurrences: Type.Optional(Type.Boolean({ description: "Allow replacing multiple matches when supported." })),
 });
 
-function normalizeProject(project: unknown): string {
-	return typeof project === "string" && project.trim() ? project : process.cwd();
-}
-
-function normalizeContext(context: unknown): string {
-	return typeof context === "string" && context.trim() ? context : DEFAULT_CONTEXT;
-}
-
-function normalizeTimeoutMs(timeoutMs: unknown): number | undefined {
-	if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) return undefined;
-	return timeoutMs;
-}
 
-function stripControlParams(params: Record<string, unknown>): { project: string; context: string; timeoutMs: number | undefined; params: Record<string, unknown> } {
-	const { project, context, timeout_ms, ...toolParams } = params;
-	return { project: normalizeProject(project), context: normalizeContext(context), timeoutMs: normalizeTimeoutMs(timeout_ms), params: toolParams };
-}
 
-export function normalizeSearchPatternParams(params: Record<string, unknown>): Record<string, unknown> {
-	const normalized = { ...params };
-	if (normalized.substring_pattern === undefined && normalized.pattern !== undefined) {
-		normalized.substring_pattern = normalized.pattern;
-	}
-	delete normalized.pattern;
-	// The Python SearchForPatternTool.apply() does not accept a multiline parameter.
-	// Strip it here to avoid TypeError when the parameter description says "when supported by Serena".
-	delete normalized.multiline;
-	return normalized;
-}
-
-export function normalizeFindReferencesParams(params: Record<string, unknown>): Record<string, unknown> {
-	const normalized = { ...params };
-	delete normalized.include_body;
-	return normalized;
-}
-
-export function normalizeReplaceContentParams(params: Record<string, unknown>): Record<string, unknown> {
-	const normalized = { ...params };
-
-	if (normalized.needle === undefined) {
-		normalized.needle = normalized.old_string ?? normalized.regex;
-	}
-	if (normalized.repl === undefined) {
-		normalized.repl = normalized.new_string ?? normalized.content;
-	}
-	if (normalized.mode === undefined) {
-		if (normalized.regex !== undefined) normalized.mode = "regex";
-		else if (normalized.old_string !== undefined) normalized.mode = "literal";
-	}
 
-	delete normalized.old_string;
-	delete normalized.new_string;
-	delete normalized.content;
-	delete normalized.regex;
-
-	return normalized;
-}
-
-function validateReplaceContentParams(params: Record<string, unknown>): string | undefined {
-	if (typeof params.needle !== "string") return "serena_replace_content requires string parameter 'needle' (or deprecated alias 'old_string'/'regex').";
-	if (typeof params.repl !== "string") return "serena_replace_content requires string parameter 'repl' (or deprecated alias 'new_string'/'content').";
-	if (params.mode !== "literal" && params.mode !== "regex") return "serena_replace_content requires mode to be 'literal' or 'regex'.";
-	return undefined;
-}
 
 function truncateText(text: string): string {
 	const lines = text.split("\n");
@@ -234,9 +170,27 @@ function truncateText(text: string): string {
 	return output;
 }
 
+function errorSuggestion(errorType: string | undefined, tool: string | undefined): string {
+	switch (errorType) {
+		case "language_server_error":
+			return " The language server may need a restart. Try serena_restart_language_server first.";
+		case "missing_tool":
+			return ` The tool '${tool ?? "unknown"}' is not available. Try serena_list_tools to see available tools for this project.`;
+		case "inactive_tool":
+			return ` The tool '${tool ?? "unknown"}' is not active in the current context. Try serena_list_tools to see active tools.`;
+		case "timeout":
+			return " The request timed out. Retry with a longer timeout_ms parameter.";
+		case "project_error":
+			return " There is a project configuration issue. Try serena_get_current_config to inspect the active project.";
+		default:
+			return "";
+	}
+}
+
 function resultText(response: SerenaWorkerResponse): string {
 	if (!response.ok) {
-		return `Error: ${response.error ?? "Unknown Serena error"}`;
+		const suggestion = errorSuggestion(response.errorType as string | undefined, response.tool as string | undefined);
+		return `Error: ${response.error ?? "Unknown Serena error"}${suggestion}`;
 	}
 	// For search results, show a friendly empty-state instead of raw "{}".
 	if (response.tool === "search_for_pattern") {
@@ -258,8 +212,17 @@ export default function serenaToolsExtension(pi: ExtensionAPI) {
 
 	const callWorkerAction = async (ctx: any, action: string, rawParams: Record<string, unknown>, extraPayload: Record<string, unknown> = {}, lockPath?: string) => {
 		const { project, context, timeoutMs, params } = stripControlParams(rawParams);
-		const run = async () => {
+		const run = async (): Promise<{ content: { type: "text"; text: string }[]; details: SerenaWorkerResponse }> => {
 			const response = await getWorker(ctx).request({ action, project, context, params, ...extraPayload }, timeoutMs);
+			// Auto-retry once on transient errors (timeout, language_server_error)
+			const errorType = response.errorType as string | undefined;
+			if (!response.ok && (errorType === "timeout" || errorType === "language_server_error")) {
+				const retryResponse = await getWorker(ctx).request({ action, project, context, params, ...extraPayload }, timeoutMs);
+				return {
+					content: [{ type: "text" as const, text: resultText(retryResponse) }],
+					details: retryResponse,
+				};
+			}
 			return {
 				content: [{ type: "text" as const, text: resultText(response) }],
 				details: response,
@@ -417,6 +380,12 @@ export default function serenaToolsExtension(pi: ExtensionAPI) {
 		promptGuidelines: ["Use serena_search_for_pattern for project-scoped code searches when symbol lookup is not enough."],
 		parameters: searchPatternSchema,
 		async execute(_id, params, _signal, _onUpdate, ctx) {
+			if (params.multiline === true) {
+				return {
+					content: [{ type: "text" as const, text: "Error: serena_search_for_pattern does not support multiline mode. Use serena_search_for_pattern without multiline or use serena_find_symbol for symbol-aware searches instead." }],
+					details: { ok: false, error: "multiline not supported" },
+				};
+			}
 			return callSerena(ctx, "search_for_pattern", normalizeSearchPatternParams(params));
 		},
 	});
@@ -429,10 +398,15 @@ export default function serenaToolsExtension(pi: ExtensionAPI) {
 		promptGuidelines: ["Prefer symbol-aware Serena edit tools for whole symbols; use serena_replace_content for non-symbol scoped replacements supported by Serena."],
 		parameters: replaceContentSchema,
 		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const hasDeprecated = params.old_string !== undefined || params.new_string !== undefined || params.content !== undefined || params.regex !== undefined;
 			const normalized = normalizeReplaceContentParams(params);
 			const error = validateReplaceContentParams(normalized);
 			if (error) return { content: [{ type: "text" as const, text: `Error: ${error}` }], details: { ok: false, error } };
-			return callSerena(ctx, "replace_content", normalized, lockPathForRelativeFile(params));
+			const result = await callSerena(ctx, "replace_content", normalized, lockPathForRelativeFile(params));
+			if (hasDeprecated) {
+				result.content[0].text = "[Deprecation warning] Use 'needle', 'repl', and 'mode' instead of deprecated aliases (old_string, new_string, content, regex).\n\n" + result.content[0].text;
+			}
+			return result;
 		},
 	});
 
@@ -623,8 +597,10 @@ export default function serenaToolsExtension(pi: ExtensionAPI) {
 		},
 	});
 
-	// Unconditional Serena guidance on every session
+	// Serena guidance — only inject when serena tools are actually active
 	pi.on("before_agent_start", async (event) => {
+		const serenaActive = event.systemPromptOptions?.selectedTools?.includes("serena_find_symbol");
+		if (!serenaActive) return;
 		return {
 			systemPrompt:
 				event.systemPrompt +
@@ -633,6 +609,10 @@ export default function serenaToolsExtension(pi: ExtensionAPI) {
 	});
 
 	pi.on("tool_call", async (event) => {
+		// Skip semantic miss detection if serena tools are not active (e.g., plan mode)
+		const activeTools = pi.getActiveTools();
+		if (!activeTools.includes("serena_find_symbol")) return;
+
 		if (event.toolName.startsWith("serena_")) {
 			semanticMissCount = 0;
 			return;
@@ -663,6 +643,16 @@ export default function serenaToolsExtension(pi: ExtensionAPI) {
 		}
 	});
 
+	// Eager startup: pre-spawn the worker on session start when SERENA_EAGER_STARTUP=1
+	pi.on("session_start", async (_event, ctx) => {
+		if (process.env.SERENA_EAGER_STARTUP === "1") {
+			// Spawn the worker via a lightweight status request to warm the Python bridge
+			getWorker(ctx).request({ action: "status", project: process.cwd(), context: DEFAULT_CONTEXT }, 30_000).catch(() => {
+				// Eager startup is best-effort; failures are handled when the tool is first used
+			});
+		}
+	});
+
 	pi.on("session_shutdown", async (_event, ctx) => {
 		await worker?.stop();
 		worker = undefined;

package/lib/detect.ts

@@ -26,9 +26,21 @@ export const CODE_FILE_EXTENSIONS = new Set([
 	".ts",
 	".tsx",
 	".vue",
+	// Additional code file extensions commonly encountered
+	".spec.ts",
+	".test.ts",
+	".server.ts",
+	".server.tsx",
+	".d.ts",
+	".config.ts",
+	".cjs",
 ]);
 
-const NON_SEMANTIC_FILE_EXTENSIONS = new Set([".json", ".jsonl", ".lock", ".md", ".txt", ".yaml", ".yml"]);
+const NON_SEMANTIC_FILE_EXTENSIONS = new Set([
+	".json", ".jsonl", ".lock", ".md", ".txt", ".yaml", ".yml",
+	".csv", ".log", ".env", ".ini", ".cfg", ".toml",
+	".editorconfig", ".gitignore",
+]);
 
 export const SEMANTIC_MISS_THRESHOLD = 2;
 
@@ -48,9 +60,14 @@ export function pathLooksNonSemantic(value: unknown): boolean {
 	return NON_SEMANTIC_FILE_EXTENSIONS.has(cleanPath.slice(dotIndex));
 }
 
+const TODO_LIKE_PATTERNS = /\b(TODO|FIXME|HACK|NOTE|XXX|BUG|WORKAROUND|OPTIMIZE|REVIEW|TEMP|WARNING|WORKAROUND)\b/i;
+
 export function commandLooksLikeSemanticCodeSearch(command: string): boolean {
 	if (!/\b(rg|grep|fd|find)\b/.test(command)) return false;
+	// Non-semantic targets: docs, configs, and project files
 	if (/\b(SKILL\.md|README\.md|AGENTS\.md|package\.json|skill-registry\.json|skill-history\.jsonl)\b/i.test(command)) return false;
+	// Searching for TODO/FIXME/etc. is a non-semantic text search
+	if (TODO_LIKE_PATTERNS.test(command)) return false;
 	if (/\b(symbol|class|method|function|def|interface|references?|implementation|declaration|rename|refactor)\b/i.test(command)) return true;
-	return /\.(c|cc|cpp|cs|go|java|js|jsx|kt|lua|mjs|php|py|rb|rs|scala|sh|swift|ts|tsx|vue)\b/i.test(command);
+	return /\.(c|cc|cpp|cs|go|java|js|jsx|kt|lua|mjs|php|py|rb|rs|scala|sh|swift|ts|tsx|vue|spec\.ts|test\.ts|server\.ts|server\.tsx|d\.ts|config\.ts|cjs)\b/i.test(command);
 }

package/lib/normalize.ts

@@ -0,0 +1,69 @@
+/**
+ * Parameter normalization logic for pi-serena.
+ * Extracted from index.ts so it can be tested without importing pi-coding-agent.
+ */
+
+export function normalizeProject(project: unknown): string {
+	return typeof project === "string" && project.trim() ? project : process.cwd();
+}
+
+export function normalizeContext(context: unknown): string {
+	return typeof context === "string" && context.trim() ? context : "ide";
+}
+
+export function normalizeTimeoutMs(timeoutMs: unknown): number | undefined {
+	if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) return undefined;
+	return timeoutMs;
+}
+
+export function stripControlParams(params: Record<string, unknown>): { project: string; context: string; timeoutMs: number | undefined; params: Record<string, unknown> } {
+	const { project, context, timeout_ms, ...toolParams } = params;
+	return { project: normalizeProject(project), context: normalizeContext(context), timeoutMs: normalizeTimeoutMs(timeout_ms), params: toolParams };
+}
+
+export function normalizeSearchPatternParams(params: Record<string, unknown>): Record<string, unknown> {
+	const normalized = { ...params };
+	if (normalized.substring_pattern === undefined && normalized.pattern !== undefined) {
+		normalized.substring_pattern = normalized.pattern;
+	}
+	delete normalized.pattern;
+	// multiline is not supported by the Python backend; validation above catches true values.
+	// Strip it here as a safety net to avoid TypeError.
+	delete normalized.multiline;
+	return normalized;
+}
+
+export function normalizeFindReferencesParams(params: Record<string, unknown>): Record<string, unknown> {
+	const normalized = { ...params };
+	delete normalized.include_body;
+	return normalized;
+}
+
+export function normalizeReplaceContentParams(params: Record<string, unknown>): Record<string, unknown> {
+	const normalized = { ...params };
+
+	if (normalized.needle === undefined) {
+		normalized.needle = normalized.old_string ?? normalized.regex;
+	}
+	if (normalized.repl === undefined) {
+		normalized.repl = normalized.new_string ?? normalized.content;
+	}
+	if (normalized.mode === undefined) {
+		if (normalized.regex !== undefined) normalized.mode = "regex";
+		else if (normalized.old_string !== undefined) normalized.mode = "literal";
+	}
+
+	delete normalized.old_string;
+	delete normalized.new_string;
+	delete normalized.content;
+	delete normalized.regex;
+
+	return normalized;
+}
+
+export function validateReplaceContentParams(params: Record<string, unknown>): string | undefined {
+	if (typeof params.needle !== "string") return "serena_replace_content requires string parameter 'needle' (or deprecated alias 'old_string'/'regex').";
+	if (typeof params.repl !== "string") return "serena_replace_content requires string parameter 'repl' (or deprecated alias 'new_string'/'content').";
+	if (params.mode !== "literal" && params.mode !== "regex") return "serena_replace_content requires mode to be 'literal' or 'regex'.";
+	return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-serena",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Pi extension that provides Serena semantic code tools through a persistent worker.",
   "license": "MIT",
   "publishConfig": {