@oh-my-pi/pi-coding-agent 7.0.0 → 8.0.0

package/src/{core/tools → tools}/python.ts

@@ -4,17 +4,22 @@ import type { ImageContent } from "@oh-my-pi/pi-ai";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text, truncateToWidth, visibleWidth } from "@oh-my-pi/pi-tui";
 import { type Static, Type } from "@sinclair/typebox";
-import { truncateToVisualLines } from "../../modes/interactive/components/visual-truncate";
-import { highlightCode, type Theme } from "../../modes/interactive/theme/theme";
-import pythonDescription from "../../prompts/tools/python.md" with { type: "text" };
-import type { RenderResultOptions } from "../custom-tools/types";
-import { renderPromptTemplate } from "../prompt-templates";
-import { executePython, getPreludeDocs, type PythonExecutorOptions } from "../python-executor";
-import type { PreludeHelper, PythonStatusEvent } from "../python-kernel";
+import { renderPromptTemplate } from "$c/config/prompt-templates";
+import type { RenderResultOptions } from "$c/extensibility/custom-tools/types";
+import { executePython, getPreludeDocs, type PythonExecutorOptions } from "$c/ipy/executor";
+import type { PreludeHelper, PythonStatusEvent } from "$c/ipy/kernel";
+import { truncateToVisualLines } from "$c/modes/components/visual-truncate";
+import { highlightCode, type Theme } from "$c/modes/theme/theme";
+import pythonDescription from "$c/prompts/tools/python.md" with { type: "text" };
+import { OutputSink, type OutputSummary } from "$c/session/streaming-output";
+import type { OutputMeta } from "$c/tools/output-meta";
+import { ToolAbortError, ToolError } from "$c/tools/tool-errors";
 import type { ToolSession } from "./index";
+import { allocateOutputArtifact, createTailBuffer } from "./output-utils";
 import { resolveToCwd } from "./path-utils";
 import { getTreeBranch, getTreeContinuePrefix, shortenPath, ToolUIKit, truncate } from "./render-utils";
-import { DEFAULT_MAX_BYTES, formatTailTruncationNotice, type TruncationResult, truncateTail } from "./truncate";
+import { toolResult } from "./tool-result";
+import { DEFAULT_MAX_BYTES } from "./truncate";
 
 export const PYTHON_DEFAULT_PREVIEW_LINES = 10;
 
@@ -41,22 +46,14 @@ function groupPreludeHelpers(helpers: PreludeHelper[]): PreludeCategory[] {
 export const pythonSchema = Type.Object({
 	cells: Type.Array(
 		Type.Object({
-			code: Type.String({
-				description:
-					"Python code for this cell. Keep it focused (imports, helper, test, use). No narrative text—put explanations in the assistant message or in the cell title.",
-			}),
-			title: Type.Optional(
-				Type.String({ description: "Short label for the cell (e.g., 'imports', 'parse helper')." }),
-			),
+			code: Type.String({ description: "Python code to execute" }),
+			title: Type.Optional(Type.String({ description: "Cell label, e.g. 'imports', 'helper'" })),
 		}),
-		{
-			description:
-				"Python cells to execute sequentially. Each cell runs in the same kernel—imports and variables persist. Keep cells small: one logical step each (import, define, test, use). If a cell fails, fix only that cell; earlier cells' state remains.",
-		},
+		{ description: "Cells to execute sequentially in persistent kernel" },
 	),
-	timeoutMs: Type.Optional(Type.Number({ description: "Timeout in milliseconds (default: 30000)" })),
-	cwd: Type.Optional(Type.String({ description: "Working directory for the command (default: current directory)" })),
-	reset: Type.Optional(Type.Boolean({ description: "Restart the kernel before executing this code" })),
+	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (default: 30)" })),
+	cwd: Type.Optional(Type.String({ description: "Working directory (default: cwd)" })),
+	reset: Type.Optional(Type.Boolean({ description: "Restart kernel before execution" })),
 });
 export type PythonToolParams = Static<typeof pythonSchema>;
 
@@ -80,14 +77,13 @@ export interface PythonCellResult {
 
 export interface PythonToolDetails {
 	cells?: PythonCellResult[];
-	truncation?: TruncationResult;
-	fullOutputPath?: string;
-	fullOutput?: string;
 	jsonOutputs?: unknown[];
 	images?: ImageContent[];
 	/** Structured status events from prelude helpers */
 	statusEvents?: PythonStatusEvent[];
 	isError?: boolean;
+	/** Structured output metadata for notices */
+	meta?: OutputMeta;
 }
 
 function formatJsonScalar(value: unknown): string {
@@ -171,17 +167,31 @@ export class PythonTool implements AgentTool<typeof pythonSchema> {
 		}
 
 		if (!this.session) {
-			throw new Error("Python tool requires a session when not using proxy executor");
+			throw new ToolError("Python tool requires a session when not using proxy executor");
 		}
 
-		const { cells, timeoutMs = 30000, cwd, reset } = params;
+		const { cells, timeout: rawTimeout = 30, cwd, reset } = params;
+		// Auto-convert milliseconds to seconds if value > 1000 (16+ min is unreasonable)
+		let timeoutSec = rawTimeout > 1000 ? rawTimeout / 1000 : rawTimeout;
+		// Clamp to reasonable range: 1s - 600s (10 min)
+		timeoutSec = Math.max(1, Math.min(600, timeoutSec));
+		const timeoutMs = timeoutSec * 1000;
 		const controller = new AbortController();
 		const onAbort = () => controller.abort();
 		signal?.addEventListener("abort", onAbort, { once: true });
+		let outputSink: OutputSink | undefined;
+		let outputSummary: OutputSummary | undefined;
+		let outputDumped = false;
+		const finalizeOutput = async (): Promise<OutputSummary | undefined> => {
+			if (outputDumped || !outputSink) return outputSummary;
+			outputSummary = await outputSink.dump();
+			outputDumped = true;
+			return outputSummary;
+		};
 
 		try {
 			if (signal?.aborted) {
-				throw new Error("Aborted");
+				throw new ToolAbortError();
 			}
 
 			const commandCwd = cwd ? resolveToCwd(cwd, this.session.cwd) : this.session.cwd;
@@ -189,15 +199,13 @@ export class PythonTool implements AgentTool<typeof pythonSchema> {
 			try {
 				cwdStat = await Bun.file(commandCwd).stat();
 			} catch {
-				throw new Error(`Working directory does not exist: ${commandCwd}`);
+				throw new ToolError(`Working directory does not exist: ${commandCwd}`);
 			}
 			if (!cwdStat.isDirectory()) {
-				throw new Error(`Working directory is not a directory: ${commandCwd}`);
+				throw new ToolError(`Working directory is not a directory: ${commandCwd}`);
 			}
 
-			const maxTailBytes = DEFAULT_MAX_BYTES * 2;
-			const tailChunks: Array<{ text: string; bytes: number }> = [];
-			let tailBytes = 0;
+			const tailBuffer = createTailBuffer(DEFAULT_MAX_BYTES * 2);
 			const jsonOutputs: unknown[] = [];
 			const images: ImageContent[] = [];
 			const statusEvents: PythonStatusEvent[] = [];
@@ -210,34 +218,18 @@ export class PythonTool implements AgentTool<typeof pythonSchema> {
 				status: "pending",
 			}));
 			const cellOutputs: string[] = [];
-			let lastFullOutputPath: string | undefined;
 
 			const appendTail = (text: string) => {
-				if (!text) return;
-				const chunkBytes = Buffer.byteLength(text, "utf-8");
-				tailChunks.push({ text, bytes: chunkBytes });
-				tailBytes += chunkBytes;
-				while (tailBytes > maxTailBytes && tailChunks.length > 1) {
-					const removed = tailChunks.shift();
-					if (removed) {
-						tailBytes -= removed.bytes;
-					}
-				}
+				tailBuffer.append(text);
 			};
 
-			const buildUpdateDetails = (truncation?: TruncationResult): PythonToolDetails => {
+			const buildUpdateDetails = (): PythonToolDetails => {
 				const details: PythonToolDetails = {
 					cells: cellResults.map((cell) => ({
 						...cell,
 						statusEvents: cell.statusEvents ? [...cell.statusEvents] : undefined,
 					})),
 				};
-				if (truncation) {
-					details.truncation = truncation;
-				}
-				if (lastFullOutputPath) {
-					details.fullOutputPath = lastFullOutputPath;
-				}
 				if (jsonOutputs.length > 0) {
 					details.jsonOutputs = jsonOutputs;
 				}
@@ -252,15 +244,24 @@ export class PythonTool implements AgentTool<typeof pythonSchema> {
 
 			const pushUpdate = () => {
 				if (!onUpdate) return;
-				const tailText = tailChunks.map((entry) => entry.text).join("");
-				const truncation = truncateTail(tailText);
+				const tailText = tailBuffer.text();
 				onUpdate({
-					content: [{ type: "text", text: truncation.content || "" }],
-					details: buildUpdateDetails(truncation.truncated ? truncation : undefined),
+					content: [{ type: "text", text: tailText }],
+					details: buildUpdateDetails(),
 				});
 			};
 
 			const sessionFile = this.session.getSessionFile?.() ?? undefined;
+			const artifactsDir = this.session.getArtifactsDir?.() ?? undefined;
+			const { artifactPath, artifactId } = await allocateOutputArtifact(this.session, "python");
+			outputSink = new OutputSink({
+				artifactPath,
+				artifactId,
+				onChunk: (chunk) => {
+					appendTail(chunk);
+					pushUpdate();
+				},
+			});
 			const sessionId = sessionFile ? `session:${sessionFile}:cwd:${commandCwd}` : `cwd:${commandCwd}`;
 			const baseExecutorOptions: Omit<PythonExecutorOptions, "reset"> = {
 				cwd: commandCwd,
@@ -270,6 +271,7 @@ export class PythonTool implements AgentTool<typeof pythonSchema> {
 				kernelMode: this.session.settings?.getPythonKernelMode?.() ?? "session",
 				useSharedGateway: this.session.settings?.getPythonSharedGateway?.() ?? true,
 				sessionFile: sessionFile ?? undefined,
+				artifactsDir: artifactsDir ?? undefined,
 			};
 
 			for (let i = 0; i < cells.length; i++) {
@@ -286,6 +288,9 @@ export class PythonTool implements AgentTool<typeof pythonSchema> {
 				const executorOptions: PythonExecutorOptions = {
 					...baseExecutorOptions,
 					reset: isFirstCell ? reset : false,
+					onChunk: async (chunk) => {
+						await outputSink!.push(chunk);
+					},
 				};
 
 				const startTime = Date.now();
@@ -306,10 +311,6 @@ export class PythonTool implements AgentTool<typeof pythonSchema> {
 					}
 				}
 
-				if (result.fullOutputPath) {
-					lastFullOutputPath = result.fullOutputPath;
-				}
-
 				const cellOutput = result.output.trim();
 				cellResult.output = cellOutput;
 				cellResult.exitCode = result.exitCode;
@@ -340,14 +341,14 @@ export class PythonTool implements AgentTool<typeof pythonSchema> {
 					cellResult.status = "error";
 					pushUpdate();
 					const errorMsg = result.output || "Command aborted";
-					throw new Error(cells.length > 1 ? `Cell ${i + 1} aborted: ${errorMsg}` : errorMsg);
+					throw new ToolError(cells.length > 1 ? `Cell ${i + 1} aborted: ${errorMsg}` : errorMsg);
 				}
 
 				if (result.exitCode !== 0 && result.exitCode !== undefined) {
 					cellResult.status = "error";
 					pushUpdate();
 					const combinedOutput = cellOutputs.join("\n\n");
-					throw new Error(
+					throw new ToolError(
 						cells.length > 1
 							? `${combinedOutput}\n\nCell ${i + 1} failed (exit code ${result.exitCode}). Earlier cells succeeded—their state persists. Fix only cell ${i + 1}.`
 							: `${combinedOutput}\n\nCommand exited with code ${result.exitCode}`,
@@ -359,29 +360,49 @@ export class PythonTool implements AgentTool<typeof pythonSchema> {
 			}
 
 			const combinedOutput = cellOutputs.join("\n\n");
-			const truncation = truncateTail(combinedOutput);
-			let outputText =
-				truncation.content || (jsonOutputs.length > 0 || images.length > 0 ? "(no text output)" : "(no output)");
+			const outputText =
+				combinedOutput || (jsonOutputs.length > 0 || images.length > 0 ? "(no text output)" : "(no output)");
+			const rawSummary = (await finalizeOutput()) ?? {
+				output: "",
+				truncated: false,
+				totalLines: 0,
+				totalBytes: 0,
+				outputLines: 0,
+				outputBytes: 0,
+			};
+			const outputLines = combinedOutput.length > 0 ? combinedOutput.split("\n").length : 0;
+			const outputBytes = Buffer.byteLength(combinedOutput, "utf-8");
+			const missingLines = Math.max(0, rawSummary.totalLines - rawSummary.outputLines);
+			const missingBytes = Math.max(0, rawSummary.totalBytes - rawSummary.outputBytes);
+			const summaryForMeta: OutputSummary = {
+				output: combinedOutput,
+				truncated: rawSummary.truncated,
+				totalLines: outputLines + missingLines,
+				totalBytes: outputBytes + missingBytes,
+				outputLines,
+				outputBytes,
+				artifactId: rawSummary.artifactId,
+			};
 
 			const details: PythonToolDetails = {
 				cells: cellResults,
-				fullOutputPath: lastFullOutputPath,
 				jsonOutputs: jsonOutputs.length > 0 ? jsonOutputs : undefined,
 				images: images.length > 0 ? images : undefined,
 				statusEvents: statusEvents.length > 0 ? statusEvents : undefined,
 			};
 
-			if (truncation.truncated) {
-				details.truncation = truncation;
-				outputText += formatTailTruncationNotice(truncation, {
-					fullOutputPath: lastFullOutputPath,
-					originalContent: combinedOutput,
-				});
-			}
+			const resultBuilder = toolResult(details)
+				.text(outputText)
+				.truncationFromSummary(summaryForMeta, { direction: "tail" });
 
-			return { content: [{ type: "text", text: outputText }], details };
+			return resultBuilder.done();
 		} finally {
 			signal?.removeEventListener("abort", onAbort);
+			if (!outputDumped) {
+				try {
+					await finalizeOutput();
+				} catch {}
+			}
 		}
 	}
 }
@@ -955,8 +976,6 @@ export const pythonToolRenderer = {
 		const expanded = renderContext?.expanded ?? options.expanded;
 		const previewLines = renderContext?.previewLines ?? PYTHON_DEFAULT_PREVIEW_LINES;
 		const output = renderContext?.output ?? (result.content?.find((c) => c.type === "text")?.text ?? "").trim();
-		const fullOutput = details?.fullOutput;
-		const showingFullOutput = expanded && fullOutput !== undefined;
 
 		const jsonOutputs = details?.jsonOutputs ?? [];
 		const jsonLines = jsonOutputs.flatMap((value, index) => {
@@ -965,27 +984,24 @@ export const pythonToolRenderer = {
 			return [header, ...treeLines];
 		});
 
-		const truncation = details?.truncation;
-		const fullOutputPath = details?.fullOutputPath;
+		const truncation = details?.meta?.truncation;
 		const timeoutSeconds = renderContext?.timeout;
 		const timeoutLine =
 			typeof timeoutSeconds === "number"
 				? uiTheme.fg("dim", ui.wrapBrackets(`Timeout: ${timeoutSeconds}s`))
 				: undefined;
 		let warningLine: string | undefined;
-		if (fullOutputPath || (truncation?.truncated && !showingFullOutput)) {
+		if (truncation) {
 			const warnings: string[] = [];
-			if (fullOutputPath) {
-				warnings.push(`Full output: ${fullOutputPath}`);
+			if (truncation.artifactId) {
+				warnings.push(`Full output: artifact://${truncation.artifactId}`);
 			}
-			if (truncation?.truncated && !showingFullOutput) {
-				if (truncation.truncatedBy === "lines") {
-					warnings.push(`Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines`);
-				} else {
-					warnings.push(
-						`Truncated: ${truncation.outputLines} lines shown (${ui.formatBytes(truncation.maxBytes)} limit)`,
-					);
-				}
+			if (truncation.truncatedBy === "lines") {
+				warnings.push(`Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines`);
+			} else {
+				warnings.push(
+					`Truncated: ${truncation.outputLines} lines shown (${ui.formatBytes(truncation.outputBytes)} limit)`,
+				);
 			}
 			if (warnings.length > 0) {
 				warningLine = uiTheme.fg("warning", ui.wrapBrackets(warnings.join(". ")));
@@ -1038,7 +1054,7 @@ export const pythonToolRenderer = {
 			};
 		}
 
-		const displayOutput = expanded ? (fullOutput ?? output) : output;
+		const displayOutput = output;
 		const combinedOutput = [displayOutput, ...jsonLines].filter(Boolean).join("\n");
 
 		const statusEvents = details?.statusEvents ?? [];