@agi-cli/sdk 0.1.88 → 0.1.90

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agi-cli/sdk",
-	"version": "0.1.88",
+	"version": "0.1.90",
 	"description": "AI agent SDK for building intelligent assistants - tree-shakable and comprehensive",
 	"author": "ntishxyz",
 	"license": "MIT",
@@ -65,6 +65,10 @@
 			"import": "./src/core/src/tools/builtin/websearch.ts",
 			"types": "./src/core/src/tools/builtin/websearch.ts"
 		},
+		"./tools/builtin/terminal": {
+			"import": "./src/core/src/tools/builtin/terminal.ts",
+			"types": "./src/core/src/tools/builtin/terminal.ts"
+		},
 		"./tools/error": {
 			"import": "./src/core/src/tools/error.ts",
 			"types": "./src/core/src/tools/error.ts"
@@ -82,18 +86,19 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@openauthjs/openauth": "^0.4.3",
-		"opencode-anthropic-auth": "^0.0.2",
-		"ai": "^5.0.43",
 		"@ai-sdk/anthropic": "^2.0.16",
-		"@ai-sdk/openai": "^2.0.30",
 		"@ai-sdk/google": "^2.0.14",
-		"@openrouter/ai-sdk-provider": "^1.2.0",
+		"@ai-sdk/openai": "^2.0.30",
 		"@ai-sdk/openai-compatible": "^1.0.18",
-		"hono": "^4.9.7",
-		"zod": "^4.1.8",
+		"@openauthjs/openauth": "^0.4.3",
+		"@openrouter/ai-sdk-provider": "^1.2.0",
+		"ai": "^5.0.43",
+		"bun-pty": "^0.3.2",
+		"diff": "^8.0.2",
 		"fast-glob": "^3.3.2",
-		"diff": "^8.0.2"
+		"hono": "^4.9.7",
+		"opencode-anthropic-auth": "^0.0.2",
+		"zod": "^4.1.8"
 	},
 	"devDependencies": {
 		"@types/bun": "latest",

package/src/core/src/index.ts

@@ -31,6 +31,7 @@ export type { ProviderId, ModelInfo } from '../../types/src/index.ts';
 // =======================
 export { discoverProjectTools } from './tools/loader';
 export type { DiscoveredTool } from './tools/loader';
+export { setTerminalManager, getTerminalManager } from './tools/loader';
 
 // Tool error handling utilities
 export {
@@ -48,6 +49,19 @@ export type {
 // Re-export builtin tools for direct access
 export { buildFsTools } from './tools/builtin/fs/index';
 export { buildGitTools } from './tools/builtin/git';
+export { buildTerminalTool } from './tools/builtin/terminal';
+
+// =======================
+// Terminals
+// =======================
+export { TerminalManager } from './terminals/index';
+export type {
+	Terminal,
+	TerminalOptions,
+	TerminalStatus,
+	TerminalCreator,
+	CreateTerminalOptions,
+} from './terminals/index';
 
 // =======================
 // Streaming & Artifacts

package/src/core/src/terminals/bun-pty.ts

@@ -0,0 +1,2 @@
+export { spawn } from 'bun-pty';
+export type { IPty, IPtyForkOptions as PtyOptions, IExitEvent } from 'bun-pty';

package/src/core/src/terminals/circular-buffer.ts

@@ -0,0 +1,30 @@
+export class CircularBuffer {
+	private buffer: string[] = [];
+	private maxSize: number;
+
+	constructor(maxSize = 500) {
+		this.maxSize = maxSize;
+	}
+
+	push(line: string): void {
+		this.buffer.push(line);
+		if (this.buffer.length > this.maxSize) {
+			this.buffer.shift();
+		}
+	}
+
+	read(lines?: number): string[] {
+		if (lines === undefined) {
+			return [...this.buffer];
+		}
+		return this.buffer.slice(-lines);
+	}
+
+	clear(): void {
+		this.buffer = [];
+	}
+
+	get length(): number {
+		return this.buffer.length;
+	}
+}

package/src/core/src/terminals/index.ts

@@ -0,0 +1,8 @@
+export { TerminalManager, type CreateTerminalOptions } from './manager.ts';
+export {
+	Terminal,
+	type TerminalOptions,
+	type TerminalStatus,
+	type TerminalCreator,
+} from './terminal.ts';
+export { CircularBuffer } from './circular-buffer.ts';

package/src/core/src/terminals/manager.ts

@@ -0,0 +1,154 @@
+import { spawn as spawnPty } from './bun-pty.ts';
+import { randomBytes } from 'node:crypto';
+import { Terminal } from './terminal.ts';
+import type { PtyOptions } from './bun-pty.ts';
+
+const MAX_TERMINALS = 10;
+const CLEANUP_DELAY_MS = 5 * 60 * 1000;
+
+export interface CreateTerminalOptions {
+	command: string;
+	args?: string[];
+	cwd: string;
+	purpose: string;
+	createdBy: 'user' | 'llm';
+	title?: string;
+}
+
+export class TerminalManager {
+	private terminals = new Map<string, Terminal>();
+	private cleanupTimers = new Map<string, NodeJS.Timeout>();
+
+	constructor() {
+		process.on('SIGTERM', () => this.killAll());
+		process.on('SIGINT', () => this.killAll());
+	}
+
+	create(options: CreateTerminalOptions): Terminal {
+		if (this.terminals.size >= MAX_TERMINALS) {
+			throw new Error(`Maximum ${MAX_TERMINALS} terminals reached`);
+		}
+
+		const id = this.generateId();
+
+		try {
+			console.log('[TerminalManager] Creating terminal:', {
+				id,
+				command: options.command,
+				args: options.args,
+				cwd: options.cwd,
+				purpose: options.purpose,
+			});
+
+			const ptyOptions: PtyOptions = {
+				name: 'xterm-256color',
+				cols: 80,
+				rows: 30,
+				cwd: options.cwd,
+				env: process.env as Record<string, string>,
+			};
+
+			const pty = spawnPty(options.command, options.args || [], ptyOptions);
+
+			console.log('[TerminalManager] PTY created successfully:', pty.pid);
+
+			const terminal = new Terminal(id, pty, options);
+
+			terminal.onExit((_exitCode) => {
+				const timer = setTimeout(() => {
+					this.delete(id);
+				}, CLEANUP_DELAY_MS);
+
+				this.cleanupTimers.set(id, timer);
+			});
+
+			this.terminals.set(id, terminal);
+
+			console.log('[TerminalManager] Terminal added to map');
+
+			return terminal;
+		} catch (error) {
+			console.error('[TerminalManager] Failed to create terminal:', error);
+			throw error;
+		}
+	}
+
+	get(id: string): Terminal | undefined {
+		return this.terminals.get(id);
+	}
+
+	list(): Terminal[] {
+		return Array.from(this.terminals.values());
+	}
+
+	async kill(id: string): Promise<void> {
+		const terminal = this.terminals.get(id);
+		if (!terminal) {
+			throw new Error(`Terminal ${id} not found`);
+		}
+
+		terminal.kill();
+
+		await new Promise<void>((resolve) => {
+			if (terminal.status === 'exited') {
+				resolve();
+				return;
+			}
+
+			const exitHandler = () => {
+				terminal.removeExitListener(exitHandler);
+				resolve();
+			};
+
+			terminal.onExit(exitHandler);
+
+			setTimeout(() => {
+				terminal.removeExitListener(exitHandler);
+				resolve();
+			}, 5000);
+		});
+
+		this.delete(id);
+	}
+
+	async killAll(): Promise<void> {
+		const killPromises = Array.from(this.terminals.keys()).map((id) =>
+			this.kill(id).catch((err) =>
+				console.error(`Failed to kill terminal ${id}:`, err),
+			),
+		);
+
+		await Promise.all(killPromises);
+	}
+
+	delete(id: string): boolean {
+		const timer = this.cleanupTimers.get(id);
+		if (timer) {
+			clearTimeout(timer);
+			this.cleanupTimers.delete(id);
+		}
+
+		return this.terminals.delete(id);
+	}
+
+	private generateId(): string {
+		return `term-${randomBytes(8).toString('hex')}`;
+	}
+
+	getContext(): string {
+		const terminals = this.list();
+
+		if (terminals.length === 0) {
+			return '';
+		}
+
+		const summary = terminals
+			.map(
+				(t) =>
+					`- [${t.id}] ${t.purpose} (${t.status}, ${t.createdBy}, pid: ${t.pid})`,
+			)
+			.join('\n');
+
+		return `\n\n## Active Terminals (${terminals.length}):\n${summary}\n\nYou can read from any terminal using the 'terminal' tool with operation: 'read'.`;
+	}
+}

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

@@ -0,0 +1,124 @@
+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);
+	}
+
+	write(input: string): void {
+		this.pty.write(input);
+	}
+
+	kill(signal?: string): void {
+		this.pty.kill(signal);
+	}
+
+	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/builtin/patch/apply.ts

@@ -259,6 +259,12 @@ function applyHunkToLines(
 		.map((line) => line.content);
 
 	const removals = hunk.lines.filter((line) => line.kind === 'remove');
+	const additions = hunk.lines
+		.filter((line) => line.kind === 'add')
+		.map((line) => line.content);
+	const contextLines = hunk.lines
+		.filter((line) => line.kind === 'context')
+		.map((line) => line.content);
 
 	const hasExpected = expected.length > 0;
 	const initialHint =

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

@@ -0,0 +1,299 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+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 text = normalized.join('\n').replace(/\u0000/g, '');
+
+						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/loader.ts

@@ -12,6 +12,8 @@ import { buildApplyPatchTool } from './builtin/patch.ts';
 import { updatePlanTool } from './builtin/plan.ts';
 import { editTool } from './builtin/edit.ts';
 import { buildWebSearchTool } from './builtin/websearch.ts';
+import { buildTerminalTool } from './builtin/terminal.ts';
+import type { TerminalManager } from '../terminals/index.ts';
 import fg from 'fast-glob';
 import { dirname, isAbsolute, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -90,6 +92,16 @@ type FsHelpers = {
 
 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,
@@ -120,6 +132,11 @@ export async function discoverProjectTools(
 	// 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);
+	}
 
 	async function loadFromBase(base: string | null | undefined) {
 		if (!base) return;

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/index.ts

@@ -120,9 +120,20 @@ export type { ProviderName, ModelConfig } from './core/src/index.ts';
 // Tools
 export { discoverProjectTools } from './core/src/index.ts';
 export type { DiscoveredTool } from './core/src/index.ts';
+export { setTerminalManager, getTerminalManager } from './core/src/index.ts';
 export { buildFsTools } from './core/src/index.ts';
 export { buildGitTools } from './core/src/index.ts';
 
+// Terminals
+export { TerminalManager } from './core/src/index.ts';
+export type {
+	Terminal,
+	TerminalOptions,
+	TerminalStatus,
+	TerminalCreator,
+	CreateTerminalOptions,
+} from './core/src/index.ts';
+
 // Streaming & Artifacts
 export {
 	createFileDiffArtifact,

package/src/prompts/src/agents/build.txt

@@ -4,6 +4,14 @@ You help with coding and build tasks.
 - Keep tool inputs short; avoid long prose inside tool parameters.
 - Stream your answer, then call finish.
 
+## Terminal Tool Workflow
+
+- List existing terminals before starting new ones to avoid duplicate dev servers or watchers.
+- Reuse running services when possible; read their output instead of spawning another copy.
+- When starting a terminal, give it a descriptive purpose/title (e.g. "web dev server 9100" or "bun test --watch") and prefer `terminal(...)` over `bash(...)` for long-lived tasks.
+- Use `terminal(operation: "write", input: "\u0003")` or `terminal(operation: "interrupt")` to stop a process before resorting to `kill`.
+- Summarize active terminals (purpose, key command, port) in your updates so collaborators know what's running.
+
 ## File Editing Best Practices
 
 **Using the `apply_patch` Tool** (Recommended):
@@ -29,9 +37,45 @@ You help with coding and build tasks.
  actual line from file        ← Context (space prefix) - REQUIRED
 -line to remove               ← Remove this line
 +line to add                  ← Add this line
- more context                 ← More context (space prefix)
+more context                 ← More context (space prefix)
 ```
 
+## ⚠️ Why Patches Fail (Common Mistakes)
+
+**Mistake 1: Patching from Memory** (Most Common)
+- ❌ Creating patches based on what you remember from earlier
+- ✅ ALWAYS read the file FIRST in this same turn, then create patch
+
+**Mistake 2: Context Lines Don't Match File**
+- ❌ Guessing or inventing what context lines look like
+- ✅ Copy context lines EXACTLY character-for-character from the file you just read
+- Context lines (space prefix) must exist in the actual file
+
+**Mistake 3: Wrong Indentation**
+- ❌ File uses 2 spaces; patch uses tabs or 4 spaces
+- ✅ Match indentation exactly: if file uses spaces, patch uses spaces (same count)
+
+**Mistake 4: Missing Markers**
+- ❌ Forgot `*** End Patch` or malformed `*** Begin Patch`
+- ✅ Always wrap: `*** Begin Patch` ... hunks ... `*** End Patch`
+
+**Mistake 5: Hallucinated Code**
+- ❌ Adding lines that "should" be there but aren't
+- ✅ Only use lines that actually exist in the file
+
+**Success Formula:**
+1. Read file with `read` tool
+2. Note exact indentation (spaces/tabs), line content
+3. Extract 2-3 context lines before/after your change
+4. Copy them EXACTLY into patch with space prefix
+5. Add your `-old` and `+new` lines
+6. Verify markers: `*** Begin Patch` and `*** End Patch`
+
+**When Patch Fails:**
+- Error means context didn't match or file changed
+- Solution: Read the file AGAIN, check character-for-character
+- If still failing repeatedly, use `edit` tool instead
+
 **Using the `edit` Tool** (Alternative):
 - Specify the file path and a list of operations
 - Operations are applied sequentially to the latest file state

package/src/prompts/src/base.txt

@@ -15,7 +15,8 @@ You MUST call the `finish` tool at the end of every response to signal completio
 **IMPORTANT**: Do NOT call `finish` before streaming your response. Always stream your message first, then call `finish`. If you forget to call `finish`, the system will hang and not complete properly.
 
 File Editing Best Practices:
-- ALWAYS read a file immediately before using apply_patch on it - never patch from memory
+- ⚠️ CRITICAL: ALWAYS read a file immediately before using apply_patch - never patch from memory
+- Read the file in THIS turn, not from previous context or memory
 - When making multiple edits to the same file, combine them into a single edit operation with multiple ops
 - Each edit operation re-reads the file, so ops within a single edit call are applied sequentially to the latest content
 - If you need to make edits based on previous edits, ensure they're in the same edit call or re-read the file between calls

package/src/prompts/src/providers/anthropic.txt

@@ -210,6 +210,28 @@ NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTAN
 
 IMPORTANT: Always use the update_plan tool to plan and track tasks throughout the conversation.
 
+# Apply Patch Tool - Critical Guidelines for Claude
+
+**⚠️ Claude-Specific Patch Failures:**
+
+You (Claude/Sonnet) generally excel at using patches, but even you can fail when:
+- Relying on memory from earlier in the conversation instead of fresh file reads
+- Making assumptions about unchanged file state between operations
+- Mixing tabs/spaces when file indentation isn't verified first
+
+**Your Success Pattern (Follow This):**
+1. Read file with `read` tool immediately before patching
+2. Extract exact context lines (space prefix) from what you just read
+3. Match indentation character-for-character
+4. Use multiple `@@` hunks for multiple edits in same file
+5. Wrap in `*** Begin Patch` and `*** End Patch`
+
+**If Patch Fails:**
+- Don't retry with same context - read file AGAIN first
+- Check that context lines exist exactly as written
+- Verify indentation matches (spaces vs tabs)
+- If failing 2+ times, switch to `edit` tool instead
+
 # Code References
 
 When referencing specific functions or pieces of code include the pattern `file_path:line_number` to allow the user to easily navigate to the source code location.

package/src/prompts/src/providers/default.txt

@@ -427,6 +427,38 @@ When using the shell, you must adhere to the following guidelines:
 - When searching for text or files, prefer using `rg` or `rg --files` respectively because `rg` is much faster than alternatives like `grep`. (If the `rg` command is not found, then use alternatives.)
 - Read files in chunks with a max chunk size of 250 lines. Do not use python scripts to attempt to output larger chunks of a file. Command line output will be truncated after 10 kilobytes or 256 lines of output, regardless of the command used.
 
+## Apply Patch Tool - Critical Guidelines
+
+**⚠️ Common Patch Failures Across All Models:**
+
+Most patch failures happen because:
+- Patches created from memory instead of reading file first
+- Context lines guessed or invented rather than copied exactly
+- Indentation mismatches (tabs vs spaces)
+- Missing or malformed markers (`*** Begin Patch` / `*** End Patch`)
+- Hallucinated code in context lines
+
+**Universal Pre-Flight Checklist:**
+Before calling `apply_patch`, verify ALL of these:
+- [ ] File was read with `read` tool in THIS turn (not from memory)
+- [ ] Context lines (space prefix) copied EXACTLY character-for-character
+- [ ] Indentation verified (if file uses spaces, patch uses spaces)
+- [ ] Wrapped in `*** Begin Patch` and `*** End Patch` markers
+- [ ] Used correct directive: `*** Add/Update/Delete File: path`
+
+**Success Formula:**
+1. Use `read` tool on target file
+2. Identify exact location to edit
+3. Extract 2-3 lines before/after as context (space prefix)
+4. Add `-old` lines to remove, `+new` lines to add
+5. Wrap in `*** Begin Patch` ... `*** End Patch`
+6. Verify all context matches file exactly
+
+**If Patch Fails:**
+- Error = context didn't match OR file content changed
+- Solution: Read file AGAIN, verify context character-by-character
+- After 2+ failures: use `edit` tool instead (more forgiving)
+
 ## `update_plan`
 
 A tool named `update_plan` is available to you. You can use it to keep an up‑to‑date, step‑by‑step plan for the task.

package/src/prompts/src/providers/openai.txt

@@ -366,6 +366,37 @@ When using the shell, you must adhere to the following guidelines:
   - Shell commands should be reserved for execution, not discovery
 - Read files in chunks with a max chunk size of 250 lines. Do not use python scripts to attempt to output larger chunks of a file. Command line output will be truncated after 10 kilobytes or 256 lines of output, regardless of the command used.
 
+## Apply Patch Tool - Critical for GPT-4 Models
+
+**⚠️ GPT-4 Common Patch Failures:**
+
+GPT-4 models (especially GPT-4o) often fail patches by:
+- Creating patches from memory instead of reading the file first
+- Guessing at context lines that don't match the actual file
+- Missing or malformed `*** End Patch` markers
+- Mixing tabs/spaces without checking file's indentation
+
+**Mandatory Pre-Flight Checklist (Check EVERY time):**
+- [ ] Read the target file with `read` tool in THIS turn
+- [ ] Copy context lines EXACTLY from what you just read
+- [ ] Verify indentation (spaces vs tabs) matches the file
+- [ ] Include `*** Begin Patch` and `*** End Patch` markers
+- [ ] Use space prefix for context lines (NOT `@@` line - that's just a hint)
+
+**GPT-4 Success Formula:**
+1. Call `read` on the file you want to patch
+2. Identify the exact lines to change
+3. Copy 2-3 surrounding lines AS-IS (space prefix)
+4. Add your `-removal` and `+addition` lines
+5. Wrap in `*** Begin Patch` ... `*** End Patch`
+6. Double-check markers and indentation before calling tool
+
+**If Your Patch Fails:**
+- You didn't read the file first, OR
+- Context lines don't match file character-for-character
+- Solution: Read file AGAIN, copy exact lines
+- After 2 failures: switch to `edit` tool instead
+
 ## `update_plan`
 
 A tool named `update_plan` is available to you. You can use it to keep an up‑to‑date, step‑by‑step plan for the task.