@ottocode/sdk 0.1.235 → 0.1.237

package/package.json

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

package/src/config/src/manager.ts

@@ -9,6 +9,9 @@ import {
 import {
 	getGlobalConfigDir,
 	getGlobalConfigPath,
+	getGlobalDebugDir,
+	getGlobalDebugLogPath,
+	getGlobalDebugSessionsDir,
 	getLocalDataDir,
 	joinPath,
 } from './paths.ts';
@@ -20,6 +23,14 @@ import {
 
 export type Scope = 'global' | 'local';
 
+export type DebugConfig = {
+	enabled: boolean;
+	scopes: string[];
+	logPath: string;
+	sessionsDir: string;
+	debugDir: string;
+};
+
 export async function read(projectRoot?: string) {
 	const cfg = await loadConfig(projectRoot);
 	const auth = await getAllAuth(projectRoot);
@@ -111,6 +122,50 @@ export async function writeDefaults(
 	await Bun.write(globalPath, JSON.stringify(next, null, 2));
 }
 
+export async function readDebugConfig(
+	projectRoot?: string,
+): Promise<DebugConfig> {
+	const cfg = await loadConfig(projectRoot);
+	return {
+		enabled: cfg.debugEnabled === true,
+		scopes: Array.isArray(cfg.debugScopes)
+			? cfg.debugScopes.filter(
+					(scope): scope is string =>
+						typeof scope === 'string' && scope.trim().length > 0,
+				)
+			: [],
+		logPath: getGlobalDebugLogPath(),
+		sessionsDir: getGlobalDebugSessionsDir(),
+		debugDir: getGlobalDebugDir(),
+	};
+}
+
+export async function writeDebugConfig(
+	updates: Partial<{
+		enabled: boolean;
+		scopes: string[];
+	}>,
+) {
+	const globalPath = getGlobalConfigPath();
+	const existing = await readJsonFile(globalPath);
+	const next: Record<string, unknown> = { ...(existing ?? {}) };
+
+	if (updates.enabled !== undefined) {
+		next.debugEnabled = updates.enabled;
+	}
+
+	if (updates.scopes !== undefined) {
+		next.debugScopes = updates.scopes;
+	}
+
+	const base = getGlobalConfigDir();
+	try {
+		const { promises: fs } = await import('node:fs');
+		await fs.mkdir(base, { recursive: true }).catch(() => {});
+	} catch {}
+	await Bun.write(globalPath, JSON.stringify(next, null, 2));
+}
+
 async function readJsonFile(
 	filePath: string,
 ): Promise<Record<string, unknown> | undefined> {

package/src/config/src/paths.ts

@@ -79,6 +79,33 @@ export function getGlobalCommandsDir(): string {
 	return joinPath(getGlobalConfigDir(), 'commands');
 }
 
+export function getGlobalDebugDir(): string {
+	return joinPath(getGlobalConfigDir(), 'debug');
+}
+
+export function getGlobalDebugLogPath(): string {
+	return joinPath(getGlobalDebugDir(), 'latest.log');
+}
+
+export function getGlobalDebugSessionsDir(): string {
+	return joinPath(getGlobalDebugDir(), 'sessions');
+}
+
+export function getSessionDebugLogPath(sessionId: string): string {
+	return joinPath(getGlobalDebugSessionsDir(), `${sessionId}.log`);
+}
+
+export function getSessionDebugDetailsLogPath(sessionId: string): string {
+	return joinPath(getGlobalDebugSessionsDir(), `${sessionId}.details.log`);
+}
+
+export function getSessionSystemPromptPath(sessionId: string): string {
+	return joinPath(
+		getGlobalDebugSessionsDir(),
+		`${sessionId}.system-prompt.txt`,
+	);
+}
+
 export function getLocalDataDir(projectRoot: string): string {
 	return joinPath(projectRoot, '.otto');
 }

package/src/core/src/tools/builtin/fs/edit-shared.ts

@@ -0,0 +1,83 @@
+export function normalizeLineEndings(text: string): string {
+	return text.replace(/\r\n/g, '\n');
+}
+
+export function detectLineEnding(text: string): '\n' | '\r\n' {
+	return text.includes('\r\n') ? '\r\n' : '\n';
+}
+
+export function convertToLineEnding(
+	text: string,
+	lineEnding: '\n' | '\r\n',
+): string {
+	if (lineEnding === '\n') return text;
+	return text.replace(/\n/g, '\r\n');
+}
+
+function countOccurrences(content: string, search: string): number {
+	if (!search) return 0;
+	let count = 0;
+	let start = 0;
+	while (true) {
+		const index = content.indexOf(search, start);
+		if (index === -1) return count;
+		count += 1;
+		start = index + search.length;
+	}
+}
+
+export function applyStringEdit(
+	content: string,
+	oldString: string,
+	newString: string,
+	replaceAll = false,
+): { content: string; occurrences: number } {
+	if (oldString.length === 0) {
+		throw new Error(
+			'oldString must not be empty. Use write to create files or apply_patch for structural insertions.',
+		);
+	}
+	if (oldString === newString) {
+		throw new Error(
+			'No changes to apply: oldString and newString are identical.',
+		);
+	}
+
+	const lineEnding = detectLineEnding(content);
+	const normalizedOld = convertToLineEnding(
+		normalizeLineEndings(oldString),
+		lineEnding,
+	);
+	const normalizedNew = convertToLineEnding(
+		normalizeLineEndings(newString),
+		lineEnding,
+	);
+
+	const occurrences = countOccurrences(content, normalizedOld);
+	if (occurrences === 0) {
+		throw new Error(
+			'oldString not found in content. Read the file again and copy the exact text, including whitespace.',
+		);
+	}
+	if (occurrences > 1 && !replaceAll) {
+		throw new Error(
+			'Found multiple matches for oldString. Provide more surrounding lines to make it unique or set replaceAll to true.',
+		);
+	}
+
+	if (replaceAll) {
+		return {
+			content: content.split(normalizedOld).join(normalizedNew),
+			occurrences,
+		};
+	}
+
+	const index = content.indexOf(normalizedOld);
+	return {
+		content:
+			content.slice(0, index) +
+			normalizedNew +
+			content.slice(index + normalizedOld.length),
+		occurrences,
+	};
+}

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

@@ -0,0 +1,129 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import DESCRIPTION from './edit.txt' with { type: 'text' };
+import { buildWriteArtifact, isAbsoluteLike, resolveSafePath } from './util.ts';
+import { applyStringEdit } from './edit-shared.ts';
+import { assertFreshRead, rememberFileWrite } from './read-tracker.ts';
+import { createToolError, type ToolResponse } from '../../error.ts';
+
+export function buildEditTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const edit = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			path: z
+				.string()
+				.describe(
+					'Relative file path within the project. Absolute paths are not allowed.',
+				),
+			oldString: z.string().describe('Exact text to replace'),
+			newString: z.string().describe('Replacement text'),
+			replaceAll: z
+				.boolean()
+				.optional()
+				.default(false)
+				.describe(
+					'Replace every matching occurrence instead of requiring a unique match',
+				),
+		}),
+		async execute({
+			path,
+			oldString,
+			newString,
+			replaceAll = false,
+		}: {
+			path: string;
+			oldString: string;
+			newString: string;
+			replaceAll?: boolean;
+		}): Promise<
+			ToolResponse<{
+				path: string;
+				occurrences: number;
+				bytes: number;
+				artifact: unknown;
+			}>
+		> {
+			if (!path || path.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: path',
+					'validation',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Provide a relative file path to edit',
+					},
+				);
+			}
+			if (isAbsoluteLike(path)) {
+				return createToolError(
+					`Refusing to edit outside project root: ${path}`,
+					'permission',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Use a relative path within the project',
+					},
+				);
+			}
+
+			const abs = resolveSafePath(projectRoot, path);
+			try {
+				await assertFreshRead(projectRoot, abs, path);
+				const original = await readFile(abs, 'utf-8');
+				const updated = applyStringEdit(
+					original,
+					oldString,
+					newString,
+					replaceAll,
+				);
+				if (updated.content === original) {
+					return createToolError('No changes applied.', 'validation', {
+						suggestion:
+							'Adjust oldString/newString so the file content actually changes',
+					});
+				}
+
+				await writeFile(abs, updated.content, 'utf-8');
+				await rememberFileWrite(projectRoot, abs);
+				const artifact = await buildWriteArtifact(
+					path,
+					true,
+					original,
+					updated.content,
+				);
+				return {
+					ok: true,
+					path,
+					occurrences: updated.occurrences,
+					bytes: updated.content.length,
+					artifact,
+				};
+			} catch (error: unknown) {
+				const isEnoent =
+					error &&
+					typeof error === 'object' &&
+					'code' in error &&
+					error.code === 'ENOENT';
+				return createToolError(
+					isEnoent
+						? `File not found: ${path}`
+						: `Failed to edit file: ${error instanceof Error ? error.message : String(error)}`,
+					isEnoent ? 'not_found' : 'execution',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: isEnoent
+							? 'Use read or ls to confirm the file path first'
+							: undefined,
+					},
+				);
+			}
+		},
+	});
+
+	return { name: 'edit', tool: edit };
+}

package/src/core/src/tools/builtin/fs/edit.txt

@@ -0,0 +1,9 @@
+Replace an exact text block in an existing file.
+
+Use this for targeted edits instead of apply_patch whenever possible.
+
+Rules:
+- You must read the file first in the current session before editing it.
+- `oldString` must match the file exactly, including whitespace.
+- If `oldString` appears multiple times, provide more context or set `replaceAll: true`.
+- Use `write` for new files and `apply_patch` for structural multi-file diffs.

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

@@ -1,5 +1,7 @@
 import type { Tool } from 'ai';
+import { buildEditTool } from './edit.ts';
 import { buildReadTool } from './read.ts';
+import { buildMultiEditTool } from './multiedit.ts';
 import { buildWriteTool } from './write.ts';
 import { buildLsTool } from './ls.ts';
 import { buildTreeTool } from './tree.ts';
@@ -11,6 +13,8 @@ export function buildFsTools(
 ): Array<{ name: string; tool: Tool }> {
 	const out: Array<{ name: string; tool: Tool }> = [];
 	out.push(buildReadTool(projectRoot));
+	out.push(buildEditTool(projectRoot));
+	out.push(buildMultiEditTool(projectRoot));
 	out.push(buildWriteTool(projectRoot));
 	out.push(buildLsTool(projectRoot));
 	out.push(buildTreeTool(projectRoot));

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

@@ -0,0 +1,137 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import DESCRIPTION from './multiedit.txt' with { type: 'text' };
+import { buildWriteArtifact, isAbsoluteLike, resolveSafePath } from './util.ts';
+import { applyStringEdit } from './edit-shared.ts';
+import { assertFreshRead, rememberFileWrite } from './read-tracker.ts';
+import { createToolError, type ToolResponse } from '../../error.ts';
+
+const multiEditSchema = z.object({
+	path: z
+		.string()
+		.describe(
+			'Relative file path within the project. Absolute paths are not allowed.',
+		),
+	edits: z
+		.array(
+			z.object({
+				oldString: z.string().describe('Exact text to replace'),
+				newString: z.string().describe('Replacement text'),
+				replaceAll: z
+					.boolean()
+					.optional()
+					.default(false)
+					.describe('Replace every matching occurrence for this edit'),
+			}),
+		)
+		.min(1)
+		.describe('Edits to apply sequentially to the same file'),
+});
+
+export function buildMultiEditTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const multiedit = tool({
+		description: DESCRIPTION,
+		inputSchema: multiEditSchema,
+		async execute({ path, edits }: z.infer<typeof multiEditSchema>): Promise<
+			ToolResponse<{
+				path: string;
+				editsApplied: number;
+				bytes: number;
+				artifact: unknown;
+			}>
+		> {
+			if (!path || path.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: path',
+					'validation',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Provide a relative file path to edit',
+					},
+				);
+			}
+			if (isAbsoluteLike(path)) {
+				return createToolError(
+					`Refusing to edit outside project root: ${path}`,
+					'permission',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Use a relative path within the project',
+					},
+				);
+			}
+
+			const abs = resolveSafePath(projectRoot, path);
+			try {
+				await assertFreshRead(projectRoot, abs, path);
+				const original = await readFile(abs, 'utf-8');
+				let nextContent = original;
+				for (let i = 0; i < edits.length; i++) {
+					const edit = edits[i];
+					try {
+						nextContent = applyStringEdit(
+							nextContent,
+							edit.oldString,
+							edit.newString,
+							edit.replaceAll,
+						).content;
+					} catch (error: unknown) {
+						throw new Error(
+							`Edit ${i + 1} failed: ${error instanceof Error ? error.message : String(error)}`,
+						);
+					}
+				}
+
+				if (nextContent === original) {
+					return createToolError('No changes applied.', 'validation', {
+						suggestion:
+							'Adjust your edits so the file content actually changes',
+					});
+				}
+
+				await writeFile(abs, nextContent, 'utf-8');
+				await rememberFileWrite(projectRoot, abs);
+				const artifact = await buildWriteArtifact(
+					path,
+					true,
+					original,
+					nextContent,
+				);
+				return {
+					ok: true,
+					path,
+					editsApplied: edits.length,
+					bytes: nextContent.length,
+					artifact,
+				};
+			} catch (error: unknown) {
+				const isEnoent =
+					error &&
+					typeof error === 'object' &&
+					'code' in error &&
+					error.code === 'ENOENT';
+				return createToolError(
+					isEnoent
+						? `File not found: ${path}`
+						: `Failed to edit file: ${error instanceof Error ? error.message : String(error)}`,
+					isEnoent ? 'not_found' : 'execution',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: isEnoent
+							? 'Use read or ls to confirm the file path first'
+							: undefined,
+					},
+				);
+			}
+		},
+	});
+
+	return { name: 'multiedit', tool: multiedit };
+}

package/src/core/src/tools/builtin/fs/multiedit.txt

@@ -0,0 +1,9 @@
+Apply multiple exact text replacements to a single existing file atomically.
+
+Use this when you need several edits in one file.
+
+Rules:
+- Read the file first before editing.
+- Each edit uses exact `oldString` -> `newString` replacement.
+- All edits must succeed or none are written.
+- Use `replaceAll: true` only when every occurrence should change.

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

@@ -0,0 +1,72 @@
+import { stat } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
+
+type FileStamp = {
+	readAt: number;
+	mtimeMs?: number;
+	ctimeMs?: number;
+	size?: number;
+};
+
+const readState = new Map<string, Map<string, FileStamp>>();
+
+function getProjectState(projectRoot: string): Map<string, FileStamp> {
+	const key = resolvePath(projectRoot);
+	let state = readState.get(key);
+	if (!state) {
+		state = new Map<string, FileStamp>();
+		readState.set(key, state);
+	}
+	return state;
+}
+
+async function captureFileStamp(absPath: string): Promise<FileStamp> {
+	const stats = await stat(absPath);
+	return {
+		readAt: Date.now(),
+		mtimeMs: Number.isFinite(stats.mtimeMs) ? stats.mtimeMs : undefined,
+		ctimeMs: Number.isFinite(stats.ctimeMs) ? stats.ctimeMs : undefined,
+		size: typeof stats.size === 'number' ? stats.size : undefined,
+	};
+}
+
+export async function rememberFileRead(
+	projectRoot: string,
+	absPath: string,
+): Promise<void> {
+	const state = getProjectState(projectRoot);
+	state.set(absPath, await captureFileStamp(absPath));
+}
+
+export async function rememberFileWrite(
+	projectRoot: string,
+	absPath: string,
+): Promise<void> {
+	const state = getProjectState(projectRoot);
+	state.set(absPath, await captureFileStamp(absPath));
+}
+
+export async function assertFreshRead(
+	projectRoot: string,
+	absPath: string,
+	displayPath: string,
+): Promise<void> {
+	const state = getProjectState(projectRoot);
+	const previous = state.get(absPath);
+	if (!previous) {
+		throw new Error(
+			`You must read file ${displayPath} before editing it. Use the read tool first.`,
+		);
+	}
+
+	const current = await captureFileStamp(absPath);
+	const changed =
+		current.mtimeMs !== previous.mtimeMs ||
+		current.ctimeMs !== previous.ctimeMs ||
+		current.size !== previous.size;
+	if (!changed) return;
+
+	throw new Error(
+		`File ${displayPath} has changed since it was last read. Read it again before editing.`,
+	);
+}

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

@@ -2,6 +2,7 @@ import { tool, type Tool } from 'ai';
 import { z } from 'zod/v3';
 import { readFile } from 'node:fs/promises';
 import { expandTilde, isAbsoluteLike, resolveSafePath } from './util.ts';
+import { rememberFileRead } from './read-tracker.ts';
 import DESCRIPTION from './read.txt' with { type: 'text' };
 import { createToolError, type ToolResponse } from '../../error.ts';
 
@@ -108,6 +109,7 @@ export function buildReadTool(projectRoot: string): {
 			try {
 				let content = await readFile(abs, 'utf-8');
 				const indent = detectIndentation(content);
+				await rememberFileRead(projectRoot, abs);
 
 				if (startLine !== undefined && endLine !== undefined) {
 					const lines = content.split('\n');

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

@@ -8,6 +8,7 @@ import {
 	expandTilde,
 	isAbsoluteLike,
 } from './util.ts';
+import { rememberFileWrite } from './read-tracker.ts';
 import DESCRIPTION from './write.txt' with { type: 'text' };
 import { createToolError, type ToolResponse } from '../../error.ts';
 
@@ -79,6 +80,7 @@ export function buildWriteTool(projectRoot: string): {
 					existed = true;
 				} catch {}
 				await writeFile(abs, content);
+				await rememberFileWrite(projectRoot, abs);
 				const artifact = await buildWriteArtifact(
 					req,
 					existed,

package/src/core/src/tools/builtin/fs/write.txt

@@ -6,6 +6,6 @@
 Usage tips:
 - Use for creating NEW files
 - Use when replacing >70% of a file's content (almost complete rewrite)
-- NEVER use for partial/targeted edits - use apply_patch instead
+- NEVER use for partial/targeted edits - use edit/multiedit first, or apply_patch for structural changes
 - Using write for partial edits wastes output tokens and risks hallucinating unchanged parts
 - Prefer idempotent writes by providing the full intended content when you do use write

package/src/core/src/utils/debug.ts

@@ -1,7 +1,34 @@
+import { readFileSync } from 'node:fs';
+import { getGlobalConfigPath } from '../../../config/src/paths.ts';
+
+type DebugSettings = {
+	debugEnabled?: boolean;
+	debugScopes?: unknown;
+};
+
+function readDebugSettings(): DebugSettings {
+	try {
+		const raw = readFileSync(getGlobalConfigPath(), 'utf-8');
+		const parsed = JSON.parse(raw) as DebugSettings;
+		return parsed && typeof parsed === 'object' ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+
 export function isDebugEnabled(): boolean {
-	return false;
+	return readDebugSettings().debugEnabled === true;
 }
 
 export function isTraceEnabled(): boolean {
 	return false;
 }
+
+export function getDebugScopes(): string[] {
+	const scopes = readDebugSettings().debugScopes;
+	if (!Array.isArray(scopes)) return [];
+	return scopes.filter(
+		(scope): scope is string =>
+			typeof scope === 'string' && scope.trim().length > 0,
+	);
+}