@oh-my-pi/pi-mom 1.337.0

package/src/tools/read.ts

@@ -0,0 +1,165 @@
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { extname } from "path";
+import type { Executor } from "../sandbox.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateHead } from "./truncate.js";
+
+/**
+ * Map of file extensions to MIME types for common image formats
+ */
+const IMAGE_MIME_TYPES: Record<string, string> = {
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".png": "image/png",
+	".gif": "image/gif",
+	".webp": "image/webp",
+};
+
+/**
+ * Check if a file is an image based on its extension
+ */
+function isImageFile(filePath: string): string | null {
+	const ext = extname(filePath).toLowerCase();
+	return IMAGE_MIME_TYPES[ext] || null;
+}
+
+const readSchema = Type.Object({
+	label: Type.String({ description: "Brief description of what you're reading and why (shown to user)" }),
+	path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
+	offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+});
+
+interface ReadToolDetails {
+	truncation?: TruncationResult;
+}
+
+export function createReadTool(executor: Executor): AgentTool<typeof readSchema> {
+	return {
+		name: "read",
+		label: "read",
+		description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${
+			DEFAULT_MAX_BYTES / 1024
+		}KB (whichever is hit first). Use offset/limit for large files.`,
+		parameters: readSchema,
+		execute: async (
+			_toolCallId: string,
+			{ path, offset, limit }: { label: string; path: string; offset?: number; limit?: number },
+			signal?: AbortSignal,
+		): Promise<{ content: (TextContent | ImageContent)[]; details: ReadToolDetails | undefined }> => {
+			const mimeType = isImageFile(path);
+
+			if (mimeType) {
+				// Read as image (binary) - use base64
+				const result = await executor.exec(`base64 < ${shellEscape(path)}`, { signal });
+				if (result.code !== 0) {
+					throw new Error(result.stderr || `Failed to read file: ${path}`);
+				}
+				const base64 = result.stdout.replace(/\s/g, ""); // Remove whitespace from base64
+
+				return {
+					content: [
+						{ type: "text", text: `Read image file [${mimeType}]` },
+						{ type: "image", data: base64, mimeType },
+					],
+					details: undefined,
+				};
+			}
+
+			// Get total line count first
+			const countResult = await executor.exec(`wc -l < ${shellEscape(path)}`, { signal });
+			if (countResult.code !== 0) {
+				throw new Error(countResult.stderr || `Failed to read file: ${path}`);
+			}
+			const totalFileLines = Number.parseInt(countResult.stdout.trim(), 10) + 1; // wc -l counts newlines, not lines
+
+			// Apply offset if specified (1-indexed)
+			const startLine = offset ? Math.max(1, offset) : 1;
+			const startLineDisplay = startLine;
+
+			// Check if offset is out of bounds
+			if (startLine > totalFileLines) {
+				throw new Error(`Offset ${offset} is beyond end of file (${totalFileLines} lines total)`);
+			}
+
+			// Read content with offset
+			let cmd: string;
+			if (startLine === 1) {
+				cmd = `cat ${shellEscape(path)}`;
+			} else {
+				cmd = `tail -n +${startLine} ${shellEscape(path)}`;
+			}
+
+			const result = await executor.exec(cmd, { signal });
+			if (result.code !== 0) {
+				throw new Error(result.stderr || `Failed to read file: ${path}`);
+			}
+
+			let selectedContent = result.stdout;
+			let userLimitedLines: number | undefined;
+
+			// Apply user limit if specified
+			if (limit !== undefined) {
+				const lines = selectedContent.split("\n");
+				const endLine = Math.min(limit, lines.length);
+				selectedContent = lines.slice(0, endLine).join("\n");
+				userLimitedLines = endLine;
+			}
+
+			// Apply truncation (respects both line and byte limits)
+			const truncation = truncateHead(selectedContent);
+
+			let outputText: string;
+			let details: ReadToolDetails | undefined;
+
+			if (truncation.firstLineExceedsLimit) {
+				// First line at offset exceeds 50KB - tell model to use bash
+				const firstLineSize = formatSize(Buffer.byteLength(selectedContent.split("\n")[0], "utf-8"));
+				outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(
+					DEFAULT_MAX_BYTES,
+				)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;
+				details = { truncation };
+			} else if (truncation.truncated) {
+				// Truncation occurred - build actionable notice
+				const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
+				const nextOffset = endLineDisplay + 1;
+
+				outputText = truncation.content;
+
+				if (truncation.truncatedBy === "lines") {
+					outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue]`;
+				} else {
+					outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(
+						DEFAULT_MAX_BYTES,
+					)} limit). Use offset=${nextOffset} to continue]`;
+				}
+				details = { truncation };
+			} else if (userLimitedLines !== undefined) {
+				// User specified limit, check if there's more content
+				const linesFromStart = startLine - 1 + userLimitedLines;
+				if (linesFromStart < totalFileLines) {
+					const remaining = totalFileLines - linesFromStart;
+					const nextOffset = startLine + userLimitedLines;
+
+					outputText = truncation.content;
+					outputText += `\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue]`;
+				} else {
+					outputText = truncation.content;
+				}
+			} else {
+				// No truncation, no user limit exceeded
+				outputText = truncation.content;
+			}
+
+			return {
+				content: [{ type: "text", text: outputText }],
+				details,
+			};
+		},
+	};
+}
+
+function shellEscape(s: string): string {
+	return `'${s.replace(/'/g, "'\\''")}'`;
+}

package/src/tools/truncate.ts

@@ -0,0 +1,236 @@
+/**
+ * Shared truncation utilities for tool outputs.
+ *
+ * Truncation is based on two independent limits - whichever is hit first wins:
+ * - Line limit (default: 2000 lines)
+ * - Byte limit (default: 50KB)
+ *
+ * Never returns partial lines (except bash tail truncation edge case).
+ */
+
+export const DEFAULT_MAX_LINES = 2000;
+export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB
+
+export interface TruncationResult {
+	/** The truncated content */
+	content: string;
+	/** Whether truncation occurred */
+	truncated: boolean;
+	/** Which limit was hit: "lines", "bytes", or null if not truncated */
+	truncatedBy: "lines" | "bytes" | null;
+	/** Total number of lines in the original content */
+	totalLines: number;
+	/** Total number of bytes in the original content */
+	totalBytes: number;
+	/** Number of complete lines in the truncated output */
+	outputLines: number;
+	/** Number of bytes in the truncated output */
+	outputBytes: number;
+	/** Whether the last line was partially truncated (only for tail truncation edge case) */
+	lastLinePartial: boolean;
+	/** Whether the first line exceeded the byte limit (for head truncation) */
+	firstLineExceedsLimit: boolean;
+}
+
+export interface TruncationOptions {
+	/** Maximum number of lines (default: 2000) */
+	maxLines?: number;
+	/** Maximum number of bytes (default: 50KB) */
+	maxBytes?: number;
+}
+
+/**
+ * Format bytes as human-readable size.
+ */
+export function formatSize(bytes: number): string {
+	if (bytes < 1024) {
+		return `${bytes}B`;
+	} else if (bytes < 1024 * 1024) {
+		return `${(bytes / 1024).toFixed(1)}KB`;
+	} else {
+		return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+	}
+}
+
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Suitable for file reads where you want to see the beginning.
+ *
+ * Never returns partial lines. If first line exceeds byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ */
+export function truncateHead(content: string, options: TruncationOptions = {}): TruncationResult {
+	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+
+	const totalBytes = Buffer.byteLength(content, "utf-8");
+	const lines = content.split("\n");
+	const totalLines = lines.length;
+
+	// Check if no truncation needed
+	if (totalLines <= maxLines && totalBytes <= maxBytes) {
+		return {
+			content,
+			truncated: false,
+			truncatedBy: null,
+			totalLines,
+			totalBytes,
+			outputLines: totalLines,
+			outputBytes: totalBytes,
+			lastLinePartial: false,
+			firstLineExceedsLimit: false,
+		};
+	}
+
+	// Check if first line alone exceeds byte limit
+	const firstLineBytes = Buffer.byteLength(lines[0], "utf-8");
+	if (firstLineBytes > maxBytes) {
+		return {
+			content: "",
+			truncated: true,
+			truncatedBy: "bytes",
+			totalLines,
+			totalBytes,
+			outputLines: 0,
+			outputBytes: 0,
+			lastLinePartial: false,
+			firstLineExceedsLimit: true,
+		};
+	}
+
+	// Collect complete lines that fit
+	const outputLinesArr: string[] = [];
+	let outputBytesCount = 0;
+	let truncatedBy: "lines" | "bytes" = "lines";
+
+	for (let i = 0; i < lines.length && i < maxLines; i++) {
+		const line = lines[i];
+		const lineBytes = Buffer.byteLength(line, "utf-8") + (i > 0 ? 1 : 0); // +1 for newline
+
+		if (outputBytesCount + lineBytes > maxBytes) {
+			truncatedBy = "bytes";
+			break;
+		}
+
+		outputLinesArr.push(line);
+		outputBytesCount += lineBytes;
+	}
+
+	// If we exited due to line limit
+	if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+		truncatedBy = "lines";
+	}
+
+	const outputContent = outputLinesArr.join("\n");
+	const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+
+	return {
+		content: outputContent,
+		truncated: true,
+		truncatedBy,
+		totalLines,
+		totalBytes,
+		outputLines: outputLinesArr.length,
+		outputBytes: finalOutputBytes,
+		lastLinePartial: false,
+		firstLineExceedsLimit: false,
+	};
+}
+
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * Suitable for bash output where you want to see the end (errors, final results).
+ *
+ * May return partial first line if the last line of original content exceeds byte limit.
+ */
+export function truncateTail(content: string, options: TruncationOptions = {}): TruncationResult {
+	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+
+	const totalBytes = Buffer.byteLength(content, "utf-8");
+	const lines = content.split("\n");
+	const totalLines = lines.length;
+
+	// Check if no truncation needed
+	if (totalLines <= maxLines && totalBytes <= maxBytes) {
+		return {
+			content,
+			truncated: false,
+			truncatedBy: null,
+			totalLines,
+			totalBytes,
+			outputLines: totalLines,
+			outputBytes: totalBytes,
+			lastLinePartial: false,
+			firstLineExceedsLimit: false,
+		};
+	}
+
+	// Work backwards from the end
+	const outputLinesArr: string[] = [];
+	let outputBytesCount = 0;
+	let truncatedBy: "lines" | "bytes" = "lines";
+	let lastLinePartial = false;
+
+	for (let i = lines.length - 1; i >= 0 && outputLinesArr.length < maxLines; i--) {
+		const line = lines[i];
+		const lineBytes = Buffer.byteLength(line, "utf-8") + (outputLinesArr.length > 0 ? 1 : 0); // +1 for newline
+
+		if (outputBytesCount + lineBytes > maxBytes) {
+			truncatedBy = "bytes";
+			// Edge case: if we haven't added ANY lines yet and this line exceeds maxBytes,
+			// take the end of the line (partial)
+			if (outputLinesArr.length === 0) {
+				const truncatedLine = truncateStringToBytesFromEnd(line, maxBytes);
+				outputLinesArr.unshift(truncatedLine);
+				outputBytesCount = Buffer.byteLength(truncatedLine, "utf-8");
+				lastLinePartial = true;
+			}
+			break;
+		}
+
+		outputLinesArr.unshift(line);
+		outputBytesCount += lineBytes;
+	}
+
+	// If we exited due to line limit
+	if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+		truncatedBy = "lines";
+	}
+
+	const outputContent = outputLinesArr.join("\n");
+	const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+
+	return {
+		content: outputContent,
+		truncated: true,
+		truncatedBy,
+		totalLines,
+		totalBytes,
+		outputLines: outputLinesArr.length,
+		outputBytes: finalOutputBytes,
+		lastLinePartial,
+		firstLineExceedsLimit: false,
+	};
+}
+
+/**
+ * Truncate a string to fit within a byte limit (from the end).
+ * Handles multi-byte UTF-8 characters correctly.
+ */
+function truncateStringToBytesFromEnd(str: string, maxBytes: number): string {
+	const buf = Buffer.from(str, "utf-8");
+	if (buf.length <= maxBytes) {
+		return str;
+	}
+
+	// Start from the end, skip maxBytes back
+	let start = buf.length - maxBytes;
+
+	// Find a valid UTF-8 boundary (start of a character)
+	while (start < buf.length && (buf[start] & 0xc0) === 0x80) {
+		start++;
+	}
+
+	return buf.slice(start).toString("utf-8");
+}

package/src/tools/write.ts

@@ -0,0 +1,45 @@
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import { Type } from "@sinclair/typebox";
+import type { Executor } from "../sandbox.js";
+
+const writeSchema = Type.Object({
+	label: Type.String({ description: "Brief description of what you're writing (shown to user)" }),
+	path: Type.String({ description: "Path to the file to write (relative or absolute)" }),
+	content: Type.String({ description: "Content to write to the file" }),
+});
+
+export function createWriteTool(executor: Executor): AgentTool<typeof writeSchema> {
+	return {
+		name: "write",
+		label: "write",
+		description:
+			"Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+		parameters: writeSchema,
+		execute: async (
+			_toolCallId: string,
+			{ path, content }: { label: string; path: string; content: string },
+			signal?: AbortSignal,
+		) => {
+			// Create parent directories and write file using heredoc
+			const dir = path.includes("/") ? path.substring(0, path.lastIndexOf("/")) : ".";
+
+			// Use printf to handle content with special characters, pipe to file
+			// This avoids issues with heredoc and special characters
+			const cmd = `mkdir -p ${shellEscape(dir)} && printf '%s' ${shellEscape(content)} > ${shellEscape(path)}`;
+
+			const result = await executor.exec(cmd, { signal });
+			if (result.code !== 0) {
+				throw new Error(result.stderr || `Failed to write file: ${path}`);
+			}
+
+			return {
+				content: [{ type: "text", text: `Successfully wrote ${content.length} bytes to ${path}` }],
+				details: undefined,
+			};
+		},
+	};
+}
+
+function shellEscape(s: string): string {
+	return `'${s.replace(/'/g, "'\\''")}'`;
+}

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"outDir": "./dist",
+		"rootDir": "./src"
+	},
+	"include": ["src/**/*.ts"],
+	"exclude": ["node_modules", "dist", "**/*.d.ts", "src/**/*.d.ts"]
+}