@agi-cli/sdk 0.1.89 → 0.1.91

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agi-cli/sdk",
-	"version": "0.1.89",
+	"version": "0.1.91",
 	"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,13 @@
+import { ensureBunPtyLibrary } from './ensure-bun-pty.ts';
+
+await ensureBunPtyLibrary();
+
+const bunPty = await import('bun-pty');
+
+export const spawn = bunPty.spawn;
+
+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/ensure-bun-pty.ts

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+
+function resolveLibraryFilename(): string {
+	const platform = process.platform;
+	const arch = process.arch;
+
+	if (platform === 'darwin') {
+		return arch === 'arm64' ? 'librust_pty_arm64.dylib' : 'librust_pty.dylib';
+	}
+
+	if (platform === 'win32') {
+		return 'rust_pty.dll';
+	}
+
+	return arch === 'arm64' ? 'librust_pty_arm64.so' : 'librust_pty.so';
+}
+
+function tryUseExistingPath(path?: string | null): string | null {
+	if (!path) return null;
+	if (existsSync(path)) {
+		process.env.BUN_PTY_LIB = path;
+		return path;
+	}
+	return null;
+}
+
+async function readFromEmbedded(
+	url: URL,
+	targetPath: string,
+): Promise<string | null> {
+	const file = Bun.file(url);
+	if (!(await file.exists())) {
+		return null;
+	}
+
+	const dir = dirname(targetPath);
+	mkdirSync(dir, { recursive: true });
+	await Bun.write(targetPath, file);
+	process.env.BUN_PTY_LIB = targetPath;
+	return targetPath;
+}
+
+export async function ensureBunPtyLibrary(): Promise<string | null> {
+	const already = tryUseExistingPath(process.env.BUN_PTY_LIB);
+	if (already) return already;
+
+	const filename = resolveLibraryFilename();
+	const candidates: string[] = [];
+
+	let pkgUrl: string | null = null;
+	try {
+		pkgUrl = await import.meta.resolve('bun-pty/package.json');
+		const pkgPath = fileURLToPath(pkgUrl);
+		const pkgDir = dirname(pkgPath);
+		candidates.push(
+			join(pkgDir, 'rust-pty', 'target', 'release', filename),
+			join(pkgDir, '..', 'bun-pty', 'rust-pty', 'target', 'release', filename),
+		);
+	} catch {
+		// ignore resolution failures
+	}
+
+	candidates.push(
+		join(
+			process.cwd(),
+			'node_modules',
+			'bun-pty',
+			'rust-pty',
+			'target',
+			'release',
+			filename,
+		),
+	);
+
+	for (const candidate of candidates) {
+		const path = tryUseExistingPath(candidate);
+		if (path) return path;
+	}
+
+	if (pkgUrl) {
+		const embeddedUrl = new URL(
+			`./rust-pty/target/release/${filename}`,
+			pkgUrl,
+		);
+		const tmpPath = join(tmpdir(), 'agi-cli', 'bun-pty', filename);
+		const fromEmbedded = await readFromEmbedded(embeddedUrl, tmpPath);
+		if (fromEmbedded) return fromEmbedded;
+	}
+
+	return null;
+}

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/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):