@oh-my-pi/pi-coding-agent 5.5.0 → 5.6.7

package/src/core/tools/index.ts

@@ -24,6 +24,7 @@ export {
 } from "./lsp/index";
 export { createNotebookTool, type NotebookToolDetails } from "./notebook";
 export { createOutputTool, type OutputToolDetails } from "./output";
+export { createPythonTool, type PythonToolDetails } from "./python";
 export { createReadTool, type ReadToolDetails } from "./read";
 export { reportFindingTool, type SubmitReviewDetails } from "./review";
 export { createSshTool, type SSHToolDetails } from "./ssh";
@@ -63,6 +64,9 @@ export { createWriteTool, type WriteToolDetails } from "./write";
 
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import type { EventBus } from "../event-bus";
+import { logger } from "../logger";
+import { getPreludeDocs, warmPythonEnvironment } from "../python-executor";
+import { checkPythonKernelAvailability } from "../python-kernel";
 import type { BashInterceptorRule } from "../settings-manager";
 import { createAskTool } from "./ask";
 import { createBashTool } from "./bash";
@@ -76,6 +80,7 @@ import { createLsTool } from "./ls";
 import { createLspTool } from "./lsp/index";
 import { createNotebookTool } from "./notebook";
 import { createOutputTool } from "./output";
+import { createPythonTool } from "./python";
 import { createReadTool } from "./read";
 import { reportFindingTool } from "./review";
 import { createSshTool } from "./ssh";
@@ -129,6 +134,9 @@ export interface ToolSession {
 		getBashInterceptorEnabled(): boolean;
 		getBashInterceptorSimpleLsEnabled(): boolean;
 		getBashInterceptorRules(): BashInterceptorRule[];
+		getPythonToolMode?(): "ipy-only" | "bash-only" | "both";
+		getPythonKernelMode?(): "session" | "per-call";
+		getPythonSharedGateway?(): boolean;
 	};
 }
 
@@ -137,6 +145,7 @@ type ToolFactory = (session: ToolSession) => Tool | null | Promise<Tool | null>;
 export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	ask: createAskTool,
 	bash: createBashTool,
+	python: createPythonTool,
 	calc: createCalculatorTool,
 	ssh: createSshTool,
 	edit: createEditTool,
@@ -162,6 +171,36 @@ export const HIDDEN_TOOLS: Record<string, ToolFactory> = {
 
 export type ToolName = keyof typeof BUILTIN_TOOLS;
 
+export type PythonToolMode = "ipy-only" | "bash-only" | "both";
+
+/**
+ * Parse OMP_PY environment variable to determine Python tool mode.
+ * Returns null if not set or invalid.
+ *
+ * Values:
+ * - "0" or "bash" → bash-only
+ * - "1" or "py" → ipy-only
+ * - "mix" or "both" → both
+ */
+function getPythonModeFromEnv(): PythonToolMode | null {
+	const value = process.env.OMP_PY?.toLowerCase();
+	if (!value) return null;
+
+	switch (value) {
+		case "0":
+		case "bash":
+			return "bash-only";
+		case "1":
+		case "py":
+			return "ipy-only";
+		case "mix":
+		case "both":
+			return "both";
+		default:
+			return null;
+	}
+}
+
 /**
  * Create tools from BUILTIN_TOOLS registry.
  */
@@ -169,8 +208,51 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 	const includeComplete = session.requireCompleteTool === true;
 	const enableLsp = session.enableLsp ?? true;
 	const requestedTools = toolNames && toolNames.length > 0 ? [...new Set(toolNames)] : undefined;
+	const pythonMode = getPythonModeFromEnv() ?? session.settings?.getPythonToolMode?.() ?? "ipy-only";
+	let pythonAvailable = true;
+	const shouldCheckPython =
+		pythonMode !== "bash-only" &&
+		(requestedTools === undefined || requestedTools.includes("python") || pythonMode === "ipy-only");
+	const isTestEnv = process.env.BUN_ENV === "test" || process.env.NODE_ENV === "test";
+	if (shouldCheckPython) {
+		const availability = await checkPythonKernelAvailability(session.cwd);
+		pythonAvailable = availability.ok;
+		if (!availability.ok) {
+			logger.warn("Python kernel unavailable, falling back to bash", {
+				reason: availability.reason,
+			});
+		} else if (!isTestEnv && getPreludeDocs().length === 0) {
+			const sessionFile = session.getSessionFile?.() ?? undefined;
+			const warmSessionId = sessionFile ? `session:${sessionFile}:workdir:${session.cwd}` : `cwd:${session.cwd}`;
+			void warmPythonEnvironment(session.cwd, warmSessionId, session.settings?.getPythonSharedGateway?.()).catch(
+				(err) => {
+					logger.warn("Failed to warm Python environment", {
+						error: err instanceof Error ? err.message : String(err),
+					});
+				},
+			);
+		}
+	}
+
+	const effectiveMode = pythonAvailable ? pythonMode : "bash-only";
+	const allowBash = effectiveMode !== "ipy-only";
+	const allowPython = effectiveMode !== "bash-only";
+	if (
+		requestedTools &&
+		allowBash &&
+		!allowPython &&
+		requestedTools.includes("python") &&
+		!requestedTools.includes("bash")
+	) {
+		requestedTools.push("bash");
+	}
 	const allTools: Record<string, ToolFactory> = { ...BUILTIN_TOOLS, ...HIDDEN_TOOLS };
-	const isToolAllowed = (name: string) => (name === "lsp" ? enableLsp : true);
+	const isToolAllowed = (name: string) => {
+		if (name === "lsp") return enableLsp;
+		if (name === "bash") return allowBash;
+		if (name === "python") return allowPython;
+		return true;
+	};
 	if (includeComplete && requestedTools && !requestedTools.includes("complete")) {
 		requestedTools.push("complete");
 	}

package/src/core/tools/python-execution.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import * as pythonExecutor from "../python-executor";
+import type { ToolSession } from "./index";
+import { createPythonTool } from "./python";
+
+function createSession(cwd: string): ToolSession {
+	return {
+		cwd,
+		hasUI: false,
+		getSessionFile: () => "session-file",
+		getSessionSpawns: () => "*",
+		settings: {
+			getImageAutoResize: () => true,
+			getLspFormatOnWrite: () => true,
+			getLspDiagnosticsOnWrite: () => true,
+			getLspDiagnosticsOnEdit: () => false,
+			getEditFuzzyMatch: () => true,
+			getGitToolEnabled: () => true,
+			getBashInterceptorEnabled: () => true,
+			getBashInterceptorSimpleLsEnabled: () => true,
+			getBashInterceptorRules: () => [],
+			getPythonToolMode: () => "ipy-only",
+			getPythonKernelMode: () => "per-call",
+		},
+	};
+}
+
+describe("python tool execution", () => {
+	it("passes kernel options from settings and args", async () => {
+		const tempDir = mkdtempSync(join(tmpdir(), "python-tool-"));
+		const executeSpy = vi.spyOn(pythonExecutor, "executePython").mockResolvedValue({
+			output: "ok",
+			exitCode: 0,
+			cancelled: false,
+			truncated: false,
+			displayOutputs: [],
+			stdinRequested: false,
+		});
+
+		const tool = createPythonTool(createSession(tempDir));
+		const result = await tool.execute(
+			"call-id",
+			{ code: "print('hi')", timeout: 5, workdir: tempDir, reset: true },
+			undefined,
+			undefined,
+			undefined,
+		);
+
+		expect(executeSpy).toHaveBeenCalledWith(
+			"print('hi')",
+			expect.objectContaining({
+				cwd: tempDir,
+				timeout: 5000,
+				sessionId: `session:session-file:workdir:${tempDir}`,
+				kernelMode: "per-call",
+				reset: true,
+			}),
+		);
+		const text = result.content.find((item) => item.type === "text")?.text;
+		expect(text).toBe("ok");
+
+		executeSpy.mockRestore();
+		rmSync(tempDir, { recursive: true, force: true });
+	});
+});

package/src/core/tools/python-fallback.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from "bun:test";
+import * as pythonKernelModule from "../python-kernel";
+import type { ToolSession } from "./index";
+import { createTools } from "./index";
+
+function createTestSession(overrides: Partial<ToolSession> = {}): ToolSession {
+	return {
+		cwd: "/tmp/test",
+		hasUI: false,
+		getSessionFile: () => null,
+		getSessionSpawns: () => "*",
+		...overrides,
+	};
+}
+
+function createBaseSettings(overrides: Partial<NonNullable<ToolSession["settings"]>> = {}) {
+	return {
+		getImageAutoResize: () => true,
+		getLspFormatOnWrite: () => true,
+		getLspDiagnosticsOnWrite: () => true,
+		getLspDiagnosticsOnEdit: () => false,
+		getEditFuzzyMatch: () => true,
+		getGitToolEnabled: () => true,
+		getBashInterceptorEnabled: () => true,
+		getBashInterceptorSimpleLsEnabled: () => true,
+		getBashInterceptorRules: () => [],
+		...overrides,
+	};
+}
+
+describe("createTools python fallback", () => {
+	it("falls back to bash-only when kernel unavailable", async () => {
+		const availabilitySpy = vi
+			.spyOn(pythonKernelModule, "checkPythonKernelAvailability")
+			.mockResolvedValue({ ok: false, reason: "unavailable" });
+
+		const session = createTestSession({
+			settings: createBaseSettings({
+				getPythonToolMode: () => "ipy-only",
+				getPythonKernelMode: () => "session",
+			}),
+		});
+
+		const tools = await createTools(session, ["python"]);
+		const names = tools.map((tool) => tool.name).sort();
+
+		expect(names).toEqual(["bash"]);
+
+		availabilitySpy.mockRestore();
+	});
+
+	it("keeps bash when python mode is both but unavailable", async () => {
+		const availabilitySpy = vi
+			.spyOn(pythonKernelModule, "checkPythonKernelAvailability")
+			.mockResolvedValue({ ok: false, reason: "unavailable" });
+
+		const session = createTestSession({
+			settings: createBaseSettings({
+				getPythonToolMode: () => "both",
+				getPythonKernelMode: () => "session",
+			}),
+		});
+
+		const tools = await createTools(session);
+		const names = tools.map((tool) => tool.name);
+
+		expect(names).toContain("bash");
+		expect(names).not.toContain("python");
+
+		availabilitySpy.mockRestore();
+	});
+});

package/src/core/tools/python-renderer.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test";
+import stripAnsi from "strip-ansi";
+import { getThemeByName } from "../../modes/interactive/theme/theme";
+import { pythonToolRenderer } from "./python";
+import { truncateTail } from "./truncate";
+
+describe("pythonToolRenderer", () => {
+	it("renders truncated output when collapsed and full output when expanded", () => {
+		const theme = getThemeByName("dark");
+		expect(theme).toBeDefined();
+		const uiTheme = theme!;
+
+		const fullOutput = ["line 1", "line 2", "line 3", "line 4"].join("\n");
+		const truncation = truncateTail(fullOutput, { maxLines: 2, maxBytes: 128 });
+
+		const result = {
+			content: [{ type: "text", text: truncation.content }],
+			details: {
+				truncation,
+				fullOutput,
+			},
+		};
+
+		const collapsed = pythonToolRenderer.renderResult(result, { expanded: false, isPartial: false }, uiTheme);
+		const collapsedLines = stripAnsi(collapsed.render(80).join("\n"));
+		expect(collapsedLines).toContain("line 4");
+		expect(collapsedLines).not.toContain("line 1");
+		expect(collapsedLines).toContain("Truncated:");
+
+		const expanded = pythonToolRenderer.renderResult(result, { expanded: true, isPartial: false }, uiTheme);
+		const expandedLines = stripAnsi(expanded.render(80).join("\n"));
+		expect(expandedLines).toContain("line 1");
+		expect(expandedLines).toContain("line 4");
+		expect(expandedLines).not.toContain("Truncated:");
+	});
+});

package/src/core/tools/python-tool-mode.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "bun:test";
+import { createTools, type ToolSession } from "./index";
+
+function createSession(overrides: Partial<ToolSession> = {}): ToolSession {
+	return {
+		cwd: "/tmp/test",
+		hasUI: false,
+		getSessionFile: () => null,
+		getSessionSpawns: () => "*",
+		settings: {
+			getImageAutoResize: () => true,
+			getLspFormatOnWrite: () => true,
+			getLspDiagnosticsOnWrite: () => true,
+			getLspDiagnosticsOnEdit: () => false,
+			getEditFuzzyMatch: () => true,
+			getGitToolEnabled: () => true,
+			getBashInterceptorEnabled: () => true,
+			getBashInterceptorSimpleLsEnabled: () => true,
+			getBashInterceptorRules: () => [],
+			getPythonToolMode: () => "bash-only",
+			getPythonKernelMode: () => "session",
+		},
+		...overrides,
+	};
+}
+
+describe("createTools python fallback", () => {
+	it("falls back to bash when python is requested but disabled", async () => {
+		const previous = process.env.OMP_PYTHON_SKIP_CHECK;
+		process.env.OMP_PYTHON_SKIP_CHECK = "1";
+		const session = createSession();
+		const tools = await createTools(session, ["python"]);
+		const names = tools.map((tool) => tool.name);
+
+		expect(names).toEqual(["bash"]);
+
+		if (previous === undefined) {
+			delete process.env.OMP_PYTHON_SKIP_CHECK;
+		} else {
+			process.env.OMP_PYTHON_SKIP_CHECK = previous;
+		}
+	});
+});

package/src/core/tools/python.test.ts

@@ -0,0 +1,121 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from "bun:test";
+import * as pythonExecutor from "../python-executor";
+import { createTools, type ToolSession } from "./index";
+import { createPythonTool } from "./python";
+
+let previousSkipCheck: string | undefined;
+
+beforeAll(() => {
+	previousSkipCheck = process.env.OMP_PYTHON_SKIP_CHECK;
+	process.env.OMP_PYTHON_SKIP_CHECK = "1";
+});
+
+afterAll(() => {
+	if (previousSkipCheck === undefined) {
+		delete process.env.OMP_PYTHON_SKIP_CHECK;
+		return;
+	}
+	process.env.OMP_PYTHON_SKIP_CHECK = previousSkipCheck;
+});
+
+function createSession(overrides: Partial<ToolSession> = {}): ToolSession {
+	return {
+		cwd: "/tmp/test",
+		hasUI: false,
+		getSessionFile: () => null,
+		getSessionSpawns: () => "*",
+		...overrides,
+	};
+}
+
+function createSettings(toolMode: "ipy-only" | "bash-only" | "both") {
+	return {
+		getImageAutoResize: () => true,
+		getLspFormatOnWrite: () => true,
+		getLspDiagnosticsOnWrite: () => true,
+		getLspDiagnosticsOnEdit: () => false,
+		getEditFuzzyMatch: () => true,
+		getGitToolEnabled: () => true,
+		getBashInterceptorEnabled: () => true,
+		getBashInterceptorSimpleLsEnabled: () => true,
+		getBashInterceptorRules: () => [],
+		getPythonToolMode: () => toolMode,
+		getPythonKernelMode: () => "session" as const,
+	};
+}
+
+describe("python tool schema", () => {
+	it("exposes expected parameters", () => {
+		const tool = createPythonTool(createSession());
+		const schema = tool.parameters as {
+			type: string;
+			properties: Record<string, { type: string; description?: string }>;
+			required?: string[];
+		};
+
+		expect(schema.type).toBe("object");
+		expect(schema.properties.code.type).toBe("string");
+		expect(schema.properties.timeout.type).toBe("number");
+		expect(schema.properties.workdir.type).toBe("string");
+		expect(schema.properties.reset.type).toBe("boolean");
+		expect(schema.required).toEqual(["code"]);
+	});
+});
+
+describe("python tool docs template", () => {
+	it("renders dynamic helper docs", () => {
+		const docs = [
+			{
+				name: "read",
+				signature: "(path)",
+				docstring: "Read file contents.",
+				category: "File I/O",
+			},
+		];
+		const spy = vi.spyOn(pythonExecutor, "getPreludeDocs").mockReturnValue(docs);
+
+		const tool = createPythonTool(createSession());
+
+		expect(tool.description).toContain("### File I/O");
+		expect(tool.description).toContain("read(path)");
+		expect(tool.description).toContain("Read file contents.");
+
+		spy.mockRestore();
+	});
+
+	it("renders fallback when docs are unavailable", () => {
+		const spy = vi.spyOn(pythonExecutor, "getPreludeDocs").mockReturnValue([]);
+
+		const tool = createPythonTool(createSession());
+
+		expect(tool.description).toContain("Documentation unavailable — Python kernel failed to start");
+
+		spy.mockRestore();
+	});
+});
+
+describe("python tool exposure", () => {
+	it("includes python only in ipy-only mode", async () => {
+		const session = createSession({ settings: createSettings("ipy-only") });
+		const tools = await createTools(session);
+		const names = tools.map((tool) => tool.name);
+		expect(names).toContain("python");
+		expect(names).not.toContain("bash");
+	});
+
+	it("includes bash only in bash-only mode", async () => {
+		const session = createSession({ settings: createSettings("bash-only") });
+		const tools = await createTools(session);
+		const names = tools.map((tool) => tool.name);
+		expect(names).toContain("bash");
+		expect(names).not.toContain("python");
+	});
+
+	it("includes bash and python in both mode", async () => {
+		const session = createSession({ settings: createSettings("both") });
+		const tools = await createTools(session);
+		const names = tools.map((tool) => tool.name);
+		expect(names).toContain("bash");
+		expect(names).toContain("python");
+	});
+});