@ottocode/sdk 0.1.173

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

@@ -0,0 +1,12 @@
+- Search the web or fetch content from URLs
+- Use `query` to search the web and get a list of results with titles, URLs, and snippets
+- Use `url` to fetch and read the content of a specific webpage
+- Returns cleaned, text-based content (HTML tags are stripped)
+- Cannot be used for both search and URL fetch in the same call
+
+Usage tips:
+- For research: use `query` to find relevant pages, then `url` to read specific ones
+- Search returns up to 10 results with titles, URLs, and snippets
+- URL fetching works for text-based content (HTML, JSON, XML, plain text)
+- Content is automatically truncated if it exceeds maxLength (default 50,000 chars)
+- Use this to gather current information, read documentation, or verify facts

package/src/core/src/tools/error.ts

@@ -0,0 +1,67 @@
+export type ToolErrorType =
+	| 'validation'
+	| 'not_found'
+	| 'permission'
+	| 'execution'
+	| 'timeout'
+	| 'unsupported';
+
+export type ToolErrorResponse = {
+	ok: false;
+	error: string;
+	errorType?: ToolErrorType;
+	details?: {
+		parameter?: string;
+		value?: unknown;
+		constraint?: string;
+		suggestion?: string;
+		[key: string]: unknown;
+	};
+	stack?: string;
+};
+
+export type ToolSuccessResponse<T = unknown> = {
+	ok: true;
+} & T;
+
+export type ToolResponse<T = unknown> =
+	| ToolSuccessResponse<T>
+	| ToolErrorResponse;
+
+export function isToolError(result: unknown): result is ToolErrorResponse {
+	if (!result || typeof result !== 'object') return false;
+	const obj = result as Record<string, unknown>;
+	return obj.ok === false || 'error' in obj || obj.success === false;
+}
+
+export function extractToolError(
+	result: unknown,
+	topLevelError?: string,
+): string | undefined {
+	if (topLevelError?.trim()) return topLevelError.trim();
+	if (!result || typeof result !== 'object') return undefined;
+
+	const obj = result as Record<string, unknown>;
+	const keys = ['error', 'stderr', 'message', 'detail', 'details', 'reason'];
+	for (const key of keys) {
+		const value = obj[key];
+		if (typeof value === 'string') {
+			const trimmed = value.trim();
+			if (trimmed.length) return trimmed;
+		}
+	}
+	return undefined;
+}
+
+export function createToolError(
+	error: string,
+	errorType?: ToolErrorType,
+	details?: ToolErrorResponse['details'],
+): ToolErrorResponse {
+	return {
+		ok: false,
+		error,
+		errorType,
+		details,
+	};
+}

package/src/core/src/tools/loader.ts

@@ -0,0 +1,421 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import { finishTool } from './builtin/finish.ts';
+import { buildFsTools } from './builtin/fs/index.ts';
+import { buildGitTools } from './builtin/git.ts';
+import { progressUpdateTool } from './builtin/progress.ts';
+import { buildBashTool } from './builtin/bash.ts';
+import { buildRipgrepTool } from './builtin/ripgrep.ts';
+import { buildGrepTool } from './builtin/grep.ts';
+import { buildGlobTool } from './builtin/glob.ts';
+import { buildApplyPatchTool } from './builtin/patch.ts';
+import { updateTodosTool } from './builtin/todos.ts';
+import { buildWebSearchTool } from './builtin/websearch.ts';
+import { buildTerminalTool } from './builtin/terminal.ts';
+import type { TerminalManager } from '../terminals/index.ts';
+import { initializeSkills, buildSkillTool } from '../../../skills/index.ts';
+import fg from 'fast-glob';
+import { dirname, isAbsolute, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { promises as fs } from 'node:fs';
+import { spawn as nodeSpawn } from 'node:child_process';
+
+export type DiscoveredTool = { name: string; tool: Tool };
+
+type PluginParameter = {
+	type: 'string' | 'number' | 'boolean';
+	description?: string;
+	default?: string | number | boolean;
+	enum?: string[];
+	optional?: boolean;
+};
+
+type PluginDescriptor = {
+	name?: string;
+	description?: string;
+	parameters?: Record<string, PluginParameter>;
+	execute?: PluginExecutor;
+	run?: PluginExecutor;
+	handler?: PluginExecutor;
+	setup?: (context: PluginContext) => unknown | Promise<unknown>;
+	onInit?: (context: PluginContext) => unknown | Promise<unknown>;
+};
+
+type PluginExecutor = (args: PluginExecuteArgs) => unknown | Promise<unknown>;
+
+type PluginExecuteArgs = {
+	input: Record<string, unknown>;
+	project: string;
+	projectRoot: string;
+	directory: string;
+	worktree: string;
+	exec: ExecFn;
+	run: ExecFn;
+	$: TemplateExecFn;
+	fs: FsHelpers;
+	env: Record<string, string>;
+	context: PluginContext;
+};
+
+type PluginContext = {
+	project: string;
+	projectRoot: string;
+	directory: string;
+	worktree: string;
+	toolDir: string;
+};
+
+type ExecFn = (
+	command: string,
+	args?: string[] | ExecOptions,
+	options?: ExecOptions,
+) => Promise<ExecResult>;
+
+type TemplateExecFn = (
+	strings: TemplateStringsArray,
+	...values: unknown[]
+) => Promise<ExecResult>;
+
+type ExecOptions = {
+	cwd?: string;
+	env?: Record<string, string>;
+	allowNonZeroExit?: boolean;
+};
+
+type ExecResult = { exitCode: number; stdout: string; stderr: string };
+
+type FsHelpers = {
+	readFile: (path: string, encoding?: BufferEncoding) => Promise<string>;
+	writeFile: (path: string, content: string) => Promise<void>;
+	exists: (path: string) => Promise<boolean>;
+};
+
+const pluginPatterns = ['tools/*/tool.js', 'tools/*/tool.mjs'];
+
+let globalTerminalManager: TerminalManager | null = null;
+
+export function setTerminalManager(manager: TerminalManager): void {
+	globalTerminalManager = manager;
+}
+
+export function getTerminalManager(): TerminalManager | null {
+	return globalTerminalManager;
+}
+
+export async function discoverProjectTools(
+	projectRoot: string,
+	globalConfigDir?: string,
+): Promise<DiscoveredTool[]> {
+	const tools = new Map<string, Tool>();
+	for (const { name, tool } of buildFsTools(projectRoot)) tools.set(name, tool);
+	for (const { name, tool } of buildGitTools(projectRoot))
+		tools.set(name, tool);
+	// Built-ins
+	tools.set('finish', finishTool);
+	tools.set('progress_update', progressUpdateTool);
+	const bash = buildBashTool(projectRoot);
+	tools.set(bash.name, bash.tool);
+	// Search
+	const rg = buildRipgrepTool(projectRoot);
+	tools.set(rg.name, rg.tool);
+	const grep = buildGrepTool(projectRoot);
+	tools.set(grep.name, grep.tool);
+	const glob = buildGlobTool(projectRoot);
+	tools.set(glob.name, glob.tool);
+	// Patch/apply
+	const ap = buildApplyPatchTool(projectRoot);
+	tools.set(ap.name, ap.tool);
+	// Todo tracking
+	tools.set('update_todos', updateTodosTool);
+	// Web search
+	const ws = buildWebSearchTool();
+	tools.set(ws.name, ws.tool);
+	// Terminal (if manager is available)
+	if (globalTerminalManager) {
+		const term = buildTerminalTool(projectRoot, globalTerminalManager);
+		tools.set(term.name, term.tool);
+	}
+	// Skills
+	// Always reinitialize to ensure skills are discovered for the current project
+	await initializeSkills(projectRoot);
+	const skillTool = buildSkillTool();
+	tools.set(skillTool.name, skillTool.tool);
+
+	async function loadFromBase(base: string | null | undefined) {
+		if (!base) return;
+		try {
+			await fs.readdir(base);
+		} catch {
+			return;
+		}
+		for (const pattern of pluginPatterns) {
+			const files = await fg(pattern, { cwd: base, absolute: false });
+			for (const rel of files) {
+				const match = rel.match(/^tools\/([^/]+)\/tool\.(m?js)$/);
+				if (!match || !match[1]) continue;
+				const folder = match[1];
+				const absPath = join(base, rel).replace(/\\/g, '/');
+				try {
+					const plugin = await loadPlugin(absPath, folder, projectRoot);
+					if (plugin) tools.set(plugin.name, plugin.tool);
+				} catch (err) {
+					if (process.env.OTTO_DEBUG_TOOLS === '1')
+						console.error('Failed to load tool', absPath, err);
+				}
+			}
+		}
+		// Fallback: manual directory scan
+		try {
+			const toolsDir = join(base, 'tools');
+			const entries = await fs.readdir(toolsDir).catch(() => [] as string[]);
+			for (const folder of entries) {
+				const js = join(toolsDir, folder, 'tool.js');
+				const mjs = join(toolsDir, folder, 'tool.mjs');
+				const candidate = await fs
+					.stat(js)
+					.then(() => js)
+					.catch(
+						async () =>
+							await fs
+								.stat(mjs)
+								.then(() => mjs)
+								.catch(() => null),
+					);
+				if (!candidate) continue;
+				try {
+					const plugin = await loadPlugin(
+						candidate.replace(/\\/g, '/'),
+						folder,
+						projectRoot,
+					);
+					if (plugin) tools.set(plugin.name, plugin.tool);
+				} catch {}
+			}
+		} catch {}
+	}
+
+	await loadFromBase(globalConfigDir);
+	await loadFromBase(join(projectRoot, '.otto'));
+	return Array.from(tools.entries()).map(([name, tool]) => ({ name, tool }));
+}
+
+async function loadPlugin(
+	absPath: string,
+	folder: string,
+	projectRoot: string,
+): Promise<DiscoveredTool | null> {
+	const mod = await import(`${pathToFileURL(absPath).href}?t=${Date.now()}`);
+	const candidate = resolveExport(mod);
+	if (!candidate) throw new Error('No plugin export found');
+
+	const context: PluginContext = {
+		project: projectRoot,
+		projectRoot,
+		directory: projectRoot,
+		worktree: projectRoot,
+		toolDir: absPath.slice(0, absPath.lastIndexOf('/')),
+	};
+
+	let descriptor: PluginDescriptor | null | undefined;
+	if (typeof candidate === 'function') descriptor = await candidate(context);
+	else descriptor = candidate;
+	if (!descriptor || typeof descriptor !== 'object')
+		throw new Error('Plugin must return an object descriptor');
+
+	if (typeof descriptor.setup === 'function') await descriptor.setup(context);
+	if (typeof descriptor.onInit === 'function') await descriptor.onInit(context);
+
+	const name = sanitizeName(descriptor.name ?? folder);
+	const description = descriptor.description ?? `Custom tool ${name}`;
+	const parameters = descriptor.parameters ?? {};
+	const inputSchema = createInputSchema(parameters);
+	const executor = resolveExecutor(descriptor);
+
+	const helpersFactory = createHelpers(projectRoot, context.toolDir);
+
+	const wrapped = tool({
+		description,
+		inputSchema,
+		async execute(input) {
+			const helpers = helpersFactory();
+			const result = await executor({
+				input: input as Record<string, unknown>,
+				project: helpers.context.project,
+				projectRoot: helpers.context.projectRoot,
+				directory: helpers.context.directory,
+				worktree: helpers.context.worktree,
+				exec: helpers.exec,
+				run: helpers.exec,
+				$: helpers.templateExec,
+				fs: helpers.fs,
+				env: helpers.env,
+				context: helpers.context,
+			});
+			return result ?? { ok: true };
+		},
+	});
+
+	return { name, tool: wrapped };
+}
+
+function resolveExport(mod: Record<string, unknown>) {
+	if (mod.default) return mod.default;
+	if (mod.tool) return mod.tool;
+	if (mod.plugin) return mod.plugin;
+	if (mod.Tool) return mod.Tool;
+	const values = Object.values(mod);
+	return values.find(
+		(value) => typeof value === 'function' || typeof value === 'object',
+	);
+}
+
+function resolveExecutor(descriptor: PluginDescriptor): PluginExecutor {
+	const fn = descriptor.execute ?? descriptor.run ?? descriptor.handler;
+	if (typeof fn !== 'function')
+		throw new Error('Plugin must provide an execute/run/handler function');
+	return fn;
+}
+
+function sanitizeName(name: string) {
+	const cleaned = name.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128);
+	return cleaned || 'tool';
+}
+
+function createInputSchema(parameters: Record<string, PluginParameter>) {
+	const shape: Record<string, z.ZodTypeAny> = {};
+	for (const [key, def] of Object.entries(parameters)) {
+		let schema: z.ZodTypeAny;
+		if (def.type === 'string') {
+			const values = def.enum;
+			schema = values?.length
+				? z.enum(values as [string, ...string[]])
+				: z.string();
+		} else if (def.type === 'number') schema = z.number();
+		else schema = z.boolean();
+		if (def.description) schema = schema.describe(def.description);
+		if (def.default !== undefined)
+			schema = schema.default(def.default as never);
+		else if (def.optional) schema = schema.optional();
+		shape[key] = schema;
+	}
+	return Object.keys(shape).length ? z.object(shape).strict() : z.object({});
+}
+
+function createHelpers(projectRoot: string, toolDir: string) {
+	return () => {
+		const exec = createExec(projectRoot);
+		const fsHelpers = createFsHelpers(projectRoot);
+		const context: PluginContext = {
+			project: projectRoot,
+			projectRoot,
+			directory: projectRoot,
+			worktree: projectRoot,
+			toolDir,
+		};
+		const env: Record<string, string> = {};
+		for (const [key, value] of Object.entries(process.env))
+			if (typeof value === 'string') env[key] = value;
+		const templateExec: TemplateExecFn = (strings, ...values) => {
+			const commandLine = strings.reduce((acc, part, index) => {
+				const value = index < values.length ? String(values[index]) : '';
+				return acc + part + value;
+			}, '');
+			const pieces = commandLine.trim().split(/\s+/).filter(Boolean);
+			if (pieces.length === 0)
+				throw new Error('Empty command passed to template executor');
+			const firstPiece = pieces[0];
+			if (!firstPiece)
+				throw new Error('Empty command passed to template executor');
+			return exec(firstPiece, pieces.slice(1));
+		};
+		return {
+			exec,
+			fs: fsHelpers,
+			env,
+			templateExec,
+			context,
+		};
+	};
+}
+
+function createExec(projectRoot: string): ExecFn {
+	return async (
+		command: string,
+		argsOrOptions?: string[] | ExecOptions,
+		maybeOptions?: ExecOptions,
+	) => {
+		let args: string[] = [];
+		let options: ExecOptions = {};
+		if (Array.isArray(argsOrOptions)) {
+			args = argsOrOptions;
+			options = maybeOptions ?? {};
+		} else if (argsOrOptions) options = argsOrOptions;
+
+		const cwd = options.cwd
+			? resolveWithinProject(projectRoot, options.cwd)
+			: projectRoot;
+		const env: Record<string, string> = {};
+		for (const [key, value] of Object.entries(process.env))
+			if (typeof value === 'string') env[key] = value;
+		if (options.env)
+			for (const [key, value] of Object.entries(options.env)) env[key] = value;
+
+		const proc = nodeSpawn(command, args, {
+			cwd,
+			env,
+			stdio: ['ignore', 'pipe', 'pipe'],
+		});
+
+		const stdoutChunks: Buffer[] = [];
+		const stderrChunks: Buffer[] = [];
+
+		proc.stdout?.on('data', (chunk) => stdoutChunks.push(chunk));
+		proc.stderr?.on('data', (chunk) => stderrChunks.push(chunk));
+
+		const exitCode = await new Promise<number>((resolve, reject) => {
+			proc.on('exit', (code) => resolve(code ?? 0));
+			proc.on('error', reject);
+		});
+
+		const stdout = Buffer.concat(stdoutChunks).toString('utf-8');
+		const stderr = Buffer.concat(stderrChunks).toString('utf-8');
+		if (exitCode !== 0 && !options.allowNonZeroExit) {
+			const message = stderr.trim() || stdout.trim() || `${command} failed`;
+			throw new Error(`${command} exited with code ${exitCode}: ${message}`);
+		}
+		return { exitCode, stdout, stderr };
+	};
+}
+
+function createFsHelpers(projectRoot: string): FsHelpers {
+	return {
+		async readFile(path: string, encoding: BufferEncoding = 'utf-8') {
+			const abs = resolveWithinProject(projectRoot, path);
+			return fs.readFile(abs, { encoding });
+		},
+		async writeFile(path: string, content: string) {
+			const abs = resolveWithinProject(projectRoot, path);
+			await fs.mkdir(dirname(abs), { recursive: true });
+			await fs.writeFile(abs, content, 'utf-8');
+		},
+		async exists(path: string) {
+			const abs = resolveWithinProject(projectRoot, path);
+			try {
+				await fs.access(abs);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+	};
+}
+
+function resolveWithinProject(projectRoot: string, target: string) {
+	if (!target) return projectRoot;
+	if (target.startsWith('~/')) {
+		const home = process.env.HOME || process.env.USERPROFILE || '';
+		return join(home, target.slice(2));
+	}
+	if (isAbsolute(target)) return target;
+	return join(projectRoot, target);
+}

package/src/core/src/types/index.ts

@@ -0,0 +1,11 @@
+export type ExecutionContext = {
+	projectRoot: string;
+	workingDir?: string;
+	env?: Record<string, string>;
+};
+
+export type ToolResult = {
+	success: boolean;
+	output?: string;
+	error?: string;
+};

package/src/core/src/types/types.ts

@@ -0,0 +1,4 @@
+export interface ToolContext {
+	projectRoot: string;
+	// Consider adding db, logger etc. when integrated
+}

package/src/core/src/utils/ansi.ts

@@ -0,0 +1,27 @@
+export function stripAnsi(input: string): string {
+	let result = '';
+	for (let i = 0; i < input.length; i += 1) {
+		const ch = input[i];
+		if (ch === '\u001B' || ch === '\u009B') {
+			// Skip CSI sequences until we hit a terminating byte (A-Z or a-z)
+			i += 1;
+			while (i < input.length) {
+				const code = input[i];
+				if (
+					code &&
+					((code >= '@' && code <= 'Z') || (code >= 'a' && code <= 'z'))
+				) {
+					break;
+				}
+				i += 1;
+			}
+		} else {
+			result += ch;
+		}
+	}
+	return result;
+}
+
+export function normalizeTerminalLine(line: string): string {
+	return stripAnsi(line).replace(/\r/g, '');
+}

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

@@ -0,0 +1,40 @@
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+
+type GlobalDebugFlags = {
+	__OTTO_DEBUG_ENABLED__?: boolean;
+	__OTTO_TRACE_ENABLED__?: boolean;
+};
+
+function readGlobalFlag(
+	key: '__OTTO_DEBUG_ENABLED__' | '__OTTO_TRACE_ENABLED__',
+) {
+	const globalState = globalThis as GlobalDebugFlags;
+	return globalState[key];
+}
+
+function envEnabled(keys: string[]): boolean {
+	for (const key of keys) {
+		const raw = typeof process !== 'undefined' ? process.env?.[key] : undefined;
+		if (!raw) continue;
+		const trimmed = raw.trim().toLowerCase();
+		if (!trimmed) continue;
+		if (TRUTHY.has(trimmed) || trimmed === 'all') return true;
+	}
+	return false;
+}
+
+export function isDebugEnabled(): boolean {
+	const globalFlag = readGlobalFlag('__OTTO_DEBUG_ENABLED__');
+	if (typeof globalFlag === 'boolean') {
+		return globalFlag;
+	}
+	return envEnabled(['OTTO_DEBUG', 'DEBUG_OTTO']);
+}
+
+export function isTraceEnabled(): boolean {
+	const globalFlag = readGlobalFlag('__OTTO_TRACE_ENABLED__');
+	if (typeof globalFlag === 'boolean') {
+		return Boolean(globalFlag) && isDebugEnabled();
+	}
+	return envEnabled(['OTTO_TRACE', 'TRACE_OTTO']) && isDebugEnabled();
+}