@bacnh85/pi-serena 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# pi-serena
+
+Pi extension that registers Pi-native `serena_*` tools backed by a persistent TypeScript/Node worker. This avoids configuring Pi as an MCP client while still using Serena's semantic code APIs.
+
+Note: Serena itself is a Python package. The TypeScript worker owns lifecycle, request/response handling, and Pi integration, and uses an embedded Python bridge subprocess only to call Serena internals because Serena does not provide a JavaScript SDK and its non-MCP project HTTP server is read-only.
+
+## Install
+
+From this repository checkout, install only this extension package:
+
+```bash
+pi install ./extensions/pi-serena
+```
+
+For local development from a checkout:
+
+```bash
+pi -e ./extensions/pi-serena
+```
+
+There is intentionally no repository-level Pi package. Install each extension from its own subdirectory, matching `extensions/pi-rtk` and future extensions.
+
+After install or update, restart Pi or run `/reload` in an existing Pi session.
+
+## Tools
+
+- `serena_status`
+- `serena_list_tools`
+- `serena_get_symbols_overview`
+- `serena_find_symbol`
+- `serena_find_referencing_symbols`
+- `serena_replace_symbol_body`
+- `serena_insert_before_symbol`
+- `serena_insert_after_symbol`
+- `serena_rename_symbol`
+- `serena_safe_delete_symbol`
+- `serena_search_for_pattern`
+- `serena_replace_content`
+- `serena_restart_language_server`
+- `serena_get_current_config`
+- `serena_check_onboarding_performed`
+- `serena_onboarding`
+- `serena_list_memories`
+- `serena_read_memory`
+- `serena_write_memory`
+- `serena_delete_memory`
+
+All tool outputs are truncated to 50KB / 2000 lines to match Pi-friendly output limits. Most tools accept optional `timeout_ms`.
+
+## Commands
+
+- `/serena-status [project]`
+- `/serena-dashboard [project]`
+- `/serena-restart`
+
+The persistent Pi worker keeps one Serena bridge process per Pi process/session. It keeps the dashboard server available by default but does not open a browser tab automatically; use `/serena-dashboard` when you want to open it. Set `SERENA_BRIDGE_WEB_DASHBOARD=0` to disable the dashboard server, or `SERENA_BRIDGE_OPEN_DASHBOARD=1` to restore automatic browser launch. These variables are read from the process environment, current working directory `.env.local`/`.env`, or Pi global config `.env.local`/`.env` under `$PI_CODING_AGENT_DIR`, `~/.pi/agent`, or compatibility path `~/.pi/agents`.
+
+## Worker protocol
+
+`worker.ts` implements the persistent worker client in TypeScript. The extension starts one worker per Pi process, lazily on first use, and shuts it down on `session_shutdown`.

package/index.ts

@@ -0,0 +1,552 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { SerenaWorkerClient, type SerenaWorkerResponse } from "./worker";
+
+const DEFAULT_CONTEXT = "ide";
+
+const PROJECT_PARAM = Type.Optional(Type.String({ description: "Project path or registered Serena project name. Defaults to Pi's current working directory." }));
+const CONTEXT_PARAM = Type.Optional(Type.String({ description: "Serena context name. Defaults to ide." }));
+const MAX_CHARS_PARAM = Type.Optional(Type.Number({ description: "Maximum Serena response characters. Defaults to Serena config." }));
+const TIMEOUT_MS_PARAM = Type.Optional(Type.Number({ description: "Per-call timeout in milliseconds. Defaults to 120000." }));
+const OUTPUT_MAX_BYTES = 50 * 1024;
+const OUTPUT_MAX_LINES = 2_000;
+
+const controlSchema = {
+	project: PROJECT_PARAM,
+	context: CONTEXT_PARAM,
+	timeout_ms: TIMEOUT_MS_PARAM,
+};
+
+const statusSchema = Type.Object({
+	project: PROJECT_PARAM,
+	context: CONTEXT_PARAM,
+	includeAgent: Type.Optional(Type.Boolean({ description: "Initialize/read a SerenaAgent and include active tools/backend details." })),
+	timeout_ms: TIMEOUT_MS_PARAM,
+});
+
+const listToolsSchema = Type.Object({
+	...controlSchema,
+	includeAgent: Type.Optional(Type.Boolean({ description: "Initialize/read a SerenaAgent before listing active tools." })),
+});
+
+const overviewSchema = Type.Object({
+	...controlSchema,
+	relative_path: Type.String({ description: "File path relative to the Serena project root." }),
+	depth: Type.Optional(Type.Number({ description: "Symbol overview depth." })),
+	max_answer_chars: MAX_CHARS_PARAM,
+});
+
+const findSymbolSchema = Type.Object({
+	...controlSchema,
+	name_path_pattern: Type.String({ description: "Symbol name path pattern, e.g. MyClass/my_method." }),
+	depth: Type.Optional(Type.Number()),
+	relative_path: Type.Optional(Type.String({ description: "Optional file or directory restriction relative to project root." })),
+	include_body: Type.Optional(Type.Boolean()),
+	include_info: Type.Optional(Type.Boolean()),
+	substring_matching: Type.Optional(Type.Boolean()),
+	max_matches: Type.Optional(Type.Number()),
+	max_answer_chars: MAX_CHARS_PARAM,
+});
+
+const referencingSchema = Type.Object({
+	...controlSchema,
+	name_path: Type.String({ description: "Exact symbol name path from find_symbol." }),
+	relative_path: Type.String({ description: "File containing the symbol, relative to project root." }),
+	include_body: Type.Optional(Type.Boolean()),
+	max_answer_chars: MAX_CHARS_PARAM,
+});
+
+const replaceBodySchema = Type.Object({
+	...controlSchema,
+	name_path: Type.String({ description: "Exact symbol name path to replace." }),
+	relative_path: Type.String({ description: "File containing the symbol, relative to project root." }),
+	body: Type.String({ description: "Complete new symbol definition/body, including signature line." }),
+});
+
+const insertSchema = Type.Object({
+	...controlSchema,
+	name_path: Type.String({ description: "Exact reference symbol name path." }),
+	relative_path: Type.String({ description: "File containing the reference symbol, relative to project root." }),
+	body: Type.String({ description: "Content to insert." }),
+});
+
+const renameSchema = Type.Object({
+	...controlSchema,
+	name_path: Type.String({ description: "Exact symbol name path to rename." }),
+	relative_path: Type.String({ description: "File containing the symbol, relative to project root." }),
+	new_name: Type.String({ description: "New symbol name." }),
+});
+
+const safeDeleteSchema = Type.Object({
+	...controlSchema,
+	name_path_pattern: Type.String({ description: "Symbol name path pattern to delete if unreferenced." }),
+	relative_path: Type.String({ description: "File containing the symbol, relative to project root." }),
+});
+
+const emptyToolSchema = Type.Object({ ...controlSchema });
+
+const memoryNameSchema = Type.Object({
+	...controlSchema,
+	memory_name: Type.String({ description: "Serena memory file name." }),
+});
+
+const writeMemorySchema = Type.Object({
+	...controlSchema,
+	memory_name: Type.String({ description: "Serena memory file name." }),
+	content: Type.String({ description: "Memory content to write." }),
+});
+
+const searchPatternSchema = Type.Object({
+	...controlSchema,
+	pattern: Type.String({ description: "Pattern to search for." }),
+	relative_path: Type.Optional(Type.String({ description: "Optional file or directory restriction relative to the Serena project root." })),
+	paths_include_glob: Type.Optional(Type.String({ description: "Optional glob for included paths." })),
+	paths_exclude_glob: Type.Optional(Type.String({ description: "Optional glob for excluded paths." })),
+	max_answer_chars: MAX_CHARS_PARAM,
+});
+
+const replaceContentSchema = Type.Object({
+	...controlSchema,
+	relative_path: Type.String({ description: "File path relative to the Serena project root." }),
+	old_string: Type.Optional(Type.String({ description: "Exact text or regex to replace, depending on Serena version." })),
+	new_string: Type.Optional(Type.String({ description: "Replacement text, depending on Serena version." })),
+	content: Type.Optional(Type.String({ description: "Replacement content for Serena versions that use content-based replacement." })),
+	regex: Type.Optional(Type.String({ description: "Regex pattern for Serena versions that use regex replacement." })),
+	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 };
+}
+
+function truncateText(text: string): string {
+	const lines = text.split("\n");
+	let output = lines.slice(0, OUTPUT_MAX_LINES).join("\n");
+	let truncatedByLines = lines.length > OUTPUT_MAX_LINES;
+	let truncatedByBytes = false;
+
+	while (Buffer.byteLength(output, "utf8") > OUTPUT_MAX_BYTES) {
+		truncatedByBytes = true;
+		output = output.slice(0, Math.max(0, output.length - 1024));
+	}
+
+	if (truncatedByLines || truncatedByBytes) {
+		output += `\n\n[Serena output truncated to ${OUTPUT_MAX_LINES} lines / ${OUTPUT_MAX_BYTES} bytes.]`;
+	}
+	return output;
+}
+
+function resultText(response: SerenaWorkerResponse): string {
+	const text = !response.ok ? `Error: ${response.error ?? "Unknown Serena error"}` : typeof response.result === "string" ? response.result : JSON.stringify(response, null, 2);
+	return truncateText(text);
+}
+
+const CODE_FILE_EXTENSIONS = new Set([
+	".c",
+	".cc",
+	".cpp",
+	".cs",
+	".css",
+	".go",
+	".java",
+	".js",
+	".jsx",
+	".kt",
+	".lua",
+	".mjs",
+	".php",
+	".py",
+	".rb",
+	".rs",
+	".scala",
+	".sh",
+	".swift",
+	".ts",
+	".tsx",
+	".vue",
+]);
+
+const NON_SEMANTIC_FILE_EXTENSIONS = new Set([".json", ".jsonl", ".lock", ".md", ".txt", ".yaml", ".yml"]);
+
+function pathLooksLikeCode(value: unknown): boolean {
+	if (typeof value !== "string" || value.trim() === "") return false;
+	const cleanPath = value.split(/[?#]/, 1)[0].toLowerCase();
+	const dotIndex = cleanPath.lastIndexOf(".");
+	if (dotIndex < 0) return false;
+	return CODE_FILE_EXTENSIONS.has(cleanPath.slice(dotIndex));
+}
+
+function pathLooksNonSemantic(value: unknown): boolean {
+	if (typeof value !== "string" || value.trim() === "") return false;
+	const cleanPath = value.split(/[?#]/, 1)[0].toLowerCase();
+	const dotIndex = cleanPath.lastIndexOf(".");
+	if (dotIndex < 0) return false;
+	return NON_SEMANTIC_FILE_EXTENSIONS.has(cleanPath.slice(dotIndex));
+}
+
+function commandLooksLikeSemanticCodeSearch(command: string): boolean {
+	if (!/\b(rg|grep|fd|find)\b/.test(command)) return false;
+	if (/\b(SKILL\.md|README\.md|AGENTS\.md|package\.json|skill-registry\.json|skill-history\.jsonl)\b/i.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);
+}
+
+export default function serenaToolsExtension(pi: ExtensionAPI) {
+	let worker: SerenaWorkerClient | undefined;
+	let semanticMissCount = 0;
+
+	const getWorker = (ctx?: { ui?: { setStatus?: (key: string, value: string | undefined) => void } }) => {
+		if (!worker) worker = new SerenaWorkerClient((status) => ctx?.ui?.setStatus?.("serena", status ? "serena ✓" : undefined));
+		return worker;
+	};
+
+	const callSerena = async (ctx: any, tool: string, rawParams: Record<string, unknown>) => {
+		const { project, context, timeoutMs, params } = stripControlParams(rawParams);
+		const response = await getWorker(ctx).request({ action: "call", project, context, tool, params }, timeoutMs);
+		return {
+			content: [{ type: "text" as const, text: resultText(response) }],
+			details: response,
+		};
+	};
+
+	pi.registerTool({
+		name: "serena_status",
+		label: "Serena Status",
+		description: "Show Serena worker and project status for semantic code tools.",
+		promptSnippet: "Check Serena semantic worker availability and active project/tool state",
+		promptGuidelines: ["Use serena_status before semantic code retrieval/refactoring if Serena availability is uncertain."],
+		parameters: statusSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const project = normalizeProject(params.project);
+			const context = normalizeContext(params.context);
+			const response = await getWorker(ctx).request({ action: "status", project, context, includeAgent: Boolean(params.includeAgent) }, normalizeTimeoutMs(params.timeout_ms));
+			return { content: [{ type: "text", text: truncateText(JSON.stringify(response, null, 2)) }], details: response };
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_list_tools",
+		label: "Serena List Tools",
+		description: "List active Serena tools for the current project/context.",
+		promptSnippet: "List available Serena semantic, memory, and workflow tools",
+		promptGuidelines: ["Use serena_list_tools when you need to know which Serena tools are active for this project/context."],
+		parameters: listToolsSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const project = normalizeProject(params.project);
+			const context = normalizeContext(params.context);
+			const response = await getWorker(ctx).request({ action: "status", project, context, includeAgent: true }, normalizeTimeoutMs(params.timeout_ms));
+			const tools = Array.isArray(response.activeTools) ? response.activeTools : [];
+			const text = tools.length > 0 ? tools.map((tool) => `- ${tool}`).join("\n") : JSON.stringify(response, null, 2);
+			return { content: [{ type: "text", text: truncateText(text) }], details: response };
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_get_symbols_overview",
+		label: "Serena Symbols Overview",
+		description: "Get top-level symbols for a code file using Serena's language-server backend.",
+		promptSnippet: "Get a semantic outline of symbols in a source file",
+		promptGuidelines: ["Use serena_get_symbols_overview before reading an entire code file when symbol structure is enough."],
+		parameters: overviewSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "get_symbols_overview", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_find_symbol",
+		label: "Serena Find Symbol",
+		description: "Find symbols by name path pattern using Serena semantic code retrieval.",
+		promptSnippet: "Find functions, classes, methods, and variables by semantic symbol name path",
+		promptGuidelines: ["Use serena_find_symbol for code navigation before grep when the target is a function, class, method, or variable."],
+		parameters: findSymbolSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "find_symbol", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_find_referencing_symbols",
+		label: "Serena Find References",
+		description: "Find symbols that reference a given symbol using Serena semantic retrieval.",
+		promptSnippet: "Find semantic references/callers/usages of a known symbol",
+		promptGuidelines: ["Use serena_find_referencing_symbols before changing public behavior or renaming a symbol."],
+		parameters: referencingSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "find_referencing_symbols", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_replace_symbol_body",
+		label: "Serena Replace Symbol Body",
+		description: "Replace a complete function/class/method definition using Serena symbol-aware editing.",
+		promptSnippet: "Replace a complete known symbol body by semantic boundary",
+		promptGuidelines: ["Use serena_replace_symbol_body only after serena_find_symbol identifies the exact symbol to replace."],
+		parameters: replaceBodySchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "replace_symbol_body", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_insert_before_symbol",
+		label: "Serena Insert Before Symbol",
+		description: "Insert content before a known symbol definition using Serena symbol-aware editing.",
+		promptSnippet: "Insert code before a known symbol definition",
+		promptGuidelines: ["Use serena_insert_before_symbol for symbol-adjacent code insertion after locating the target symbol."],
+		parameters: insertSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "insert_before_symbol", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_insert_after_symbol",
+		label: "Serena Insert After Symbol",
+		description: "Insert content after a known symbol definition using Serena symbol-aware editing.",
+		promptSnippet: "Insert code after a known symbol definition",
+		promptGuidelines: ["Use serena_insert_after_symbol for adding sibling/helper symbols after a located symbol."],
+		parameters: insertSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "insert_after_symbol", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_rename_symbol",
+		label: "Serena Rename Symbol",
+		description: "Rename a symbol across the codebase using Serena language-server refactoring.",
+		promptSnippet: "Semantic rename of a known symbol across references",
+		promptGuidelines: ["Use serena_rename_symbol for cross-file code renames after finding the exact symbol and references."],
+		parameters: renameSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "rename_symbol", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_safe_delete_symbol",
+		label: "Serena Safe Delete Symbol",
+		description: "Delete a symbol only if Serena finds no remaining references.",
+		promptSnippet: "Safely delete an unreferenced symbol",
+		promptGuidelines: ["Use serena_safe_delete_symbol instead of text deletion when remaining references matter."],
+		parameters: safeDeleteSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "safe_delete_symbol", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_search_for_pattern",
+		label: "Serena Search Pattern",
+		description: "Search project files through Serena with project-aware path filtering.",
+		promptSnippet: "Search for a text or regex pattern using Serena",
+		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) {
+			return callSerena(ctx, "search_for_pattern", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_replace_content",
+		label: "Serena Replace Content",
+		description: "Replace file content through Serena when symbol-aware editing is not the right boundary.",
+		promptSnippet: "Perform a Serena content replacement in a project file",
+		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) {
+			return callSerena(ctx, "replace_content", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_restart_language_server",
+		label: "Serena Restart Language Server",
+		description: "Restart Serena's language server for the active project when diagnostics/symbol data are stale.",
+		promptSnippet: "Restart the Serena language server",
+		promptGuidelines: ["Use serena_restart_language_server when Serena symbol retrieval appears stale or language-server diagnostics are stuck."],
+		parameters: emptyToolSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "restart_language_server", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_get_current_config",
+		label: "Serena Current Config",
+		description: "Show Serena's current project/configuration details.",
+		promptSnippet: "Inspect Serena project, context, modes, tools, and backend configuration",
+		promptGuidelines: ["Use serena_get_current_config when project activation, contexts, modes, or tool availability are unclear."],
+		parameters: emptyToolSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "get_current_config", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_check_onboarding_performed",
+		label: "Serena Check Onboarding",
+		description: "Check whether Serena onboarding memories exist for this project.",
+		promptSnippet: "Check whether project onboarding was already performed",
+		promptGuidelines: ["Use serena_check_onboarding_performed before relying on Serena project memories."],
+		parameters: emptyToolSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "check_onboarding_performed", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_onboarding",
+		label: "Serena Onboarding",
+		description: "Run Serena's onboarding prompt for collecting project memories.",
+		promptSnippet: "Start Serena project onboarding",
+		promptGuidelines: ["Use serena_onboarding only when project onboarding has not been performed or the user asks to refresh it."],
+		parameters: emptyToolSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "onboarding", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_list_memories",
+		label: "Serena List Memories",
+		description: "List Serena project memories available for the active project.",
+		promptSnippet: "List available Serena memories",
+		promptGuidelines: ["Use serena_list_memories before reading Serena memories relevant to a task."],
+		parameters: emptyToolSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "list_memories", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_read_memory",
+		label: "Serena Read Memory",
+		description: "Read a named Serena project memory.",
+		promptSnippet: "Read a Serena project memory by name",
+		promptGuidelines: ["Use serena_read_memory only for memories that are relevant to the current task."],
+		parameters: memoryNameSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "read_memory", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_write_memory",
+		label: "Serena Write Memory",
+		description: "Write a named Serena project memory.",
+		promptSnippet: "Write durable Serena project memory content",
+		promptGuidelines: ["Use serena_write_memory after onboarding or when durable verified project knowledge should be available to Serena."],
+		parameters: writeMemorySchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "write_memory", params);
+		},
+	});
+
+	pi.registerTool({
+		name: "serena_delete_memory",
+		label: "Serena Delete Memory",
+		description: "Delete a named Serena project memory when the user explicitly asks.",
+		promptSnippet: "Delete a Serena project memory by name",
+		promptGuidelines: ["Use serena_delete_memory only when the user explicitly asks to remove a Serena memory."],
+		parameters: memoryNameSchema,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			return callSerena(ctx, "delete_memory", params);
+		},
+	});
+
+	pi.registerCommand("serena-status", {
+		description: "Show Serena worker status",
+		handler: async (args, ctx) => {
+			const project = args?.trim() || process.cwd();
+			const response = await getWorker(ctx).request({ action: "status", project, context: DEFAULT_CONTEXT, includeAgent: true });
+			ctx.ui.notify(JSON.stringify(response, null, 2), response.ok ? "info" : "error");
+		},
+	});
+
+	pi.registerCommand("serena-dashboard", {
+		description: "Open the Serena dashboard for the current project",
+		handler: async (args, ctx) => {
+			const project = args?.trim() || process.cwd();
+			const response = await getWorker(ctx).request({ action: "dashboard", project, context: DEFAULT_CONTEXT, open: true });
+			if (response.ok) {
+				const opened = response.opened ? "opened" : "available";
+				ctx.ui.notify(`Serena dashboard ${opened}: ${response.dashboardUrl ?? "dashboard URL unavailable"}`, "info");
+			} else {
+				ctx.ui.notify(resultText(response), "error");
+			}
+		},
+	});
+
+	pi.registerCommand("serena-restart", {
+		description: "Restart the persistent Serena worker",
+		handler: async (_args, ctx) => {
+			getWorker(ctx).restart();
+			ctx.ui.notify("Restarted Serena worker", "info");
+		},
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		const prompt = event.prompt.toLowerCase();
+		if (/\b(find references|rename|refactor|symbol|declaration|implementation|diagnostic|large repo|semantic|class|method|function)\b/.test(prompt)) {
+			return {
+				systemPrompt:
+					event.systemPrompt +
+					"\n\nSerena semantic tools are available as Pi-native tools. For symbol lookup, references, semantic code navigation, whole-symbol edits, safe deletion, or cross-file renames, prefer serena_* tools before repeated grep/read/edit operations. Use normal Pi tools for small exact text edits and non-code files.",
+			};
+		}
+	});
+
+	pi.on("tool_call", async (event) => {
+		if (event.toolName.startsWith("serena_")) {
+			semanticMissCount = 0;
+			return;
+		}
+
+		let looksLikeSemanticMiss = false;
+		if (event.toolName === "read") {
+			const input = event.input as Record<string, unknown>;
+			looksLikeSemanticMiss = pathLooksLikeCode(input.path) && !pathLooksNonSemantic(input.path);
+		} else if (event.toolName === "bash") {
+			const command = (event.input as Record<string, unknown>)?.command;
+			looksLikeSemanticMiss = typeof command === "string" && commandLooksLikeSemanticCodeSearch(command);
+		}
+
+		if (!looksLikeSemanticMiss) return;
+		semanticMissCount += 1;
+		if (semanticMissCount >= 4) {
+			semanticMissCount = 0;
+			pi.sendMessage(
+				{
+					customType: "serena-reminder",
+					content:
+						"Reminder: Serena semantic tools are available for code-symbol work. If you are searching code for symbols, references, declarations, implementations, or refactor targets, switch to serena_find_symbol / serena_get_symbols_overview / serena_find_referencing_symbols instead of more grep/read calls. Normal read/search tools are still appropriate for Markdown, JSON/YAML, docs, and exact text edits.",
+					display: true,
+				},
+				{ deliverAs: "steer", triggerTurn: true },
+			);
+		}
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		await worker?.stop();
+		worker = undefined;
+		ctx.ui.setStatus("serena", undefined);
+	});
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@bacnh85/pi-serena",
+  "version": "0.1.0",
+  "description": "Pi extension that provides Serena semantic code tools through a persistent worker.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/bacnh85/skills#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bacnh85/skills.git",
+    "directory": "extensions/pi-serena"
+  },
+  "bugs": {
+    "url": "https://github.com/bacnh85/skills/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "serena",
+    "semantic-code"
+  ],
+  "files": [
+    "README.md",
+    "index.ts",
+    "worker.ts"
+  ],
+  "pi": {
+    "extensions": [
+      "."
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}

package/worker.ts

@@ -0,0 +1,347 @@
+import { spawn, spawnSync, type ChildProcessWithoutNullStreams } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type SerenaWorkerResponse = {
+	id: string | null;
+	ok: boolean;
+	result?: string;
+	error?: string;
+	[key: string]: unknown;
+};
+
+type Pending = {
+	resolve: (value: SerenaWorkerResponse) => void;
+	reject: (error: Error) => void;
+	timer: NodeJS.Timeout;
+};
+
+function piConfigDirs(): string[] {
+	return process.env.PI_CODING_AGENT_DIR ? [process.env.PI_CODING_AGENT_DIR] : [path.join(os.homedir(), ".pi", "agent"), path.join(os.homedir(), ".pi", "agents")];
+}
+
+function loadEnv(cwd = process.cwd()): void {
+	for (const file of [path.resolve(cwd, ".env.local"), path.resolve(cwd, ".env"), ...piConfigDirs().flatMap((dir) => [path.join(dir, ".env.local"), path.join(dir, ".env")])]) {
+		let text: string;
+		try { text = fs.readFileSync(file, "utf8"); } catch (error: any) { if (error?.code === "ENOENT") continue; throw error; }
+		for (const rawLine of text.split(/\r?\n/)) {
+			const line = rawLine.trim();
+			if (!line || line.startsWith("#")) continue;
+			const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+			if (!match || process.env[match[1]] !== undefined) continue;
+			process.env[match[1]] = match[2].trim().replace(/^[\'\"]|[\'\"]$/g, "");
+		}
+	}
+}
+
+const PYTHON_BRIDGE = String.raw`
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import sys
+import traceback
+from typing import Any
+
+os.environ.setdefault("SERENA_USAGE_REPORTING", "false")
+
+try:
+    from serena.agent import SerenaAgent
+    from serena.config.context_mode import SerenaAgentContext
+    from serena.config.serena_config import SerenaConfig
+except Exception as exc:
+    print(json.dumps({"id": None, "ok": False, "error": f"Failed to import Serena: {type(exc).__name__}: {exc}"}), flush=True)
+    raise
+
+try:
+    from serena import serena_version
+except Exception:
+    serena_version = lambda: "unknown"  # type: ignore
+
+agents: dict[str, SerenaAgent] = {}
+
+def env_flag(name: str, default: bool) -> bool:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def load_bridge_config() -> SerenaConfig:
+    config = SerenaConfig.from_config_file()
+    # Pi keeps one worker per process/session. Keep dashboard available by default,
+    # but do not open browser tabs unless explicitly requested.
+    config.web_dashboard = env_flag("SERENA_BRIDGE_WEB_DASHBOARD", True)
+    config.web_dashboard_open_on_launch = env_flag("SERENA_BRIDGE_OPEN_DASHBOARD", False)
+    return config
+
+
+def classify_error(message: str) -> str:
+    if "Tool named" in message and "not found" in message:
+        return "missing_tool"
+    if "not active" in message:
+        return "inactive_tool"
+    if "No active project" in message or "Project" in message and "not found" in message:
+        return "project_error"
+    if "Cannot extract symbols" in message or "Active languages" in message or "language server" in message or "LSP" in message:
+        return "language_server_error"
+    if "Timeout" in message or "timed out" in message:
+        return "timeout"
+    return "serena_error"
+
+def respond(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload, ensure_ascii=False), flush=True)
+
+
+def agent_key(project: str, context: str) -> str:
+    return f"{os.path.abspath(project)}\0{context}"
+
+
+def get_agent(project: str, context: str) -> SerenaAgent:
+    key = agent_key(project, context)
+    agent = agents.get(key)
+    if agent is None:
+        with contextlib.redirect_stdout(sys.stderr):
+            agent = SerenaAgent(project=project, context=SerenaAgentContext.load(context), serena_config=load_bridge_config())
+        agents[key] = agent
+    return agent
+
+
+def close_agents() -> None:
+    for key, agent in list(agents.items()):
+        try:
+            agent.on_shutdown()
+        except Exception as exc:
+            print(f"Error shutting down Serena agent {key}: {exc}", file=sys.stderr, flush=True)
+    agents.clear()
+
+
+def handle(req: dict[str, Any]) -> dict[str, Any]:
+    req_id = req.get("id")
+    action = req.get("action")
+
+    if action == "shutdown":
+        close_agents()
+        return {"id": req_id, "ok": True, "shutdown": True}
+
+    if action == "status":
+        project = str(req.get("project") or os.getcwd())
+        context = str(req.get("context") or "ide")
+        data: dict[str, Any] = {
+            "id": req_id,
+            "ok": True,
+            "version": serena_version(),
+            "pid": os.getpid(),
+            "cachedAgents": len(agents),
+            "project": os.path.abspath(project),
+            "context": context,
+        }
+        if req.get("includeAgent"):
+            agent = get_agent(project, context)
+            data["activeTools"] = agent.get_active_tool_names()
+            active_project = agent.get_active_project()
+            data["activeProject"] = str(active_project.project_root) if active_project else None
+            data["languageBackend"] = agent.get_language_backend().value
+            data["dashboardUrl"] = agent.get_dashboard_url()
+        return data
+
+    if action == "dashboard":
+        project = str(req.get("project") or os.getcwd())
+        context = str(req.get("context") or "ide")
+        agent = get_agent(project, context)
+        opened = bool(req.get("open")) and agent.open_dashboard()
+        return {"id": req_id, "ok": True, "opened": opened, "dashboardUrl": agent.get_dashboard_url()}
+
+    if action == "call":
+        project = str(req.get("project") or os.getcwd())
+        context = str(req.get("context") or "ide")
+        tool_name = req.get("tool")
+        params = req.get("params") or {}
+        if not isinstance(tool_name, str) or not tool_name:
+            raise ValueError("call request requires non-empty string field 'tool'")
+        if not isinstance(params, dict):
+            raise ValueError("call request field 'params' must be an object")
+        agent = get_agent(project, context)
+        with contextlib.redirect_stdout(sys.stderr):
+            result = agent.get_tool_by_name(tool_name).apply_ex(**params)
+        # Serena's apply_ex catches many tool failures and returns an "Error: ..." string.
+        if isinstance(result, str) and result.startswith("Error"):
+            return {"id": req_id, "ok": False, "tool": tool_name, "errorType": classify_error(result), "error": result, "result": result}
+        return {"id": req_id, "ok": True, "tool": tool_name, "result": result}
+
+    raise ValueError(f"Unknown action: {action}")
+
+
+def main() -> int:
+    try:
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            req_id = None
+            try:
+                req = json.loads(line)
+                if not isinstance(req, dict):
+                    raise ValueError("request must be a JSON object")
+                req_id = req.get("id")
+                response = handle(req)
+                respond(response)
+                if req.get("action") == "shutdown":
+                    return 0
+            except Exception as exc:
+                message = f"{type(exc).__name__}: {exc}"
+                print(traceback.format_exc(), file=sys.stderr, flush=True)
+                respond({"id": req_id, "ok": False, "errorType": classify_error(message), "error": message})
+    finally:
+        close_agents()
+    return 0
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+`;
+
+function runSync(command: string, args: string[]): string | undefined {
+	try {
+		const result = spawnSync(command, args, { encoding: "utf8" });
+		if (result.status === 0) return String(result.stdout).trim().replace(/\u001b\[[0-9;]*m/g, "");
+	} catch {
+		// ignore discovery failures
+	}
+	return undefined;
+}
+
+function serenaPythonCandidates(): string[] {
+	const candidates: string[] = [];
+	const configured = process.env.SERENA_PYTHON;
+	if (configured) candidates.push(configured);
+
+	const addToolDirCandidates = (toolDir: string | undefined) => {
+		if (!toolDir) return;
+		candidates.push(
+			path.join(toolDir, "serena-agent", "Scripts", "python.exe"),
+			path.join(toolDir, "serena-agent", "bin", "python"),
+		);
+	};
+
+	addToolDirCandidates(runSync("uv", ["tool", "dir"]));
+
+	const uvFromBash = runSync("bash", ["-lc", "command -v uv"]);
+	if (uvFromBash) addToolDirCandidates(runSync(uvFromBash, ["tool", "dir"]));
+
+	addToolDirCandidates(path.join(os.homedir(), ".local", "share", "uv", "tools"));
+	addToolDirCandidates(path.join(os.homedir(), "AppData", "Roaming", "uv", "tools"));
+
+	return [...new Set(candidates)];
+}
+
+function findSerenaPython(): string | undefined {
+	return serenaPythonCandidates().find((candidate) => fs.existsSync(candidate));
+}
+
+export class SerenaWorkerClient {
+	private process?: ChildProcessWithoutNullStreams;
+	private buffer = "";
+	private nextId = 1;
+	private pending = new Map<string, Pending>();
+	private generation = 0;
+
+	constructor(private readonly onStatus?: (text: string | undefined) => void) {}
+
+	async request(payload: Record<string, unknown>, timeoutMs = 120_000): Promise<SerenaWorkerResponse> {
+		this.ensureStarted();
+		const id = String(this.nextId++);
+		const request = { id, ...payload };
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(new Error(`Serena worker request timed out: ${payload.action ?? "unknown"}`));
+			}, timeoutMs);
+			this.pending.set(id, { resolve, reject, timer });
+			this.process!.stdin.write(`${JSON.stringify(request)}\n`);
+		});
+	}
+
+	async stop(): Promise<void> {
+		const proc = this.process;
+		if (!proc) return;
+		try {
+			await this.request({ action: "shutdown" }, 10_000).catch(() => undefined);
+		} finally {
+			proc.kill();
+			this.process = undefined;
+			this.onStatus?.(undefined);
+		}
+	}
+
+	restart(): void {
+		if (this.process) this.process.kill();
+		this.failAll(new Error("Serena worker restarted"));
+		this.process = undefined;
+		this.ensureStarted();
+	}
+
+	private ensureStarted(): void {
+		if (this.process && !this.process.killed) return;
+		loadEnv();
+		const python = findSerenaPython();
+		if (!python) {
+			const checked = serenaPythonCandidates().map((candidate) => `- ${candidate}`).join("\n") || "- none";
+			throw new Error(
+				`Could not find Serena Python. Install with: uv tool install -p 3.13 serena-agent && serena init, or set SERENA_PYTHON to the serena-agent Python executable. Checked:\n${checked}`
+			);
+		}
+
+		this.generation += 1;
+		const proc = spawn(python, ["-u", "-c", PYTHON_BRIDGE], {
+			env: { ...process.env, SERENA_USAGE_REPORTING: process.env.SERENA_USAGE_REPORTING ?? "false" },
+			stdio: "pipe",
+		});
+		this.process = proc;
+		this.buffer = "";
+		this.onStatus?.(`Serena worker pid ${proc.pid} gen ${this.generation}`);
+
+		proc.stdout.on("data", (chunk) => this.onStdout(String(chunk)));
+		proc.stderr.on("data", (chunk) => process.stderr.write(`[serena-worker] ${String(chunk)}`));
+		proc.on("exit", (code, signal) => {
+			if (this.process === proc) {
+				this.process = undefined;
+				this.onStatus?.(undefined);
+			}
+			this.failAll(new Error(`Serena worker exited code=${code} signal=${signal}`));
+		});
+	}
+
+	private onStdout(chunk: string): void {
+		this.buffer += chunk;
+		let index: number;
+		while ((index = this.buffer.indexOf("\n")) >= 0) {
+			const line = this.buffer.slice(0, index).trim();
+			this.buffer = this.buffer.slice(index + 1);
+			if (!line) continue;
+			let response: SerenaWorkerResponse;
+			try {
+				response = JSON.parse(line) as SerenaWorkerResponse;
+			} catch {
+				process.stderr.write(`[serena-worker] non-json stdout: ${line}\n`);
+				continue;
+			}
+			const id = response.id;
+			if (!id) continue;
+			const pending = this.pending.get(id);
+			if (!pending) continue;
+			this.pending.delete(id);
+			clearTimeout(pending.timer);
+			pending.resolve(response);
+		}
+	}
+
+	private failAll(error: Error): void {
+		for (const [id, pending] of this.pending) {
+			clearTimeout(pending.timer);
+			pending.reject(error);
+			this.pending.delete(id);
+		}
+	}
+}