@ottocode/sdk 0.1.173

package/src/core/src/tools/builtin/patch.ts

@@ -0,0 +1,167 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import DESCRIPTION from './patch.txt' with { type: 'text' };
+import { createToolError, type ToolResponse } from '../error.ts';
+import { applyPatchOperations } from './patch/apply.ts';
+import { parsePatchInput } from './patch/parse.ts';
+import type {
+	AppliedPatchOperation,
+	PatchOperation,
+	RejectedPatch,
+} from './patch/types.ts';
+
+function serializeChanges(operations: AppliedPatchOperation[]) {
+	return operations.map((operation) => ({
+		filePath: operation.filePath,
+		kind: operation.kind,
+		hunks: operation.hunks.map((hunk) => ({
+			oldStart: hunk.oldStart,
+			oldLines: hunk.oldLines,
+			newStart: hunk.newStart,
+			newLines: hunk.newLines,
+			additions: hunk.additions,
+			deletions: hunk.deletions,
+			context: hunk.header.context,
+		})),
+	}));
+}
+
+function serializeRejected(rejected: RejectedPatch[]) {
+	if (rejected.length === 0) return undefined;
+	return rejected.map((item) => ({
+		filePath: item.filePath,
+		kind: item.kind,
+		reason: item.reason,
+		hunks:
+			item.operation.kind === 'update'
+				? item.operation.hunks.map((hunk) => ({
+						oldStart: hunk.header.oldStart,
+						oldLines: hunk.header.oldLines,
+						newStart: hunk.header.newStart,
+						newLines: hunk.header.newLines,
+						context: hunk.header.context,
+						lines: hunk.lines.map((line) => ({
+							kind: line.kind,
+							content: line.content,
+						})),
+					}))
+				: undefined,
+	}));
+}
+
+export function buildApplyPatchTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const applyPatch = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			patch: z.string().min(1).describe('Unified diff patch content'),
+			allowRejects: z
+				.boolean()
+				.optional()
+				.default(false)
+				.describe(
+					'Allow hunks to be rejected without failing the whole operation',
+				),
+			fuzzyMatch: z
+				.boolean()
+				.optional()
+				.default(true)
+				.describe(
+					'Enable fuzzy matching with whitespace normalization (converts tabs to spaces for matching)',
+				),
+		}),
+		async execute({
+			patch,
+			allowRejects = false,
+			fuzzyMatch = true,
+		}: {
+			patch: string;
+			allowRejects?: boolean;
+			fuzzyMatch?: boolean;
+		}): Promise<
+			ToolResponse<{
+				output: string;
+				changes: unknown[];
+				artifact: unknown;
+				rejected?: unknown[];
+			}>
+		> {
+			if (!patch || patch.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: patch',
+					'validation',
+					{
+						parameter: 'patch',
+						value: patch,
+						suggestion: 'Provide patch content in enveloped format',
+					},
+				);
+			}
+
+			let operations: PatchOperation[];
+			try {
+				const parsed = parsePatchInput(patch);
+				operations = parsed.operations;
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return createToolError(message, 'validation', {
+					parameter: 'patch',
+					suggestion:
+						'Provide patch content using the enveloped format (*** Begin Patch ... *** End Patch) or standard unified diff format (---/+++ headers).',
+				});
+			}
+
+			try {
+				const result = await applyPatchOperations(projectRoot, operations, {
+					useFuzzy: fuzzyMatch,
+					allowRejects,
+				});
+
+				const changes = serializeChanges(result.operations);
+				const rejected = serializeRejected(result.rejected);
+
+				const output: string[] = [];
+				if (result.operations.length > 0) {
+					output.push(
+						`Applied ${result.operations.length} operation${result.operations.length === 1 ? '' : 's'}`,
+					);
+				}
+				if (allowRejects && result.rejected.length > 0) {
+					output.push(
+						`Skipped ${result.rejected.length} operation${result.rejected.length === 1 ? '' : 's'} due to mismatches`,
+					);
+				}
+				if (output.length === 0) {
+					output.push('No changes applied');
+				}
+
+				return {
+					ok: true,
+					output: output.join('; '),
+					changes,
+					artifact: {
+						kind: 'file_diff',
+						patch: result.normalizedPatch,
+						summary: result.summary,
+					},
+					rejected,
+				};
+			} catch (error) {
+				const errorMessage =
+					error instanceof Error ? error.message : String(error);
+				return createToolError(
+					`Failed to apply patch: ${errorMessage}`,
+					'execution',
+					{
+						suggestion:
+							'Check that the patch format is correct and target files exist',
+					},
+				);
+			}
+		},
+	});
+
+	return { name: 'apply_patch', tool: applyPatch };
+}

package/src/core/src/tools/builtin/patch.txt

@@ -0,0 +1,207 @@
+Apply a patch to modify one or more files. The tool accepts the **enveloped patch format** (preferred) and will also auto-convert standard unified diffs (`--- / +++`) if you provide one.
+
+**Quick checklist before you call the tool:**
+- Finished patch must include both `*** Begin Patch` and `*** End Patch`
+- Each change needs a directive (`*** Add File`, `*** Update File`, `*** Delete File`)
+- Include real context lines (prefixed with space) around your changes
+- Keep paths relative to the project root
+- **Use multiple `@@` hunks for multiple edits to the same file - do NOT make separate tool calls**
+
+**RECOMMENDED: Use apply_patch for targeted file edits to avoid rewriting entire files and wasting tokens.**
+
+**FUZZY MATCHING**: By default, fuzzy matching is enabled to handle whitespace differences (tabs vs spaces).
+Exact matching is tried first, then normalized matching if exact fails. Disable with `fuzzyMatch: false` if needed.
+
+Use `apply_patch` only when:
+- You want to make targeted edits to specific lines (primary use case)
+- You want to make multiple related changes across different files in a single operation
+- You need to add/delete entire files along with modifications
+- You have JUST read the file immediately before (within the same response) and are confident the content hasn't changed
+
+**CRITICAL - ALWAYS READ BEFORE PATCHING**: You MUST read the file content immediately before creating a patch.
+Never rely on memory or previous reads. Even with fuzzy matching enabled (tolerates tabs vs spaces),
+If the file content has changed significantly since you last read it, the patch may still fail.
+
+**ALLOW REJECTS**: If you are applying a patch that might include stale hunks, set `allowRejects: true`.
+The tool will apply the hunks it can and skip the rest, returning the skipped hunks with reasons.
+
+**ALREADY APPLIED?**: If the removal lines are already gone or the additions are already present, the tool will treat the hunk as applied and move on—no need to resend the same change.
+
+**Alternative: Use the `edit` tool if you need fuzzy matching or structured operations.**
+
+## ⚠️ CRITICAL: Multiple Edits to Same File
+
+**DO NOT make separate `apply_patch` calls for the same file!**
+
+Instead, use multiple `@@` hunks in a single patch:
+
+```
+*** Begin Patch
+*** Update File: src/app.ts
+@@ first change - line 10
+ function init() {
+-  const port = 3000;
++  const port = 8080;
+   return port;
+ }
+@@ second change - line 25
+ function start() {
+-  console.log("Starting...");
++  console.log("Server starting...");
+   init();
+ }
+@@ third change - line 40
+ function cleanup() {
+-  // TODO
++  console.log("Cleaning up...");
+ }
+*** End Patch
+```
+
+**This makes ONE tool call instead of three, saving tokens and reducing latency.**
+
+## Patch Formats
+
+### Preferred: Enveloped Patch
+
+All patches must be wrapped in markers and use explicit file directives:
+
+```
+*** Begin Patch
+*** Add File: path/to/file.txt
++line 1
++line 2
+*** Update File: path/to/other.txt
+-old line
++new line
+*** Delete File: path/to/delete.txt
+*** End Patch
+```
+
+### Also Supported: Standard Unified Diff
+
+You can paste a regular `git diff` style patch:
+
+```
+diff --git a/src/app.ts b/src/app.ts
+--- a/src/app.ts
++++ b/src/app.ts
+@@
+-const PORT = 3000;
++const PORT = 8080;
+```
+
+The tool will convert it automatically, but the enveloped format is still recommended because it is more explicit and easier to control.
+
+## File Operations
+
+### Add a new file:
+```
+*** Begin Patch
+*** Add File: src/hello.ts
++export function hello() {
++  console.log("Hello!");
++}
+*** End Patch
+```
+
+### Update an existing file (simple replacement):
+```
+*** Begin Patch
+*** Update File: src/config.ts
+-const PORT = 3000;
++const PORT = 8080;
+*** End Patch
+```
+
+**CRITICAL**: The `-` lines must match EXACTLY what's in the file, character-for-character. If you're not 100% certain, use the `edit` tool instead.
+
+### Update with context (recommended for precision):
+```
+*** Begin Patch
+*** Update File: src/app.ts
+@@ function main()
+ function main() {
+-  console.log("old");
++  console.log("new");
+ }
+*** End Patch
+```
+
+**IMPORTANT**: 
+- The `@@` line is an OPTIONAL hint to help locate the change - it's a comment, not parsed as context
+- REQUIRED: Actual context lines (starting with space ` `) that match the file exactly
+- The context lines with space prefix are what the tool uses to find the location
+- The `@@` line just helps humans/AI understand what section you're editing
+
+
+### Update multiple locations in the same file:
+```
+*** Begin Patch
+*** Update File: src/app.ts
+@@ first section - near line 10
+ function init() {
+-  const port = 3000;
++  const port = 8080;
+   return port;
+ }
+@@ second section - near line 25
+ function start() {
+-  console.log("Starting...");
++  console.log("Server starting...");
+   init();
+ }
+*** End Patch
+```
+
+**IMPORTANT**: Use separate `@@` headers for each non-consecutive change location. This allows multiple edits to the same file in one patch, saving tokens and reducing tool calls.
+
+### Delete a file:
+```
+*** Begin Patch
+*** Delete File: old/unused.ts
+*** End Patch
+```
+
+### Multiple operations in one patch:
+```
+*** Begin Patch
+*** Add File: new.txt
++New content
+*** Update File: existing.txt
+-old
++new
+*** Delete File: obsolete.txt
+*** End Patch
+```
+
+## Line Prefixes
+
+- Lines starting with `+` are added
+- Lines starting with `-` are removed  
+- Lines starting with ` ` (space) are context (kept unchanged)
+- Lines starting with `@@` are optional hints/comments (not parsed as context)
+
+## Common Errors
+
+**"Missing *** End Patch marker"**: Every patch MUST end with `*** End Patch` on its own line.
+This is the most common error. Double-check your patch ends with:
+```
+*** End Patch
+```
+
+**"Failed to find expected lines"**: The file content doesn't match your patch. Common causes:
+- Missing context lines (lines with space prefix)
+- Using `@@` line as context instead of real context lines
+- The file content has changed since you read it
+- Whitespace/indentation mismatch
+
+**Solution**: Always read the file immediately before patching and include actual context lines with space prefix.
+
+## Important Notes
+
+- **Patches are fragile**: Any mismatch in whitespace, indentation, or content will cause failure
+- **Use `edit` for reliability**: The `edit` tool can make targeted changes without requiring exact matches
+- All file paths are relative to the project root
+- The enveloped format is the most reliable; unified diffs are converted automatically if provided
+- Always wrap patches with `*** Begin Patch` and `*** End Patch` when you write them manually

package/src/core/src/tools/builtin/progress.ts

@@ -0,0 +1,55 @@
+import { tool } from 'ai';
+import { z } from 'zod/v3';
+import DESCRIPTION from './progress.txt' with { type: 'text' };
+
+// Progress update tool: allows the model to emit lightweight status signals
+// without revealing chain-of-thought. The runner/UI should surface these
+// messages immediately.
+const StageEnum = z.enum([
+	'planning',
+	'discovering',
+	'generating',
+	'preparing',
+	'writing',
+	'verifying',
+]);
+
+export const progressUpdateTool = tool({
+	description: DESCRIPTION,
+	inputSchema: z.object({
+		message: z
+			.string()
+			.min(1)
+			.max(200)
+			.describe('Short, user-facing status message (<= 200 chars).'),
+		pct: z
+			.number()
+			.min(0)
+			.max(100)
+			.optional()
+			.describe('Optional overall progress percent 0-100.'),
+		stage: StageEnum.optional().default('planning'),
+	}),
+	async execute({
+		message,
+		pct,
+		stage,
+	}: {
+		message: string;
+		pct?: number;
+		stage?: z.infer<typeof StageEnum>;
+	}) {
+		// Keep the tool lightweight; no side effects beyond the event itself.
+		// Returning the normalized payload allows generic renderers to inspect it if needed.
+		const normalizedPct =
+			typeof pct === 'number'
+				? Math.min(100, Math.max(0, Math.round(pct)))
+				: undefined;
+		return {
+			ok: true,
+			message,
+			pct: normalizedPct,
+			stage: stage ?? 'planning',
+		} as const;
+	},
+});

package/src/core/src/tools/builtin/progress.txt

@@ -0,0 +1,7 @@
+- Emit a short, user-facing progress/status update
+- Supports optional `pct` (0–100) and `stage` indicators
+- Lightweight; intended for immediate UI display
+
+Usage tips:
+- Keep messages short (<= 200 chars) and informative
+- Use multiple updates during long-running tasks

package/src/core/src/tools/builtin/ripgrep.ts

@@ -0,0 +1,125 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import DESCRIPTION from './ripgrep.txt' with { type: 'text' };
+import { createToolError, type ToolResponse } from '../error.ts';
+import { resolveBinary } from '../bin-manager.ts';
+
+export function buildRipgrepTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const rg = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			query: z.string().min(1).describe('Search pattern (regex by default)'),
+			path: z
+				.string()
+				.optional()
+				.default('.')
+				.describe('Relative path to search in'),
+			ignoreCase: z.boolean().optional().default(false),
+			glob: z
+				.array(z.string())
+				.optional()
+				.describe('One or more glob patterns to include'),
+			maxResults: z.number().int().min(1).max(5000).optional().default(500),
+		}),
+		async execute({
+			query,
+			path = '.',
+			ignoreCase,
+			glob,
+			maxResults = 500,
+		}: {
+			query: string;
+			path?: string;
+			ignoreCase?: boolean;
+			glob?: string[];
+			maxResults?: number;
+		}): Promise<
+			ToolResponse<{
+				count: number;
+				matches: Array<{ file: string; line: number; text: string }>;
+			}>
+		> {
+			function expandTilde(p: string) {
+				const home = process.env.HOME || process.env.USERPROFILE || '';
+				if (!home) return p;
+				if (p === '~') return home;
+				if (p.startsWith('~/')) return `${home}/${p.slice(2)}`;
+				return p;
+			}
+			const p = expandTilde(String(path ?? '.')).trim();
+			const isAbs = p.startsWith('/') || /^[A-Za-z]:[\\/]/.test(p);
+			const target = p ? (isAbs ? p : join(projectRoot, p)) : projectRoot;
+			const args = ['--no-heading', '--line-number', '--color=never'];
+			if (ignoreCase) args.push('-i');
+			if (Array.isArray(glob)) for (const g of glob) args.push('-g', g);
+			args.push('--max-count', String(maxResults));
+			args.push(query);
+			args.push(target);
+
+			try {
+				const rgBin = await resolveBinary('rg');
+				return await new Promise((resolve) => {
+					const proc = spawn(rgBin, args, { cwd: projectRoot });
+					let stdout = '';
+					let stderr = '';
+
+					proc.stdout.on('data', (data) => {
+						stdout += data.toString();
+					});
+
+					proc.stderr.on('data', (data) => {
+						stderr += data.toString();
+					});
+
+					proc.on('close', (code) => {
+						if (code !== 0 && code !== 1) {
+							resolve(
+								createToolError(
+									stderr.trim() || 'ripgrep failed',
+									'execution',
+									{
+										suggestion:
+											'Check if ripgrep (rg) is installed and the query is valid',
+									},
+								),
+							);
+							return;
+						}
+
+						const lines = stdout
+							.split('\n')
+							.filter(Boolean)
+							.slice(0, maxResults);
+						const matches = lines.map((l) => {
+							const parts = l.split(':');
+							if (parts.length < 3) return { file: '', line: 0, text: l };
+							const file = parts[0];
+							const line = Number.parseInt(parts[1], 10);
+							const text = parts.slice(2).join(':');
+							return { file, line, text };
+						});
+						resolve({ ok: true, count: matches.length, matches });
+					});
+
+					proc.on('error', (err) => {
+						resolve(
+							createToolError(String(err), 'execution', {
+								suggestion: 'Ensure ripgrep (rg) is installed',
+							}),
+						);
+					});
+				});
+			} catch (err) {
+				return createToolError(String(err), 'execution', {
+					suggestion: 'Ensure ripgrep (rg) is installed',
+				});
+			}
+		},
+	});
+	return { name: 'ripgrep', tool: rg };
+}

package/src/core/src/tools/builtin/ripgrep.txt

@@ -0,0 +1,7 @@
+- Search files using ripgrep (rg) with regex patterns
+- Returns a flat list of matches with `file`, `line`, and `text`
+- Supports include globs and case-insensitive search
+
+Usage tips:
+- Use the Grep tool for a friendly summary grouped by file
+- Use the Glob tool first to limit the search set if needed