@ottocode/sdk 0.1.173

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

@@ -0,0 +1,300 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import DESCRIPTION from './terminal.txt' with { type: 'text' };
+import { createToolError } from '../error.ts';
+import type { TerminalManager } from '../../terminals/index.ts';
+import type { TerminalStatus } from '../../terminals/terminal.ts';
+import { normalizeTerminalLine } from '../../utils/ansi.ts';
+
+function shellQuote(segment: string): string {
+	if (/^[a-zA-Z0-9._-]+$/.test(segment)) {
+		return segment;
+	}
+	return `'${segment.replace(/'/g, `'\\''`)}'`;
+}
+
+function formatShellCommand(parts: string[]): string {
+	return parts.map(shellQuote).join(' ');
+}
+
+function normalizePath(p: string) {
+	const parts = p.replace(/\\/g, '/').split('/');
+	const stack: string[] = [];
+	for (const part of parts) {
+		if (!part || part === '.') continue;
+		if (part === '..') stack.pop();
+		else stack.push(part);
+	}
+	return `/${stack.join('/')}`;
+}
+
+function resolveSafePath(projectRoot: string, p: string) {
+	const root = normalizePath(projectRoot);
+	const abs = normalizePath(`${root}/${p || '.'}`);
+	if (!(abs === root || abs.startsWith(`${root}/`))) {
+		throw new Error(`cwd escapes project root: ${p}`);
+	}
+	return abs;
+}
+
+export function buildTerminalTool(
+	projectRoot: string,
+	terminalManager: TerminalManager,
+): {
+	name: string;
+	tool: Tool;
+} {
+	const terminal = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			operation: z
+				.enum(['start', 'read', 'write', 'interrupt', 'list', 'kill'])
+				.describe('Operation to perform'),
+
+			command: z.string().optional().describe('For start: Command to run'),
+			args: z
+				.array(z.string())
+				.optional()
+				.describe('For start: Command arguments'),
+			shell: z
+				.boolean()
+				.default(true)
+				.describe(
+					'For start: Launch inside interactive shell and optionally run command',
+				),
+			purpose: z
+				.string()
+				.optional()
+				.describe('For start: Description of what this terminal is for'),
+			title: z
+				.string()
+				.optional()
+				.describe(
+					'For start: Short name shown in the UI (defaults to purpose)',
+				),
+			cwd: z
+				.string()
+				.default('.')
+				.describe('For start: Working directory relative to project root'),
+
+			terminalId: z
+				.string()
+				.optional()
+				.describe('For read/write/kill: Terminal ID'),
+
+			lines: z
+				.number()
+				.default(100)
+				.optional()
+				.describe('For read: Number of lines to read from end'),
+			raw: z
+				.boolean()
+				.optional()
+				.describe(
+					'For read: Include raw output with ANSI escape sequences (default false)',
+				),
+
+			input: z
+				.string()
+				.optional()
+				.describe('For write: String to write to stdin'),
+		}),
+		execute: async (params) => {
+			try {
+				const { operation } = params;
+
+				switch (operation) {
+					case 'start': {
+						const runInShell = params.shell;
+
+						if (!params.command && !runInShell) {
+							return createToolError('command is required for start operation');
+						}
+						if (!params.purpose) {
+							return createToolError('purpose is required for start operation');
+						}
+
+						const cwd = resolveSafePath(projectRoot, params.cwd);
+
+						const shellPath = process.env.SHELL || '/bin/sh';
+
+						let command = params.command ?? shellPath;
+						let args = params.args ?? [];
+						let initialCommand: string | null = null;
+
+						if (runInShell) {
+							command = shellPath;
+							args = ['-i'];
+							const providedCommand = params.command;
+							const providedArgs = params.args ?? [];
+
+							if (providedCommand || providedArgs.length > 0) {
+								if (providedArgs.length === 0 && providedCommand) {
+									// Command already contains spaces; treat as full shell snippet
+									initialCommand = providedCommand;
+								} else {
+									const commandParts = [
+										providedCommand,
+										...providedArgs,
+									].filter((part): part is string => Boolean(part));
+									if (commandParts.length > 0) {
+										initialCommand = formatShellCommand(commandParts);
+									}
+								}
+							}
+						}
+
+						const term = terminalManager.create({
+							command,
+							args,
+							cwd,
+							purpose: params.purpose,
+							title: params.title,
+							createdBy: 'llm',
+						});
+
+						if (initialCommand) {
+							queueMicrotask(() => {
+								term.write(`${initialCommand}\n`);
+							});
+						}
+
+						return {
+							ok: true,
+							terminalId: term.id,
+							pid: term.pid,
+							purpose: term.purpose,
+							command: params.command ?? command,
+							args: params.args || [],
+							shell: runInShell,
+							title: term.title,
+							message: `Started: ${params.command ?? command}${params.args ? ` ${params.args.join(' ')}` : ''}`,
+						};
+					}
+
+					case 'read': {
+						if (!params.terminalId) {
+							return createToolError(
+								'terminalId is required for read operation',
+							);
+						}
+
+						const term = terminalManager.get(params.terminalId);
+						if (!term) {
+							return createToolError(`Terminal ${params.terminalId} not found`);
+						}
+
+						const output = term.read(params.lines);
+						const normalized = output.map(normalizeTerminalLine);
+						const joined = normalized.join('\n');
+						const text = joined.split(String.fromCharCode(0)).join('');
+
+						const response: {
+							ok: true;
+							terminalId: string;
+							output: string[];
+							status: TerminalStatus;
+							exitCode: number | undefined;
+							lines: number;
+							text: string;
+							rawOutput?: string[];
+						} = {
+							ok: true,
+							terminalId: term.id,
+							output: normalized,
+							status: term.status,
+							exitCode: term.exitCode,
+							lines: normalized.length,
+							text,
+						};
+
+						if (params.raw) {
+							response.rawOutput = output;
+						}
+
+						return response;
+					}
+
+					case 'write': {
+						if (!params.terminalId) {
+							return createToolError(
+								'terminalId is required for write operation',
+							);
+						}
+						if (!params.input) {
+							return createToolError('input is required for write operation');
+						}
+
+						const term = terminalManager.get(params.terminalId);
+						if (!term) {
+							return createToolError(`Terminal ${params.terminalId} not found`);
+						}
+
+						term.write(params.input);
+
+						return {
+							ok: true,
+							terminalId: term.id,
+							message: `Wrote ${params.input.length} characters to terminal`,
+						};
+					}
+
+					case 'interrupt': {
+						if (!params.terminalId) {
+							return createToolError(
+								'terminalId is required for interrupt operation',
+							);
+						}
+
+						const term = terminalManager.get(params.terminalId);
+						if (!term) {
+							return createToolError(`Terminal ${params.terminalId} not found`);
+						}
+
+						term.write('\u0003');
+
+						return {
+							ok: true,
+							terminalId: term.id,
+							message: 'Sent SIGINT (Ctrl+C) to terminal',
+						};
+					}
+
+					case 'list': {
+						const terminals = terminalManager.list();
+
+						return {
+							ok: true,
+							terminals: terminals.map((t) => t.toJSON()),
+							count: terminals.length,
+						};
+					}
+
+					case 'kill': {
+						if (!params.terminalId) {
+							return createToolError(
+								'terminalId is required for kill operation',
+							);
+						}
+
+						await terminalManager.kill(params.terminalId);
+
+						return {
+							ok: true,
+							terminalId: params.terminalId,
+							message: `Killed terminal ${params.terminalId}`,
+						};
+					}
+
+					default:
+						return createToolError(`Unknown operation: ${operation}`);
+				}
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return createToolError(`Terminal operation failed: ${message}`);
+			}
+		},
+	});
+
+	return { name: 'terminal', tool: terminal };
+}

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

@@ -0,0 +1,93 @@
+- Manage persistent terminals for long-running processes (dev servers, watchers, build processes)
+- Returns terminal information and output
+- Supports creating, reading, writing, listing, and killing terminals
+
+## Operations
+
+### start
+- Spawns a new persistent terminal (interactive shell by default)
+- Returns terminal ID for future operations
+- Use for processes that need to stay alive (dev servers, watchers, logs)
+- Before starting, call `terminal(operation: "list")` to see if a matching service is already running
+- Provide a clear `purpose` or `title` (e.g. "web dev server port 9100") so humans can recognize it
+- Parameters:
+  - command (optional when `shell` is true): Command to run
+  - purpose (required): Description of what this terminal is for
+  - title (optional): Short UI label shown beside the terminal
+  - cwd (optional): Working directory relative to project root (default: '.')
+  - args (optional): Array of command arguments
+  - shell (optional, default: true): Launch an interactive shell and run the command via stdin. Set to `false` to spawn the process directly.
+
+### read
+- Read output from a terminal's buffer (last N lines)
+- Strips ANSI escape codes by default so responses are easy to read
+- Parameters:
+  - terminalId (required): Terminal ID from start operation
+  - lines (optional): Number of lines to read from end (default: 100)
+  - raw (optional): Include `rawOutput` array with ANSI escape sequences (default: false)
+- Returns sanitized output lines, combined `text`, status, and exit code
+
+### write
+- Write input to a terminal's stdin
+- Useful for interactive commands or sending signals
+- Parameters:
+  - terminalId (required): Terminal ID
+  - input (required): String to write to stdin
+
+### interrupt
+- Sends SIGINT (Ctrl+C) to the terminal without closing the PTY
+- Useful for stopping dev servers or watchers while keeping the shell alive
+- Parameters:
+  - terminalId (required): Terminal ID
+
+### list
+- List all active terminals
+- Returns array of terminal metadata (id, purpose, status, pid, uptime)
+- No parameters required
+
+### kill
+- Kill a running terminal
+- Sends SIGTERM by default
+- Parameters:
+  - terminalId (required): Terminal ID to kill
+
+## When to Use Terminal vs Bash
+
+### Use terminal for:
+- Dev servers: npm run dev, bun dev
+- File watchers: bun test --watch, nodemon
+- Build watchers: bun build --watch
+- Log tailing: tail -f logs/app.log
+- Background services: docker compose up
+- Any process that needs to stay alive and produce continuous output
+
+### Use bash for:
+- Status checks: git status, ls, ps
+- One-off commands: mkdir, rm, curl
+- Quick scripts: bun run build, git commit
+- File operations: cat, grep, sed
+- Short-lived commands with immediate output
+
+## Example Workflow
+
+1. Start dev server:
+   terminal(operation: "start", command: "npm", args: ["run", "dev"], purpose: "dev server")
+   → Returns { terminalId: "term-abc123", pid: 12345 }
+
+2. Later, check for errors:
+   terminal(operation: "read", terminalId: "term-abc123", lines: 50)
+   → Returns last 50 lines of output
+
+3. Kill when done:
+   terminal(operation: "kill", terminalId: "term-abc123")
+
+## Notes
+
+- Terminals persist across multiple LLM turns (unlike bash commands)
+- Maximum 10 terminals per session
+- Exited terminals auto-cleanup after 5 minutes
+- Output is buffered (last 500 lines kept)
+- Both user-created and LLM-created terminals are visible
+- You can read from user-created terminals to understand context
+- Prefer `read` over `start` when you only need status — avoid duplicating services that already exist
+- Mention running terminals (purpose, command, port) in your responses so humans know what is active

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

@@ -0,0 +1,66 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import DESCRIPTION from './todos.txt' with { type: 'text' };
+
+const STATUS_ENUM = z.enum([
+	'pending',
+	'in_progress',
+	'completed',
+	'cancelled',
+]);
+
+const TODO_SCHEMA = z
+	.union([
+		z.string().min(1, 'Todo steps must be non-empty'),
+		z.object({
+			step: z.string().min(1, 'Todo steps must be non-empty'),
+			status: STATUS_ENUM.optional(),
+		}),
+	])
+	.describe('Todo item');
+
+type TodoItemInput = z.infer<typeof TODO_SCHEMA>;
+
+function normalizeItems(
+	raw: TodoItemInput[],
+): Array<{ step: string; status: z.infer<typeof STATUS_ENUM> }> {
+	const normalized = raw.map((item) => {
+		if (typeof item === 'string') {
+			return { step: item.trim(), status: 'pending' as const };
+		}
+		const step = item.step.trim();
+		const status = item.status ?? 'pending';
+		return { step, status };
+	});
+
+	const filtered = normalized.filter((item) => item.step.length > 0);
+	if (!filtered.length) {
+		throw new Error('At least one todo item is required');
+	}
+
+	const inProgressCount = filtered.filter(
+		(item) => item.status === 'in_progress',
+	).length;
+	if (inProgressCount > 1) {
+		throw new Error('Only one todo item may be marked as in_progress');
+	}
+
+	return filtered;
+}
+
+export const updateTodosTool: Tool = tool({
+	description: DESCRIPTION,
+	inputSchema: z.object({
+		todos: z
+			.array(TODO_SCHEMA)
+			.min(1)
+			.describe('The complete list of todo items'),
+		note: z
+			.string()
+			.optional()
+			.describe('Optional note or context for the update'),
+	}),
+	async execute({ todos, note }: { todos: TodoItemInput[]; note?: string }) {
+		return { items: normalizeItems(todos), note };
+	},
+});

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

@@ -0,0 +1,7 @@
+- Create and manage a list of subtasks for complex requests
+- Displays ordered todo items with status and optional note to the user
+
+Usage tips:
+- Keep descriptions concise (imperative verbs)
+- Update the todos whenever scope changes or new tasks emerge
+- Mark items as in_progress when starting, completed when done

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

@@ -0,0 +1,250 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import DESCRIPTION from './websearch.txt' with { type: 'text' };
+import { createToolError, type ToolResponse } from '../error.ts';
+
+export function buildWebSearchTool(): {
+	name: string;
+	tool: Tool;
+} {
+	const websearch = tool({
+		description: DESCRIPTION,
+		inputSchema: z
+			.object({
+				url: z
+					.string()
+					.optional()
+					.describe(
+						'URL to fetch content from (mutually exclusive with query)',
+					),
+				query: z
+					.string()
+					.optional()
+					.describe(
+						'Search query to search the web (mutually exclusive with url)',
+					),
+				maxLength: z
+					.number()
+					.optional()
+					.default(50000)
+					.describe(
+						'Maximum content length to return (default: 50000 characters)',
+					),
+			})
+			.strict()
+			.refine((data) => (data.url ? !data.query : !!data.query), {
+				message: 'Must provide either url or query, but not both',
+			}),
+		async execute({
+			url,
+			query,
+			maxLength,
+		}: {
+			url?: string;
+			query?: string;
+			maxLength?: number;
+		}): Promise<
+			ToolResponse<
+				| {
+						url: string;
+						content: string;
+						contentLength: number;
+						truncated: boolean;
+						contentType: string;
+				  }
+				| {
+						query: string;
+						results: Array<{ title: string; url: string; snippet: string }>;
+						count: number;
+				  }
+			>
+		> {
+			const maxLen = maxLength ?? 50000;
+
+			if (url) {
+				// Fetch URL content
+				try {
+					const response = await fetch(url, {
+						headers: {
+							'User-Agent':
+								'Mozilla/5.0 (compatible; otto-bot/1.0; +https://github.com/anthropics/otto)',
+							Accept:
+								'text/html,application/xhtml+xml,application/xml;q=0.9,text/plain;q=0.8,*/*;q=0.7',
+						},
+						redirect: 'follow',
+						signal: AbortSignal.timeout(30000), // 30 second timeout
+					});
+
+					if (!response.ok) {
+						throw new Error(
+							`HTTP error! status: ${response.status} ${response.statusText}`,
+						);
+					}
+
+					const contentType = response.headers.get('content-type') || '';
+					let content = '';
+
+					if (
+						contentType.includes('text/') ||
+						contentType.includes('application/json') ||
+						contentType.includes('application/xml') ||
+						contentType.includes('application/xhtml')
+					) {
+						content = await response.text();
+					} else {
+						return createToolError(
+							`Unsupported content type: ${contentType}. Only text-based content can be fetched.`,
+							'unsupported',
+							{ contentType },
+						);
+					}
+
+					// Strip HTML tags for better readability (basic cleaning)
+					const cleanContent = content
+						.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
+						.replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, '')
+						.replace(/<[^>]+>/g, ' ')
+						.replace(/\s+/g, ' ')
+						.trim();
+
+					const truncated = cleanContent.slice(0, maxLen);
+					const wasTruncated = cleanContent.length > maxLen;
+
+					return {
+						ok: true,
+						url,
+						content: truncated,
+						contentLength: cleanContent.length,
+						truncated: wasTruncated,
+						contentType,
+					};
+				} catch (error) {
+					const errorMessage =
+						error instanceof Error ? error.message : String(error);
+					return createToolError(
+						`Failed to fetch URL: ${errorMessage}`,
+						'execution',
+						{ url },
+					);
+				}
+			}
+
+			if (query) {
+				// Web search functionality
+				// Use DuckDuckGo's HTML search (doesn't require API key)
+				try {
+					const searchUrl = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+					const response = await fetch(searchUrl, {
+						headers: {
+							'User-Agent':
+								'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36',
+							Accept: 'text/html',
+						},
+						redirect: 'follow',
+						signal: AbortSignal.timeout(30000),
+					});
+
+					if (!response.ok) {
+						throw new Error(`Search failed: ${response.status}`);
+					}
+
+					const html = await response.text();
+
+					// Parse DuckDuckGo results (basic parsing)
+					const results: Array<{
+						title: string;
+						url: string;
+						snippet: string;
+					}> = [];
+
+					// Match result blocks
+					const resultPattern =
+						/<a[^>]+class="result__a"[^>]+href="([^"]+)"[^>]*>([^<]+)<\/a>[\s\S]*?<a[^>]+class="result__snippet"[^>]*>([\s\S]*?)<\/a>/gi;
+
+					let match: RegExpExecArray | null = null;
+					match = resultPattern.exec(html);
+					while (match !== null && results.length < 10) {
+						const url = match[1]?.trim();
+						const title = match[2]?.trim();
+						let snippet = match[3]?.trim();
+
+						if (url && title) {
+							// Clean snippet
+							snippet = snippet
+								?.replace(/<[^>]+>/g, '')
+								.replace(/\s+/g, ' ')
+								.trim();
+
+							results.push({
+								title,
+								url,
+								snippet: snippet || '',
+							});
+						}
+						match = resultPattern.exec(html);
+					}
+
+					// Fallback: simpler pattern if the above doesn't work
+					if (results.length === 0) {
+						const simplePattern =
+							/<a[^>]+rel="nofollow"[^>]+href="([^"]+)"[^>]*>([^<]+)<\/a>/gi;
+						match = simplePattern.exec(html);
+						while (match !== null && results.length < 10) {
+							const url = match[1]?.trim();
+							const title = match[2]?.trim();
+							if (url && title && url.startsWith('http')) {
+								results.push({
+									title,
+									url,
+									snippet: '',
+								});
+							}
+							match = simplePattern.exec(html);
+						}
+					}
+
+					if (results.length === 0) {
+						return createToolError(
+							'No search results found. The search service may have changed its format or blocked the request.',
+							'execution',
+							{
+								query,
+								suggestion:
+									'Try using the url parameter to fetch a specific webpage instead.',
+							},
+						);
+					}
+
+					return {
+						ok: true,
+						query,
+						results,
+						count: results.length,
+					};
+				} catch (error) {
+					const errorMessage =
+						error instanceof Error ? error.message : String(error);
+					return createToolError(
+						`Search failed: ${errorMessage}`,
+						'execution',
+						{
+							query,
+							suggestion:
+								'Search services may be temporarily unavailable. Try using the url parameter to fetch a specific webpage instead.',
+						},
+					);
+				}
+			}
+
+			return createToolError(
+				'Must provide either url or query parameter',
+				'validation',
+				{
+					suggestion: 'Provide either a url to fetch or a query to search',
+				},
+			);
+		},
+	});
+
+	return { name: 'websearch', tool: websearch };
+}