@ottocode/sdk 0.1.173

package/src/core/src/terminals/terminal.ts

@@ -0,0 +1,132 @@
+import type { IPty } from './bun-pty.ts';
+import { EventEmitter } from 'node:events';
+import { CircularBuffer } from './circular-buffer.ts';
+
+export type TerminalStatus = 'running' | 'exited';
+export type TerminalCreator = 'user' | 'llm';
+
+export interface TerminalOptions {
+	command: string;
+	args?: string[];
+	cwd: string;
+	purpose: string;
+	createdBy: TerminalCreator;
+	title?: string;
+}
+
+export class Terminal {
+	readonly id: string;
+	readonly pty: IPty;
+	readonly command: string;
+	readonly args: string[];
+	readonly cwd: string;
+	readonly purpose: string;
+	readonly createdBy: TerminalCreator;
+	readonly createdAt: Date;
+
+	private buffer: CircularBuffer;
+	private _status: TerminalStatus = 'running';
+	private _exitCode?: number;
+	private _title?: string;
+	private dataEmitter = new EventEmitter();
+	private exitEmitter = new EventEmitter();
+
+	constructor(id: string, pty: IPty, options: TerminalOptions) {
+		this.id = id;
+		this.pty = pty;
+		this.command = options.command;
+		this.args = options.args || [];
+		this.cwd = options.cwd;
+		this.purpose = options.purpose;
+		this.createdBy = options.createdBy;
+		this._title = options.title;
+		this.createdAt = new Date();
+		this.buffer = new CircularBuffer(500);
+
+		this.pty.onData((data) => {
+			// Store in buffer for history
+			this.buffer.push(data);
+			// Emit raw data - terminals need control chars, ANSI codes, etc.
+			this.dataEmitter.emit('data', data);
+		});
+
+		this.pty.onExit(({ exitCode }) => {
+			this._status = 'exited';
+			this._exitCode = exitCode;
+			this.exitEmitter.emit('exit', exitCode);
+		});
+	}
+
+	get pid(): number {
+		return this.pty.pid;
+	}
+
+	get status(): TerminalStatus {
+		return this._status;
+	}
+
+	get exitCode(): number | undefined {
+		return this._exitCode;
+	}
+
+	get title(): string {
+		return this._title || this.purpose;
+	}
+
+	set title(value: string) {
+		this._title = value;
+	}
+
+	read(lines?: number): string[] {
+		return this.buffer.read(lines);
+	}
+
+	clearBuffer(): void {
+		this.buffer.clear();
+	}
+
+	write(input: string): void {
+		this.pty.write(input);
+	}
+
+	kill(signal?: string): void {
+		this.pty.kill(signal);
+	}
+
+	resize(cols: number, rows: number): void {
+		this.pty.resize(cols, rows);
+	}
+
+	onData(callback: (line: string) => void): void {
+		this.dataEmitter.on('data', callback);
+	}
+
+	onExit(callback: (exitCode: number) => void): void {
+		this.exitEmitter.on('exit', callback);
+	}
+
+	removeDataListener(callback: (line: string) => void): void {
+		this.dataEmitter.off('data', callback);
+	}
+
+	removeExitListener(callback: (exitCode: number) => void): void {
+		this.exitEmitter.off('exit', callback);
+	}
+
+	toJSON() {
+		return {
+			id: this.id,
+			pid: this.pid,
+			command: this.command,
+			args: this.args,
+			cwd: this.cwd,
+			purpose: this.purpose,
+			createdBy: this.createdBy,
+			title: this.title,
+			status: this.status,
+			exitCode: this.exitCode,
+			createdAt: this.createdAt,
+			uptime: Date.now() - this.createdAt.getTime(),
+		};
+	}
+}

package/src/core/src/tools/bin-manager.ts

@@ -0,0 +1,250 @@
+import { join } from 'node:path';
+import { promises as fs } from 'node:fs';
+import { spawn, execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+
+const OTTO_BIN_DIR_NAME = 'bin';
+
+let cachedBinDir: string | null = null;
+const resolvedPaths = new Map<string, string>();
+let cachedLoginPath: string | null = null;
+
+function getConfigHome(): string {
+	const cfgHome = process.env.XDG_CONFIG_HOME;
+	if (cfgHome?.trim()) return cfgHome.replace(/\\/g, '/');
+	const home = process.env.HOME || process.env.USERPROFILE || '';
+	return join(home, '.config');
+}
+
+export function getAgiBinDir(): string {
+	if (cachedBinDir) return cachedBinDir;
+	cachedBinDir = join(getConfigHome(), 'otto', OTTO_BIN_DIR_NAME);
+	return cachedBinDir;
+}
+
+function getPlatformKey(): string {
+	const platform = process.platform;
+	const arch = process.arch;
+	const os =
+		platform === 'darwin'
+			? 'darwin'
+			: platform === 'win32'
+				? 'windows'
+				: 'linux';
+	const cpu = arch === 'arm64' ? 'arm64' : 'x64';
+	return `${os}-${cpu}`;
+}
+
+function getBinaryFileName(name: string): string {
+	if (process.platform === 'win32') return `${name}.exe`;
+	return name;
+}
+
+async function ensureDir(dir: string): Promise<void> {
+	await fs.mkdir(dir, { recursive: true });
+}
+
+async function fileExists(p: string): Promise<boolean> {
+	try {
+		await fs.access(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function isExecutable(p: string): Promise<boolean> {
+	try {
+		await fs.access(p, 0o1);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function makeExecutable(p: string): Promise<void> {
+	if (process.platform === 'win32') return;
+	try {
+		await fs.chmod(p, 0o755);
+	} catch {}
+}
+
+async function whichBinary(name: string): Promise<string | null> {
+	const cmd = process.platform === 'win32' ? 'where' : 'which';
+	return new Promise((resolve) => {
+		const proc = spawn(cmd, [name], { stdio: ['ignore', 'pipe', 'ignore'] });
+		let stdout = '';
+		proc.stdout.on('data', (d) => {
+			stdout += d.toString();
+		});
+		proc.on('close', (code) => {
+			if (code === 0 && stdout.trim()) resolve(stdout.trim().split('\n')[0]);
+			else resolve(null);
+		});
+		proc.on('error', () => resolve(null));
+	});
+}
+
+function getVendorSearchPaths(binaryName: string): string[] {
+	const platformKey = getPlatformKey();
+	const paths: string[] = [];
+
+	const tauriResource = process.env.TAURI_RESOURCE_DIR;
+	if (tauriResource) {
+		paths.push(join(tauriResource, 'vendor', 'bin', platformKey, binaryName));
+		paths.push(join(tauriResource, 'vendor', 'bin', binaryName));
+	}
+
+	try {
+		const exePath = process.execPath;
+		if (exePath) {
+			const exeDir = join(exePath, '..');
+			paths.push(join(exeDir, 'vendor', 'bin', platformKey, binaryName));
+			paths.push(
+				join(
+					exeDir,
+					'..',
+					'Resources',
+					'vendor',
+					'bin',
+					platformKey,
+					binaryName,
+				),
+			);
+		}
+	} catch {}
+
+	if (process.env.CARGO_MANIFEST_DIR) {
+		paths.push(
+			join(
+				process.env.CARGO_MANIFEST_DIR,
+				'resources',
+				'vendor',
+				'bin',
+				platformKey,
+				binaryName,
+			),
+		);
+	}
+
+	const cwd = process.cwd();
+	paths.push(join(cwd, 'vendor', 'bin', platformKey, binaryName));
+
+	return paths;
+}
+
+async function extractFromVendor(name: string): Promise<string | null> {
+	const binaryName = getBinaryFileName(name);
+	const binDir = getAgiBinDir();
+	const targetPath = join(binDir, binaryName);
+
+	if ((await fileExists(targetPath)) && (await isExecutable(targetPath))) {
+		return targetPath;
+	}
+
+	const searchPaths = getVendorSearchPaths(binaryName);
+
+	for (const src of searchPaths) {
+		if (await fileExists(src)) {
+			await ensureDir(binDir);
+			await fs.copyFile(src, targetPath);
+			await makeExecutable(targetPath);
+			return targetPath;
+		}
+	}
+
+	return null;
+}
+
+export async function resolveBinary(name: string): Promise<string> {
+	const cached = resolvedPaths.get(name);
+	if (cached) return cached;
+
+	const binaryName = getBinaryFileName(name);
+	const binDir = getAgiBinDir();
+	const installedPath = join(binDir, binaryName);
+	if (
+		(await fileExists(installedPath)) &&
+		(await isExecutable(installedPath))
+	) {
+		resolvedPaths.set(name, installedPath);
+		return installedPath;
+	}
+
+	const vendorPath = await extractFromVendor(name);
+	if (vendorPath) {
+		resolvedPaths.set(name, vendorPath);
+		return vendorPath;
+	}
+
+	const systemPath = await whichBinary(binaryName);
+	if (systemPath) {
+		resolvedPaths.set(name, systemPath);
+		return systemPath;
+	}
+
+	return binaryName;
+}
+
+export function clearBinaryCache(): void {
+	resolvedPaths.clear();
+}
+
+function getLoginShellPath(): string | null {
+	if (cachedLoginPath !== null) return cachedLoginPath;
+
+	if (process.platform === 'win32') {
+		cachedLoginPath = process.env.PATH || '';
+		return cachedLoginPath;
+	}
+
+	const home = process.env.HOME || homedir();
+	const shellCandidates = [
+		process.env.SHELL,
+		'/bin/zsh',
+		'/bin/bash',
+		'/bin/sh',
+	].filter(Boolean) as string[];
+
+	for (const shell of shellCandidates) {
+		try {
+			const result = execSync(`${shell} -ilc 'echo "___PATH___:$PATH"'`, {
+				timeout: 5000,
+				stdio: ['ignore', 'pipe', 'ignore'],
+				env: { HOME: home, USER: process.env.USER || '', SHELL: shell },
+			});
+			const output = result.toString();
+			const match = output.match(/___PATH___:(.*)/);
+			if (match?.[1]?.trim()) {
+				cachedLoginPath = match[1].trim();
+				return cachedLoginPath;
+			}
+		} catch {}
+	}
+
+	cachedLoginPath = null;
+	return null;
+}
+
+export function getAugmentedPath(): string {
+	const sep = process.platform === 'win32' ? ';' : ':';
+	const binDir = getAgiBinDir();
+	const current = process.env.PATH || '';
+	const loginPath = getLoginShellPath();
+
+	const seen = new Set<string>();
+	const parts: string[] = [];
+
+	for (const p of [
+		binDir,
+		...(loginPath ? loginPath.split(sep) : []),
+		...current.split(sep),
+	]) {
+		if (p && !seen.has(p)) {
+			seen.add(p);
+			parts.push(p);
+		}
+	}
+
+	return parts.join(sep);
+}

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

@@ -0,0 +1,155 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import { spawn } from 'node:child_process';
+import DESCRIPTION from './bash.txt' with { type: 'text' };
+import { createToolError, type ToolResponse } from '../error.ts';
+import { getAugmentedPath } from '../bin-manager.ts';
+
+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 buildBashTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const bash = tool({
+		description: DESCRIPTION,
+		inputSchema: z
+			.object({
+				cmd: z.string().describe('Shell command to run (bash -c <cmd>)'),
+				cwd: z
+					.string()
+					.default('.')
+					.describe('Working directory relative to project root'),
+				allowNonZeroExit: z
+					.boolean()
+					.optional()
+					.default(false)
+					.describe('If true, do not throw on non-zero exit'),
+				timeout: z
+					.number()
+					.optional()
+					.default(300000)
+					.describe('Timeout in milliseconds (default: 300000 = 5 minutes)'),
+			})
+			.strict(),
+		async execute({
+			cmd,
+			cwd,
+			allowNonZeroExit,
+			timeout = 300000,
+		}: {
+			cmd: string;
+			cwd?: string;
+			allowNonZeroExit?: boolean;
+			timeout?: number;
+		}): Promise<
+			ToolResponse<{
+				exitCode: number;
+				stdout: string;
+				stderr: string;
+			}>
+		> {
+			const absCwd = resolveSafePath(projectRoot, cwd || '.');
+
+			return new Promise((resolve) => {
+				const proc = spawn(cmd, {
+					cwd: absCwd,
+					shell: true,
+					stdio: ['ignore', 'pipe', 'pipe'],
+					env: { ...process.env, PATH: getAugmentedPath() },
+				});
+
+				let stdout = '';
+				let stderr = '';
+				let didTimeout = false;
+				let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+				if (timeout > 0) {
+					timeoutId = setTimeout(() => {
+						didTimeout = true;
+						proc.kill();
+					}, timeout);
+				}
+
+				proc.stdout?.on('data', (chunk) => {
+					stdout += chunk.toString();
+				});
+
+				proc.stderr?.on('data', (chunk) => {
+					stderr += chunk.toString();
+				});
+
+				proc.on('close', (exitCode) => {
+					if (timeoutId) clearTimeout(timeoutId);
+
+					if (didTimeout) {
+						resolve(
+							createToolError(
+								`Command timed out after ${timeout}ms: ${cmd}`,
+								'timeout',
+								{
+									parameter: 'timeout',
+									value: timeout,
+									suggestion: 'Increase timeout or optimize the command',
+								},
+							),
+						);
+					} else if (exitCode !== 0 && !allowNonZeroExit) {
+						const errorDetail = stderr.trim() || stdout.trim() || '';
+						const errorMsg = `Command failed with exit code ${exitCode}${errorDetail ? `\n\n${errorDetail}` : ''}`;
+						resolve(
+							createToolError(errorMsg, 'execution', {
+								exitCode,
+								stdout,
+								stderr,
+								cmd,
+								suggestion:
+									'Check command syntax or use allowNonZeroExit: true',
+							}),
+						);
+					} else {
+						resolve({
+							ok: true,
+							exitCode: exitCode ?? 0,
+							stdout,
+							stderr,
+						});
+					}
+				});
+
+				proc.on('error', (err) => {
+					if (timeoutId) clearTimeout(timeoutId);
+					resolve(
+						createToolError(
+							`Command execution failed: ${err.message}`,
+							'execution',
+							{
+								cmd,
+								originalError: err.message,
+							},
+						),
+					);
+				});
+			});
+		},
+	});
+	return { name: 'bash', tool: bash };
+}

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

@@ -0,0 +1,7 @@
+- Execute a shell command using `bash -lc`
+- Returns `stdout`, `stderr`, and `exitCode`
+- `cwd` is relative to the project root and sandboxed within it
+
+Usage tips:
+- Chain multiple commands with `&&` to fail-fast
+- For long outputs, consider redirecting to a file and reading it

package/src/core/src/tools/builtin/file-cache.ts

@@ -0,0 +1,39 @@
+/**
+ * File content cache to track modifications during a session/step
+ * This helps ensure tools always work with the latest file content
+ */
+
+const fileContentCache = new Map<string, Map<string, string>>();
+
+export function getFileCache(sessionId: string): Map<string, string> {
+	if (!fileContentCache.has(sessionId)) {
+		fileContentCache.set(sessionId, new Map());
+	}
+	return fileContentCache.get(sessionId) as Map<string, string>;
+}
+
+export function updateFileCache(
+	sessionId: string,
+	filePath: string,
+	content: string,
+): void {
+	const cache = getFileCache(sessionId);
+	cache.set(filePath, content);
+}
+
+export function getCachedContent(
+	sessionId: string,
+	filePath: string,
+): string | undefined {
+	const cache = getFileCache(sessionId);
+	return cache.get(filePath);
+}
+
+export function clearFileCache(sessionId: string): void {
+	fileContentCache.delete(sessionId);
+}
+
+export function clearFileCacheEntry(sessionId: string, filePath: string): void {
+	const cache = getFileCache(sessionId);
+	cache.delete(filePath);
+}

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

@@ -0,0 +1,12 @@
+import { z } from 'zod/v3';
+import { tool } from 'ai';
+import DESCRIPTION from './finish.txt' with { type: 'text' };
+import type { ToolResponse } from '../error.ts';
+
+export const finishTool = tool({
+	description: DESCRIPTION,
+	inputSchema: z.object({}),
+	async execute(): Promise<ToolResponse<{ done: true }>> {
+		return { ok: true, done: true };
+	},
+});

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

@@ -0,0 +1,10 @@
+Call this tool AFTER you have completed all your work AND streamed your final summary/response to the user.
+
+This signals the end of your turn and that you are done with the current request.
+
+**CRITICAL**: You MUST always call this tool when you are completely finished. The workflow is:
+1. Perform all necessary tool calls (read files, make changes, etc.)
+2. Stream your final text response/summary to the user
+3. Call the finish tool to signal completion
+
+Do NOT call finish before streaming your response. Do NOT forget to call finish after responding.

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

@@ -0,0 +1,19 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import DESCRIPTION from './cd.txt' with { type: 'text' };
+
+// description imported above
+
+export function buildCdTool(): { name: string; tool: Tool } {
+	const cd = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			path: z.string().describe('Relative directory path'),
+		}),
+		async execute({ path }: { path: string }) {
+			// Actual cwd update is handled in the adapter; this is a placeholder schema
+			return { cwd: path };
+		},
+	});
+	return { name: 'cd', tool: cd };
+}

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

@@ -0,0 +1,5 @@
+- Change the current working directory (relative to the project root)
+- The runner enforces boundaries; this tool only requests a new cwd
+
+Usage tip:
+- Use PWD to verify the current directory

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

@@ -0,0 +1,20 @@
+import type { Tool } from 'ai';
+import { buildReadTool } from './read.ts';
+import { buildWriteTool } from './write.ts';
+import { buildLsTool } from './ls.ts';
+import { buildTreeTool } from './tree.ts';
+import { buildPwdTool } from './pwd.ts';
+import { buildCdTool } from './cd.ts';
+
+export function buildFsTools(
+	projectRoot: string,
+): Array<{ name: string; tool: Tool }> {
+	const out: Array<{ name: string; tool: Tool }> = [];
+	out.push(buildReadTool(projectRoot));
+	out.push(buildWriteTool(projectRoot));
+	out.push(buildLsTool(projectRoot));
+	out.push(buildTreeTool(projectRoot));
+	out.push(buildPwdTool());
+	out.push(buildCdTool());
+	return out;
+}