@ottocode/sdk 0.1.279 → 0.1.280

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ottocode/sdk",
-	"version": "0.1.279",
+	"version": "0.1.280",
 	"description": "AI agent SDK for building intelligent assistants - tree-shakable and comprehensive",
 	"author": "nitishxyz",
 	"license": "MIT",

package/src/core/src/tools/builtin/fs/copy-attachment.ts

@@ -0,0 +1,196 @@
+import { createHash } from 'node:crypto';
+import { copyFile, mkdir, readFile, stat } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import { createToolError, type ToolResponse } from '../../error.ts';
+import { expandTilde, isAbsoluteLike, resolveSafePath } from './util.ts';
+import { rememberFileWrite } from './read-tracker.ts';
+import DESCRIPTION from './copy-attachment.txt' with { type: 'text' };
+
+type AttachmentMetadata = {
+	id: string;
+	filename: string;
+	mimeType: string;
+	size: number;
+	sha256: string;
+	kind: 'image' | 'pdf' | 'text' | 'binary';
+	originalPath: string;
+	createdAt: string;
+};
+
+const ATTACHMENTS_DIR = '.otto/attachments';
+const MIME_EXTENSIONS: Record<string, string[]> = {
+	'image/png': ['.png'],
+	'image/jpeg': ['.jpg', '.jpeg'],
+	'image/jpg': ['.jpg', '.jpeg'],
+	'image/gif': ['.gif'],
+	'image/webp': ['.webp'],
+	'image/svg+xml': ['.svg'],
+	'image/bmp': ['.bmp'],
+	'image/avif': ['.avif'],
+	'application/pdf': ['.pdf'],
+};
+
+function getExpectedExtensions(mimeType: string): string[] {
+	return MIME_EXTENSIONS[mimeType.toLowerCase().split(';', 1)[0].trim()] ?? [];
+}
+
+function replaceExtension(path: string, extension: string): string {
+	return extname(path)
+		? path.replace(/\.[^/.]*$/, extension)
+		: `${path}${extension}`;
+}
+
+async function readAttachmentMetadata(
+	projectRoot: string,
+	attachmentId: string,
+): Promise<AttachmentMetadata> {
+	const metadataPath = join(
+		projectRoot,
+		ATTACHMENTS_DIR,
+		attachmentId,
+		'metadata.json',
+	);
+	const raw = await readFile(metadataPath, 'utf-8');
+	return JSON.parse(raw) as AttachmentMetadata;
+}
+
+export function buildCopyAttachmentTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const copyAttachment = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			attachmentId: z
+				.string()
+				.describe('Attachment id from the current chat, e.g. att_...'),
+			targetPath: z
+				.string()
+				.describe('Project-relative destination path for the original file.'),
+			overwrite: z
+				.boolean()
+				.optional()
+				.default(false)
+				.describe('Overwrite the target path if it already exists.'),
+			createDirs: z
+				.boolean()
+				.optional()
+				.default(true)
+				.describe('Create parent directories for the target path.'),
+		}),
+		async execute({
+			attachmentId,
+			targetPath,
+			overwrite,
+			createDirs,
+		}: {
+			attachmentId: string;
+			targetPath: string;
+			overwrite?: boolean;
+			createDirs?: boolean;
+		}): Promise<
+			ToolResponse<{
+				attachmentId: string;
+				path: string;
+				filename: string;
+				mimeType: string;
+				bytes: number;
+				sha256: string;
+				created: boolean;
+				requestedPath?: string;
+				extensionAdjusted?: boolean;
+			}>
+		> {
+			if (!attachmentId || attachmentId.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: attachmentId',
+					'validation',
+					{ parameter: 'attachmentId' },
+				);
+			}
+			if (!targetPath || targetPath.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: targetPath',
+					'validation',
+					{ parameter: 'targetPath' },
+				);
+			}
+
+			const requestedPath = expandTilde(targetPath);
+			if (isAbsoluteLike(requestedPath)) {
+				return createToolError(
+					`Refusing to copy outside project root: ${requestedPath}. Use a relative path within the project.`,
+					'permission',
+					{
+						parameter: 'targetPath',
+						value: requestedPath,
+						suggestion: 'Use a relative path within the project',
+					},
+				);
+			}
+
+			try {
+				const metadata = await readAttachmentMetadata(
+					projectRoot,
+					attachmentId,
+				);
+				const source = join(projectRoot, metadata.originalPath);
+				const expectedExtensions = getExpectedExtensions(metadata.mimeType);
+				const targetExtension = extname(requestedPath).toLowerCase();
+				const preferredExtension = expectedExtensions[0];
+				const req =
+					preferredExtension && !expectedExtensions.includes(targetExtension)
+						? replaceExtension(requestedPath, preferredExtension)
+						: requestedPath;
+				const extensionAdjusted = req !== requestedPath;
+				const target = resolveSafePath(projectRoot, req);
+				try {
+					await stat(target);
+					if (!overwrite) {
+						return createToolError(
+							`Target file already exists: ${req}`,
+							'validation',
+							{
+								parameter: 'targetPath',
+								value: req,
+								suggestion:
+									'Choose a different target path or set overwrite to true',
+							},
+						);
+					}
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+				}
+
+				if (createDirs) {
+					await mkdir(dirname(target), { recursive: true });
+				}
+				await copyFile(source, target);
+				await rememberFileWrite(projectRoot, target);
+				const bytes = await readFile(target);
+				const sha256 = createHash('sha256').update(bytes).digest('hex');
+				return {
+					ok: true,
+					attachmentId,
+					path: req,
+					...(extensionAdjusted ? { requestedPath } : {}),
+					extensionAdjusted,
+					filename: metadata.filename,
+					mimeType: metadata.mimeType,
+					bytes: bytes.byteLength,
+					sha256,
+					created: true,
+				};
+			} catch (error) {
+				return createToolError(
+					`Failed to copy attachment: ${error instanceof Error ? error.message : String(error)}`,
+					'execution',
+					{ parameter: 'attachmentId', value: attachmentId },
+				);
+			}
+		},
+	});
+	return { name: 'copy_attachment_to_project', tool: copyAttachment };
+}

package/src/core/src/tools/builtin/fs/copy-attachment.txt

@@ -0,0 +1,9 @@
+Copy an original uploaded chat attachment into the project.
+
+Use this when the user drops/uploads a file and asks you to add it to the repo. The copied bytes are the untouched original upload, not the compressed image sent to the model.
+
+Rules:
+- `targetPath` must be project-relative and cannot escape the project root.
+- Existing files are not overwritten unless `overwrite: true` is provided.
+- For known file types, the tool uses the original MIME type to ensure the final extension is correct. For example, if `targetPath` is `.jpg` but the upload is `image/png`, the file is written as `.png` and the returned `path` is the actual path.
+- Prefer sensible asset paths such as `public/`, `src/assets/`, or an existing app asset directory.

package/src/core/src/tools/builtin/fs/index.ts

@@ -1,9 +1,11 @@
 import type { Tool } from 'ai';
 import { buildEditTool } from './edit.ts';
 import { buildReadTool } from './read.ts';
+import { buildReadImageTool } from './read-image.ts';
 import { buildMultiEditTool } from './multiedit.ts';
 import { buildWriteTool } from './write.ts';
 import { buildCopyIntoTool } from './copy-into.ts';
+import { buildCopyAttachmentTool } from './copy-attachment.ts';
 import { buildLsTool } from './ls.ts';
 import { buildTreeTool } from './tree.ts';
 import { buildPwdTool } from './pwd.ts';
@@ -14,10 +16,12 @@ export function buildFsTools(
 ): Array<{ name: string; tool: Tool }> {
 	const out: Array<{ name: string; tool: Tool }> = [];
 	out.push(buildReadTool(projectRoot));
+	out.push(buildReadImageTool(projectRoot));
 	out.push(buildEditTool(projectRoot));
 	out.push(buildMultiEditTool(projectRoot));
 	out.push(buildWriteTool(projectRoot));
 	out.push(buildCopyIntoTool(projectRoot));
+	out.push(buildCopyAttachmentTool(projectRoot));
 	out.push(buildLsTool(projectRoot));
 	out.push(buildTreeTool(projectRoot));
 	out.push(buildPwdTool());

package/src/core/src/tools/builtin/fs/read-image.ts

@@ -0,0 +1,381 @@
+import { createHash } from 'node:crypto';
+import { extname } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import { createToolError, type ToolResponse } from '../../error.ts';
+import { expandTilde, isAbsoluteLike, resolveSafePath } from './util.ts';
+import DESCRIPTION from './read-image.txt' with { type: 'text' };
+
+type BunImageMetadata = {
+	width?: number;
+	height?: number;
+	format?: string;
+};
+
+type BunImagePipeline = {
+	metadata(): Promise<BunImageMetadata>;
+	resize(
+		width: number,
+		height?: number,
+		options?: {
+			fit?: 'inside';
+			withoutEnlargement?: boolean;
+		},
+	): BunImagePipeline;
+	jpeg(options?: { quality?: number }): BunImagePipeline;
+	bytes(): Promise<Uint8Array>;
+};
+
+type BunImageConstructor = new (
+	input: string | ArrayBuffer | Uint8Array | Blob,
+) => BunImagePipeline;
+
+type JsonValue =
+	| null
+	| boolean
+	| number
+	| string
+	| JsonValue[]
+	| { [key: string]: JsonValue };
+
+type ReadImageResult = {
+	ok: true;
+	path: string;
+	mediaType: string;
+	data: string;
+	size: number;
+	transmittedSize: number;
+	sha256: string;
+	compressed: boolean;
+	width?: number;
+	height?: number;
+};
+
+type PreparedImage = {
+	data: Uint8Array;
+	mediaType: string;
+	width?: number;
+	height?: number;
+	compressed: boolean;
+};
+
+type ReadImageInput = {
+	path: string;
+	maxEdge?: number;
+	quality?: number;
+	maxBytes?: number;
+};
+
+const DEFAULT_MAX_EDGE = 1568;
+const DEFAULT_QUALITY = 82;
+const DEFAULT_MAX_BYTES = 4 * 1024 * 1024;
+const JPEG_MEDIA_TYPE = 'image/jpeg';
+const SUPPORTED_IMAGE_TYPES = new Set([
+	'image/bmp',
+	'image/gif',
+	'image/jpeg',
+	'image/png',
+	'image/webp',
+]);
+const COMPRESSIBLE_IMAGE_TYPES = new Set([
+	'image/bmp',
+	'image/jpeg',
+	'image/png',
+	'image/webp',
+]);
+const MEDIA_TYPE_BY_EXTENSION: Record<string, string> = {
+	'.bmp': 'image/bmp',
+	'.gif': 'image/gif',
+	'.jpeg': 'image/jpeg',
+	'.jpg': 'image/jpeg',
+	'.png': 'image/png',
+	'.webp': 'image/webp',
+};
+
+function getBunImageConstructor(): BunImageConstructor | undefined {
+	return (Bun as typeof Bun & { Image?: BunImageConstructor }).Image;
+}
+
+function toJsonValue(value: unknown): JsonValue {
+	if (value === undefined) return null;
+	try {
+		return JSON.parse(JSON.stringify(value)) as JsonValue;
+	} catch {
+		return String(value);
+	}
+}
+
+function normalizeMediaType(mediaType: string | undefined): string | undefined {
+	const normalized = mediaType?.toLowerCase().split(';', 1)[0].trim();
+	return normalized === 'image/jpg' ? JPEG_MEDIA_TYPE : normalized;
+}
+
+function detectMediaType(
+	filePath: string,
+	data: Uint8Array,
+): string | undefined {
+	if (
+		data.length >= 8 &&
+		data[0] === 0x89 &&
+		data[1] === 0x50 &&
+		data[2] === 0x4e &&
+		data[3] === 0x47
+	) {
+		return 'image/png';
+	}
+	if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8) {
+		return JPEG_MEDIA_TYPE;
+	}
+	if (
+		data.length >= 12 &&
+		data[0] === 0x52 &&
+		data[1] === 0x49 &&
+		data[2] === 0x46 &&
+		data[3] === 0x46 &&
+		data[8] === 0x57 &&
+		data[9] === 0x45 &&
+		data[10] === 0x42 &&
+		data[11] === 0x50
+	) {
+		return 'image/webp';
+	}
+	if (
+		data.length >= 6 &&
+		data[0] === 0x47 &&
+		data[1] === 0x49 &&
+		data[2] === 0x46
+	) {
+		return 'image/gif';
+	}
+	if (data.length >= 2 && data[0] === 0x42 && data[1] === 0x4d) {
+		return 'image/bmp';
+	}
+	return normalizeMediaType(
+		MEDIA_TYPE_BY_EXTENSION[extname(filePath).toLowerCase()],
+	);
+}
+
+async function prepareImage(
+	input: Uint8Array,
+	mediaType: string,
+	options: Required<Pick<ReadImageInput, 'maxEdge' | 'quality'>>,
+): Promise<PreparedImage> {
+	const ImageConstructor = getBunImageConstructor();
+	if (!ImageConstructor || !COMPRESSIBLE_IMAGE_TYPES.has(mediaType)) {
+		return { data: input, mediaType, compressed: false };
+	}
+
+	try {
+		const image = new ImageConstructor(input);
+		const metadata = await image.metadata();
+		const width = metadata.width ?? 0;
+		const height = metadata.height ?? 0;
+		if (width <= 0 || height <= 0) {
+			return { data: input, mediaType, compressed: false };
+		}
+
+		const pipeline =
+			width > options.maxEdge || height > options.maxEdge
+				? image.resize(options.maxEdge, options.maxEdge, {
+						fit: 'inside',
+						withoutEnlargement: true,
+					})
+				: image;
+		const output = await pipeline.jpeg({ quality: options.quality }).bytes();
+
+		if (output.byteLength >= input.byteLength) {
+			return { data: input, mediaType, width, height, compressed: false };
+		}
+
+		return {
+			data: output,
+			mediaType: JPEG_MEDIA_TYPE,
+			width,
+			height,
+			compressed: true,
+		};
+	} catch {
+		return { data: input, mediaType, compressed: false };
+	}
+}
+
+/**
+ * Builds the read_image tool, which loads local image files and returns image
+ * content that vision-capable language models can inspect.
+ */
+export function buildReadImageTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const readImage = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			path: z
+				.string()
+				.describe(
+					"Image path. Relative to project root by default; absolute ('/...') and home ('~/...') paths are allowed.",
+				),
+			maxEdge: z
+				.number()
+				.int()
+				.min(1)
+				.max(4096)
+				.optional()
+				.describe(
+					'Maximum width or height for model submission. Defaults to 1568.',
+				),
+			quality: z
+				.number()
+				.int()
+				.min(1)
+				.max(100)
+				.optional()
+				.describe('JPEG quality when compression is used. Defaults to 82.'),
+			maxBytes: z
+				.number()
+				.int()
+				.min(1024)
+				.max(20 * 1024 * 1024)
+				.optional()
+				.describe(
+					'Maximum transmitted image bytes after compression. Defaults to 4 MiB.',
+				),
+		}),
+		async execute({
+			path,
+			maxEdge = DEFAULT_MAX_EDGE,
+			quality = DEFAULT_QUALITY,
+			maxBytes = DEFAULT_MAX_BYTES,
+		}: ReadImageInput): Promise<ToolResponse<ReadImageResult>> {
+			if (!path || path.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: path',
+					'validation',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Provide an image file path to read',
+					},
+				);
+			}
+
+			const req = expandTilde(path);
+			let abs: string;
+			try {
+				abs = isAbsoluteLike(req) ? req : resolveSafePath(projectRoot, req);
+			} catch (error) {
+				return createToolError(
+					`Invalid image path: ${error instanceof Error ? error.message : String(error)}`,
+					'validation',
+					{ parameter: 'path', value: req },
+				);
+			}
+
+			try {
+				const input = await readFile(abs);
+				if (input.byteLength === 0) {
+					return createToolError('Image file is empty', 'validation', {
+						parameter: 'path',
+						value: req,
+					});
+				}
+
+				const mediaType = detectMediaType(abs, input);
+				if (!mediaType || !SUPPORTED_IMAGE_TYPES.has(mediaType)) {
+					return createToolError(
+						`Unsupported image type: ${mediaType ?? 'unknown'}`,
+						'validation',
+						{
+							parameter: 'path',
+							value: req,
+							suggestion:
+								'Use PNG, JPEG, WebP, GIF, or BMP images with read_image',
+						},
+					);
+				}
+
+				const prepared = await prepareImage(input, mediaType, {
+					maxEdge,
+					quality,
+				});
+				if (prepared.data.byteLength > maxBytes) {
+					return createToolError(
+						`Image is too large after compression: ${prepared.data.byteLength} bytes`,
+						'validation',
+						{
+							parameter: 'maxBytes',
+							value: maxBytes,
+							suggestion:
+								'Increase maxBytes or lower maxEdge/quality for this image',
+						},
+					);
+				}
+
+				const result: ReadImageResult = {
+					ok: true,
+					path: req,
+					mediaType: prepared.mediaType,
+					data: Buffer.from(prepared.data).toString('base64'),
+					size: input.byteLength,
+					transmittedSize: prepared.data.byteLength,
+					sha256: createHash('sha256').update(input).digest('hex'),
+					compressed: prepared.compressed,
+				};
+				if (prepared.width) result.width = prepared.width;
+				if (prepared.height) result.height = prepared.height;
+				return result;
+			} catch (error) {
+				const isEnoent =
+					error &&
+					typeof error === 'object' &&
+					'code' in error &&
+					error.code === 'ENOENT';
+				return createToolError(
+					isEnoent
+						? `Image not found: ${req}`
+						: `Failed to read image: ${error instanceof Error ? error.message : String(error)}`,
+					isEnoent ? 'not_found' : 'execution',
+					{
+						parameter: 'path',
+						value: req,
+						suggestion: isEnoent
+							? 'Use ls or tree to find available images'
+							: undefined,
+					},
+				);
+			}
+		},
+		toModelOutput({ output }) {
+			const maybeResult = output as Partial<ReadImageResult>;
+			if (
+				maybeResult.ok !== true ||
+				typeof maybeResult.data !== 'string' ||
+				typeof maybeResult.mediaType !== 'string'
+			) {
+				return { type: 'json', value: toJsonValue(output) };
+			}
+
+			const dimensions =
+				typeof maybeResult.width === 'number' &&
+				typeof maybeResult.height === 'number'
+					? `, ${maybeResult.width}x${maybeResult.height}`
+					: '';
+			return {
+				type: 'content',
+				value: [
+					{
+						type: 'text',
+						text: `Image read from ${maybeResult.path} (${maybeResult.mediaType}${dimensions}, ${maybeResult.transmittedSize} bytes). Inspect the following image content.`,
+					},
+					{
+						type: 'image-data',
+						data: maybeResult.data,
+						mediaType: maybeResult.mediaType,
+					},
+				],
+			};
+		},
+	});
+	return { name: 'read_image', tool: readImage };
+}

package/src/core/src/tools/builtin/fs/read-image.txt

@@ -0,0 +1,5 @@
+- Read a local image file and send it to the language model as image content
+- Accepts project-relative paths by default; absolute and home paths are allowed
+- Uses Bun.Image to downscale/compress supported images before model submission when possible
+- Returns metadata plus the visual image payload; use when you need to inspect screenshots, icons, diagrams, or other images
+- For text files, use the read tool instead