@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.1

package/examples/extensions/tic-tac-toe.ts

@@ -1,4 +1,4 @@
-/**
+/*
  * Tic-Tac-Toe extension - demonstrates executionMode: "sequential" on tools.
  *
  * The user plays via /tic-tac-toe (arrow keys + Enter).
@@ -18,608 +18,39 @@
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionContext, Theme, ToolExecutionMode } from "@bastani/atomic";
-import { type Component, matchesKey, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionContext, ToolExecutionMode } from "@bastani/atomic";
 import { Type } from "typebox";
-
-// Thrown from the tool on illegal actions. The agent runtime surfaces thrown
-// errors as tool errors (isError=true) without resetting any of our state.
-class TicTacToeError extends Error {
-	constructor(message: string) {
-		super(message);
-		this.name = "TicTacToeError";
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-type Cell = " " | "X" | "O";
-type GameStatus = "playing" | "win_X" | "win_O" | "draw";
-
-interface GameState {
-	board: Cell[][];
-	// User cursor (TUI-only, never exposed to the agent).
-	userCursorRow: number;
-	userCursorCol: number;
-	// Agent cursor (manipulated by the tool, shown in the TUI during O's turn).
-	agentCursorRow: number;
-	agentCursorCol: number;
-	status: GameStatus;
-	userMark: Cell;
-	agentMark: Cell;
-	currentTurn: Cell;
-}
-
-// Persisted with each toolResult for state reconstruction AND sent to the
-// agent as `details`. Only the agent cursor is included: the user cursor is
-// private to the TUI.
-interface BoardDetails {
-	board: Cell[][];
-	agentCursorRow: number;
-	agentCursorCol: number;
-	status: GameStatus;
-	currentTurn: Cell;
-}
-
-// ---------------------------------------------------------------------------
-// Game logic
-// ---------------------------------------------------------------------------
-
-// Agent cursor home: where the cursor is reset to after a SUCCESSFUL play.
-// Pinned at (0,0) so every non-origin play requires at least one move, which
-// guarantees multiple tool calls per turn and makes the parallel-vs-sequential
-// behavior observable in the demo. The cursor is NOT reset when the user plays
-// nor on a failed `play` (cell taken), so the agent can retry without
-// starting over.
-const AGENT_CURSOR_HOME_ROW = 0;
-const AGENT_CURSOR_HOME_COL = 0;
-
-function createInitialState(): GameState {
-	return {
-		board: [
-			[" ", " ", " "],
-			[" ", " ", " "],
-			[" ", " ", " "],
-		],
-		userCursorRow: 1,
-		userCursorCol: 1,
-		agentCursorRow: AGENT_CURSOR_HOME_ROW,
-		agentCursorCol: AGENT_CURSOR_HOME_COL,
-		status: "playing",
-		userMark: "X",
-		agentMark: "O",
-		currentTurn: "X",
-	};
-}
-
-function getWinLine(board: Cell[][]): [number, number][] | null {
-	const lines: [number, number][][] = [
-		[
-			[0, 0],
-			[0, 1],
-			[0, 2],
-		],
-		[
-			[1, 0],
-			[1, 1],
-			[1, 2],
-		],
-		[
-			[2, 0],
-			[2, 1],
-			[2, 2],
-		],
-		[
-			[0, 0],
-			[1, 0],
-			[2, 0],
-		],
-		[
-			[0, 1],
-			[1, 1],
-			[2, 1],
-		],
-		[
-			[0, 2],
-			[1, 2],
-			[2, 2],
-		],
-		[
-			[0, 0],
-			[1, 1],
-			[2, 2],
-		],
-		[
-			[0, 2],
-			[1, 1],
-			[2, 0],
-		],
-	];
-	for (const line of lines) {
-		const vals = line.map(([r, c]) => board[r][c]);
-		if (vals[0] !== " " && vals[0] === vals[1] && vals[1] === vals[2]) {
-			return line;
-		}
-	}
-	return null;
-}
-
-function checkWin(board: Cell[][]): GameStatus {
-	const winLine = getWinLine(board);
-	if (winLine) {
-		const [r, c] = winLine[0];
-		return board[r][c] === "X" ? "win_X" : "win_O";
-	}
-	if (board.every((row) => row.every((c) => c !== " "))) {
-		return "draw";
-	}
-	return "playing";
-}
-
-function boardToAscii(board: Cell[][], agentCursorRow: number, agentCursorCol: number): string {
-	// Plain grid with coordinates for empty cells, marking the agent cursor
-	// position with angle brackets. The user cursor is NEVER included: it is a
-	// TUI-only concept and must not leak to the agent.
-	const rows = board.map((row, r) =>
-		row
-			.map((c, cIdx) => {
-				const onCursor = r === agentCursorRow && cIdx === agentCursorCol;
-				if (c === " ") return onCursor ? `<[${r},${cIdx}]>` : ` [${r},${cIdx}] `;
-				return onCursor ? `   <${c}>   ` : `    ${c}    `;
-			})
-			.join("|"),
-	);
-	const separator = "---------+---------+---------";
-	return rows.join(`\n${separator}\n`);
-}
-
-// ---------------------------------------------------------------------------
-// Visual board rendering (ANSI).
-// - Cells have NO background fill. Only the centered glyph is drawn.
-// - Played cells color their glyph AND their surrounding borders in the
-//   player's color, so each mark reads as a colored boxed region.
-// - Cursor is indicated with colored borders around the cursor cell.
-// ---------------------------------------------------------------------------
-
-const CELL_WIDTH = 7;
-const CELL_HEIGHT = 3;
-
-// Player colors (SGR fg codes). Also used for the borders of played cells.
-const FG_CODE_X = "34"; // blue
-const FG_CODE_O = "33"; // yellow
-const FG_CODE_WIN = "32"; // green (overrides on the winning line)
-
-// Single-character glyphs, picked for maximum visual size without emoji.
-// - \u2573 (BOX DRAWINGS LIGHT DIAGONAL CROSS) for X
-// - \u25ef (LARGE CIRCLE) for O
-const GLYPH_X = "\u2573";
-const GLYPH_O = "\u25ef";
-
-const DIM = (s: string) => `\x1b[2m${s}\x1b[22m`;
-const RESET = "\x1b[0m";
-
-function centerPad(content: string, width: number): string {
-	const contentLen = visibleWidth(content);
-	if (contentLen >= width) return truncateToWidth(content, width);
-	const pad = width - contentLen;
-	const left = Math.floor(pad / 2);
-	return " ".repeat(left) + content + " ".repeat(pad - left);
-}
-
-// Fg color for a played cell's glyph and its surrounding borders. Undefined
-// for empty cells.
-function cellFgCode(cell: Cell, isWin: boolean): string | undefined {
-	if (cell === " ") return undefined;
-	if (isWin) return FG_CODE_WIN;
-	return cell === "X" ? FG_CODE_X : FG_CODE_O;
-}
-
-function buildCellContent(mark: Cell, lineIdx: number, isWin: boolean): string {
-	const empty = " ".repeat(CELL_WIDTH);
-	if (mark === " ") return empty;
-
-	const isMidLine = lineIdx === Math.floor(CELL_HEIGHT / 2);
-	if (!isMidLine) return empty;
-
-	const glyph = mark === "X" ? GLYPH_X : GLYPH_O;
-	const fg = cellFgCode(mark, isWin) as string;
-	const padLen = CELL_WIDTH - visibleWidth(glyph);
-	const leftPad = Math.floor(padLen / 2);
-	const rightPad = padLen - leftPad;
-	return `${" ".repeat(leftPad)}\x1b[${fg};1m${glyph}${RESET}${" ".repeat(rightPad)}`;
-}
-
-// Fg color for a border char based on its adjacent cells. Undefined when no
-// adjacent cell is played or when adjacent plays disagree (border stays dim
-// to show the separation).
-function borderFgCode(adjacent: ReadonlyArray<{ cell: Cell; isWin: boolean }>): string | undefined {
-	const fgs = adjacent.map((a) => cellFgCode(a.cell, a.isWin)).filter((f): f is string => !!f);
-	if (fgs.length === 0) return undefined;
-	const first = fgs[0];
-	return fgs.every((f) => f === first) ? first : undefined;
-}
-
-interface BoardRenderOpts {
-	board: Cell[][];
-	maxWidth: number;
-	// Optional cursor overlay. Omit to render a static snapshot (used in tool
-	// results, move messages, and the game-over banner).
-	cursor?: { row: number; col: number; owner: "user" | "agent" };
-}
-
-function renderBoard(opts: BoardRenderOpts): string[] {
-	const { board, maxWidth, cursor } = opts;
-	const showCursor = !!cursor;
-	const cr = cursor?.row ?? -1;
-	const cc = cursor?.col ?? -1;
-
-	// Green for user cursor, yellow for agent cursor.
-	const cursorSgr = cursor?.owner === "agent" ? "\x1b[33;1m" : "\x1b[32;1m";
-
-	const winLine = getWinLine(board);
-	const winCells = new Set((winLine ?? []).map(([r, c]) => `${r},${c}`));
-	const cellAt = (r: number, c: number) => ({ cell: board[r][c], isWin: winCells.has(`${r},${c}`) });
-
-	const isCursorCorner = (gridR: number, gridC: number): boolean =>
-		showCursor && (gridR === cr || gridR === cr + 1) && (gridC === cc || gridC === cc + 1);
-	const isCursorHSegment = (gridR: number, c: number): boolean =>
-		showCursor && c === cc && (gridR === cr || gridR === cr + 1);
-	const isCursorVBorder = (r: number, gridC: number): boolean =>
-		showCursor && r === cr && (gridC === cc || gridC === cc + 1);
-
-	const paintBorder = (ch: string, highlighted: boolean, fgCode: string | undefined): string => {
-		if (highlighted) return `${cursorSgr}${ch}${RESET}`;
-		if (fgCode) return `\x1b[${fgCode};1m${ch}${RESET}`;
-		return DIM(ch);
-	};
-
-	const cornerChar = (gridR: number, gridC: number): string => {
-		if (gridR === 0 && gridC === 0) return "\u250c";
-		if (gridR === 0 && gridC === 3) return "\u2510";
-		if (gridR === 3 && gridC === 0) return "\u2514";
-		if (gridR === 3 && gridC === 3) return "\u2518";
-		if (gridR === 0) return "\u252c";
-		if (gridR === 3) return "\u2534";
-		if (gridC === 0) return "\u251c";
-		if (gridC === 3) return "\u2524";
-		return "\u253c";
-	};
-
-	const cornerAdjacent = (gridR: number, gridC: number) => {
-		const out: { cell: Cell; isWin: boolean }[] = [];
-		for (const [dr, dc] of [
-			[-1, -1],
-			[-1, 0],
-			[0, -1],
-			[0, 0],
-		]) {
-			const r = gridR + dr;
-			const c = gridC + dc;
-			if (r >= 0 && r < 3 && c >= 0 && c < 3) out.push(cellAt(r, c));
-		}
-		return out;
-	};
-
-	const lines: string[] = [];
-
-	for (let gridR = 0; gridR <= 3; gridR++) {
-		// Horizontal border row.
-		let row = "";
-		for (let gridC = 0; gridC <= 3; gridC++) {
-			const cornerColor = borderFgCode(cornerAdjacent(gridR, gridC));
-			row += paintBorder(cornerChar(gridR, gridC), isCursorCorner(gridR, gridC), cornerColor);
-			if (gridC < 3) {
-				const adj: { cell: Cell; isWin: boolean }[] = [];
-				if (gridR > 0) adj.push(cellAt(gridR - 1, gridC));
-				if (gridR < 3) adj.push(cellAt(gridR, gridC));
-				const segColor = borderFgCode(adj);
-				row += paintBorder("\u2500".repeat(CELL_WIDTH), isCursorHSegment(gridR, gridC), segColor);
-			}
-		}
-		lines.push(centerPad(row, maxWidth));
-
-		if (gridR === 3) break;
-
-		for (let lineIdx = 0; lineIdx < CELL_HEIGHT; lineIdx++) {
-			let contentRow = "";
-			for (let gridC = 0; gridC <= 3; gridC++) {
-				const adj: { cell: Cell; isWin: boolean }[] = [];
-				if (gridC > 0) adj.push(cellAt(gridR, gridC - 1));
-				if (gridC < 3) adj.push(cellAt(gridR, gridC));
-				const vColor = borderFgCode(adj);
-				contentRow += paintBorder("\u2502", isCursorVBorder(gridR, gridC), vColor);
-				if (gridC < 3) {
-					contentRow += buildCellContent(board[gridR][gridC], lineIdx, winCells.has(`${gridR},${gridC}`));
-				}
-			}
-			lines.push(centerPad(contentRow, maxWidth));
-		}
-	}
-
-	return lines;
-}
-
-// Full TUI board with the right cursor overlayed for the current turn.
-function renderVisualBoard(state: GameState, maxWidth: number): string[] {
-	const isUserTurn = state.currentTurn === state.userMark;
-	const cursor =
-		state.status !== "playing"
-			? undefined
-			: {
-					row: isUserTurn ? state.userCursorRow : state.agentCursorRow,
-					col: isUserTurn ? state.userCursorCol : state.agentCursorCol,
-					owner: (isUserTurn ? "user" : "agent") as "user" | "agent",
-				};
-	return renderBoard({ board: state.board, maxWidth, cursor });
-}
-
-/** Static snapshot used inside tool results and custom messages. */
-function renderBoardSnapshot(board: Cell[][], maxWidth: number): string[] {
-	return renderBoard({ board, maxWidth });
-}
-
-// ---------------------------------------------------------------------------
-// TUI component
-// ---------------------------------------------------------------------------
-
-class TicTacToeComponent implements Component {
-	private state: GameState;
-	private onClose: () => void;
-	private onUserPlay: (row: number, col: number) => void;
-	private tui: { requestRender: () => void };
-	private cachedLines: string[] = [];
-	private cachedWidth = 0;
-	private version = 0;
-	private cachedVersion = -1;
-
-	constructor(
-		tui: { requestRender: () => void },
-		onClose: () => void,
-		onUserPlay: (row: number, col: number) => void,
-		state: GameState,
-	) {
-		this.tui = tui;
-		this.onClose = onClose;
-		this.onUserPlay = onUserPlay;
-		this.state = state;
-	}
-
-	updateState(state: GameState): void {
-		this.state = state;
-		this.version++;
-		this.tui.requestRender();
-	}
-
-	handleInput(data: string): boolean {
-		if (matchesKey(data, "escape") || data === "q" || data === "Q") {
-			this.onClose();
-			return true;
-		}
-		if (this.state.status !== "playing") {
-			if (data === "r" || data === "R") {
-				this.onClose();
-				return true;
-			}
-			return true;
-		}
-		if (this.state.currentTurn !== this.state.userMark) return true;
-
-		if (matchesKey(data, "up") && this.state.userCursorRow > 0) {
-			this.state.userCursorRow--;
-			this.version++;
-			this.tui.requestRender();
-		} else if (matchesKey(data, "down") && this.state.userCursorRow < 2) {
-			this.state.userCursorRow++;
-			this.version++;
-			this.tui.requestRender();
-		} else if (matchesKey(data, "left") && this.state.userCursorCol > 0) {
-			this.state.userCursorCol--;
-			this.version++;
-			this.tui.requestRender();
-		} else if (matchesKey(data, "right") && this.state.userCursorCol < 2) {
-			this.state.userCursorCol++;
-			this.version++;
-			this.tui.requestRender();
-		} else if (matchesKey(data, "return") || data === " ") {
-			const { userCursorRow, userCursorCol } = this.state;
-			if (this.state.board[userCursorRow][userCursorCol] === " ") {
-				this.onUserPlay(userCursorRow, userCursorCol);
-			}
-		}
-		return true;
-	}
-
-	invalidate(): void {
-		this.cachedWidth = 0;
-	}
-
-	render(width: number): string[] {
-		if (width === this.cachedWidth && this.cachedVersion === this.version) {
-			return this.cachedLines;
-		}
-
-		const ESC = "\x1b[";
-		const reset = `${ESC}0m`;
-		const bold = (s: string) => `${ESC}1m${s}${reset}`;
-		const dim = (s: string) => `${ESC}2m${s}${reset}`;
-		const blue = (s: string) => `${ESC}34m${s}${reset}`;
-		const yellow = (s: string) => `${ESC}33m${s}${reset}`;
-		const green = (s: string) => `${ESC}32m${s}${reset}`;
-
-		const lines: string[] = [];
-
-		// Top title banner, full width.
-		const titleText = " Tic-Tac-Toe ";
-		const titleLen = visibleWidth(titleText);
-		const borderLen = Math.max(0, width - titleLen);
-		const leftBorder = Math.floor(borderLen / 2);
-		const rightBorder = borderLen - leftBorder;
-		lines.push(dim("\u2500".repeat(leftBorder)) + bold(blue(titleText)) + dim("\u2500".repeat(rightBorder)));
-
-		lines.push("");
-
-		// Status line.
-		if (this.state.status !== "playing") {
-			const statusText =
-				this.state.status === "draw"
-					? bold(yellow("Draw!"))
-					: this.state.status === "win_X"
-						? bold(green("X wins!"))
-						: bold(yellow("O wins!"));
-			lines.push(centerPad(statusText, width));
-		} else if (this.state.currentTurn === "X") {
-			lines.push(centerPad(`Turn: ${bold(blue("X"))} (You)  ${dim("|")}  ${bold(yellow("O"))} (Agent)`, width));
-		} else {
-			lines.push(centerPad(`${blue("X")} (You)  ${dim("|")}  Turn: ${bold(yellow("O"))} (Agent)`, width));
-		}
-
-		lines.push("");
-		lines.push("");
-
-		lines.push(...renderVisualBoard(this.state, width));
-
-		lines.push("");
-		lines.push("");
-
-		// Footer.
-		let footer: string;
-		if (this.state.status !== "playing") {
-			footer = `${bold("R")} restart  ${dim("|")}  ${bold("Q")}/${bold("ESC")} quit`;
-		} else if (this.state.currentTurn !== this.state.userMark) {
-			footer = dim("Agent is thinking...");
-		} else {
-			footer = `${bold("\u2190\u2191\u2193\u2192")} move  ${dim("|")}  ${bold("ENTER")} play  ${dim("|")}  ${bold("ESC")} quit`;
-		}
-		lines.push(centerPad(footer, width));
-
-		// Bottom separator between the component and the editor below.
-		lines.push("");
-		lines.push(dim("\u2500".repeat(width)));
-
-		this.cachedLines = lines;
-		this.cachedWidth = width;
-		this.cachedVersion = this.version;
-		return lines;
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Move-message renderer (full width banner)
-// ---------------------------------------------------------------------------
-
-// Full-width banner message with an optional board snapshot underneath.
-class BannerMessageComponent implements Component {
-	private readonly title: string;
-	private readonly details: BoardDetails | undefined;
-	private readonly expanded: boolean;
-	private readonly theme: Theme;
-
-	constructor(title: string, details: BoardDetails | undefined, expanded: boolean, theme: Theme) {
-		this.title = title;
-		this.details = details;
-		this.expanded = expanded;
-		this.theme = theme;
-	}
-
-	invalidate(): void {}
-
-	render(width: number): string[] {
-		const dim = (s: string) => this.theme.fg("dim", s);
-		const lines: string[] = [];
-		const titleLen = visibleWidth(this.title);
-		const fillLen = Math.max(0, width - titleLen - 2);
-		const leftFill = Math.floor(fillLen / 2);
-		const rightFill = fillLen - leftFill;
-		lines.push(`${dim("\u2500".repeat(leftFill))} ${this.title} ${dim("\u2500".repeat(rightFill))}`);
-
-		if (this.expanded && this.details) {
-			lines.push("");
-			lines.push(...renderBoardSnapshot(this.details.board, width));
-		}
-
-		return lines;
-	}
-}
-
-// End-of-game banner: two dim hrs, a big colored title line, and the final
-// board with the winning line highlighted.
-class GameOverMessageComponent implements Component {
-	private readonly status: GameStatus;
-	private readonly details: BoardDetails | undefined;
-	private readonly theme: Theme;
-
-	constructor(status: GameStatus, details: BoardDetails | undefined, theme: Theme) {
-		this.status = status;
-		this.details = details;
-		this.theme = theme;
-	}
-
-	invalidate(): void {}
-
-	render(width: number): string[] {
-		const dim = (s: string) => this.theme.fg("dim", s);
-		const bold = (s: string) => this.theme.bold(s);
-
-		const hr = dim("\u2500".repeat(width));
-		const lines: string[] = [];
-		lines.push(hr);
-		lines.push("");
-
-		let title: string;
-		let sub: string;
-		switch (this.status) {
-			case "win_X":
-				title = bold(this.theme.fg("accent", "\u2605 Player X wins \u2605"));
-				sub = "You beat the agent.";
-				break;
-			case "win_O":
-				title = bold(this.theme.fg("warning", "\u2605 Player O wins \u2605"));
-				sub = "The agent beat you.";
-				break;
-			case "draw":
-				title = bold(this.theme.fg("muted", "\u2014 Draw \u2014"));
-				sub = "No winner.";
-				break;
-			default:
-				title = bold("Game over");
-				sub = "";
-				break;
-		}
-
-		for (const line of [title, dim(sub)]) {
-			const pad = Math.max(0, width - visibleWidth(line));
-			lines.push(`${" ".repeat(Math.floor(pad / 2))}${line}`);
-		}
-
-		lines.push("");
-		if (this.details) {
-			lines.push(...renderBoardSnapshot(this.details.board, width));
-			lines.push("");
-		}
-		lines.push(hr);
-
-		return lines;
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Delay helper
-// ---------------------------------------------------------------------------
-
-function delay(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-// ---------------------------------------------------------------------------
-// Extension
-// ---------------------------------------------------------------------------
+import { buildTicTacToeInstructions } from "./tic-tac-toe-instructions.js";
+import { BannerMessageComponent, GameOverMessageComponent, TicTacToeComponent } from "./tic-tac-toe-rendering.js";
+import {
+	AGENT_CURSOR_HOME_COL,
+	AGENT_CURSOR_HOME_ROW,
+	TicTacToeError,
+	boardToAscii,
+	checkWin,
+	createInitialState,
+	delay,
+	toBoardDetails,
+	type BoardDetails,
+	type GameState,
+	type GameStatus,
+} from "./tic-tac-toe-state.js";
 
 const SAVE_TYPE = "tic-tac-toe-save";
 const MOVE_MESSAGE_TYPE = "tic-tac-toe-move";
 const GAME_OVER_MESSAGE_TYPE = "tic-tac-toe-game-over";
 
+type Action = "move_up" | "move_down" | "move_left" | "move_right" | "play";
+
+const ACTION_DELAYS: Record<Action, number> = {
+	move_up: 300,
+	move_down: 300,
+	move_left: 300,
+	move_right: 300,
+	play: 0,
+};
+
 let gameState: GameState = createInitialState();
 let component: TicTacToeComponent | null = null;
 let gameActive = false;
@@ -646,13 +77,24 @@ function reconstructState(ctx: ExtensionContext): void {
 }
 
 function getBoardDetails(): BoardDetails {
-	return {
-		board: gameState.board.map((row) => [...row]),
-		agentCursorRow: gameState.agentCursorRow,
-		agentCursorCol: gameState.agentCursorCol,
-		status: gameState.status,
-		currentTurn: gameState.currentTurn,
-	};
+	return toBoardDetails(gameState);
+}
+
+function applyCursorMove(action: Exclude<Action, "play">): string {
+	switch (action) {
+		case "move_up":
+			if (gameState.agentCursorRow > 0) gameState.agentCursorRow--;
+			return `Moved up. Cursor: (${gameState.agentCursorRow}, ${gameState.agentCursorCol})`;
+		case "move_down":
+			if (gameState.agentCursorRow < 2) gameState.agentCursorRow++;
+			return `Moved down. Cursor: (${gameState.agentCursorRow}, ${gameState.agentCursorCol})`;
+		case "move_left":
+			if (gameState.agentCursorCol > 0) gameState.agentCursorCol--;
+			return `Moved left. Cursor: (${gameState.agentCursorRow}, ${gameState.agentCursorCol})`;
+		case "move_right":
+			if (gameState.agentCursorCol < 2) gameState.agentCursorCol++;
+			return `Moved right. Cursor: (${gameState.agentCursorRow}, ${gameState.agentCursorCol})`;
+	}
 }
 
 export default function (pi: ExtensionAPI) {
@@ -679,9 +121,6 @@ export default function (pi: ExtensionAPI) {
 		});
 	};
 
-	// -----------------------------------------------------------------------
-	// Custom message renderer for user move messages
-	// -----------------------------------------------------------------------
 	pi.registerMessageRenderer(MOVE_MESSAGE_TYPE, (message, { expanded }, theme) => {
 		const details = message.details as BoardDetails | undefined;
 		const turnLabel =
@@ -692,89 +131,17 @@ export default function (pi: ExtensionAPI) {
 		return new BannerMessageComponent(title, details, expanded, theme);
 	});
 
-	// -----------------------------------------------------------------------
-	// Custom message renderer for game-over messages
-	// -----------------------------------------------------------------------
 	pi.registerMessageRenderer(GAME_OVER_MESSAGE_TYPE, (message, _options, theme) => {
 		const details = message.details as BoardDetails | undefined;
 		const status = (details?.status ?? "draw") as GameStatus;
 		return new GameOverMessageComponent(status, details, theme);
 	});
 
-	// -----------------------------------------------------------------------
-	// before_agent_start - inject game instructions each turn
-	// -----------------------------------------------------------------------
 	pi.on("before_agent_start", async (event) => {
 		if (!gameActive) return undefined;
-
-		const instructions = `
-
-## Tic-Tac-Toe (you are Player O)
-
-A tic-tac-toe game is in progress. The human is Player X. You are Player O.
-The human plays through a TUI; you play through the \`tic_tac_toe\` tool.
-
-### Turn protocol
-
-When the human plays, you receive a message that contains the cell X marked,
-the full board, and YOUR cursor position (Player O's cursor). The message is
-the source of truth for the board.
-
-Player O's cursor persists between O turns. It is reset to (row=${AGENT_CURSOR_HOME_ROW}, col=${AGENT_CURSOR_HOME_COL})
-only after a successful \`play\`. If a \`play\` fails (cell already taken), the
-cursor stays where it was, so you can move and retry.
-
-You may also call \`tic_tac_toe_see_board\` if you want the current board and
-your cursor position restated at any point. The user's cursor is private and
-is never shown to you.
-
-### The tool
-
-\`tic_tac_toe\` takes ONE action per call:
-- \`move_up\` / \`move_down\` / \`move_left\` / \`move_right\`: move YOUR cursor one cell (clamped at edges)
-- \`play\`: place O on the cell under YOUR cursor. Errors if the cell is not empty.
-
-There is no batched form. One call = one action.
-
-### CRITICAL: emit the whole turn in a single response
-
-To play at (r, c) from your cursor (r0, c0) emit, in order:
-- \`move_down\` (r - r0) times (or \`move_up\` (r0 - r) times if r < r0)
-- \`move_right\` (c - c0) times (or \`move_left\` (c0 - c) times if c < c0)
-- one call of \`play\`
-
-All of these tool calls MUST be emitted in the SAME assistant response, as
-separate tool_use blocks, before you stop. Do not:
-- split the sequence across multiple assistant responses,
-- wait for a move result before emitting the next move or \`play\`,
-- write any explanation or text between the tool calls,
-- call any other tool during your turn (except \`tic_tac_toe_see_board\` when you
-  explicitly need the state restated).
-
-Decide the target cell first, then dump every action for the turn in one go.
-
-### Examples (cursor starts at (${AGENT_CURSOR_HOME_ROW}, ${AGENT_CURSOR_HOME_COL}))
-
-- Target (0,0): one call, \`play\`.
-- Target (0,2): \`move_right\`, \`move_right\`, \`play\`. Three calls, one response.
-- Target (1,1): \`move_down\`, \`move_right\`, \`play\`. Three calls, one response.
-- Target (2,2): \`move_down\`, \`move_down\`, \`move_right\`, \`move_right\`, \`play\`. Five calls, one response.
-
-### Strategy
-
-1. If you have two O's in a line with the third cell empty, win by playing there.
-2. Otherwise, if X has two in a line with the third cell empty, block there.
-3. Otherwise, prefer center, then corners, then edges.
-`;
-
-		return {
-			systemPrompt: event.systemPrompt + instructions,
-		};
+		return { systemPrompt: buildTicTacToeInstructions(event.systemPrompt) };
 	});
 
-	// -----------------------------------------------------------------------
-	// /tic-tac-toe command
-	// -----------------------------------------------------------------------
 	pi.registerCommand("tic-tac-toe", {
 		description: "Play tic-tac-toe against the agent",
 
@@ -842,20 +209,6 @@ Decide the target cell first, then dump every action for the turn in one go.
 		},
 	});
 
-	// -----------------------------------------------------------------------
-	// tic_tac_toe tool - one action per call.
-	// -----------------------------------------------------------------------
-
-	type Action = "move_up" | "move_down" | "move_left" | "move_right" | "play";
-
-	const ACTION_DELAYS: Record<Action, number> = {
-		move_up: 300,
-		move_down: 300,
-		move_left: 300,
-		move_right: 300,
-		play: 0,
-	};
-
 	pi.registerTool({
 		name: "tic_tac_toe",
 		label: "Tic-Tac-Toe",
@@ -879,63 +232,10 @@ Decide the target cell first, then dump every action for the turn in one go.
 			if (actionDelay > 0) await delay(actionDelay);
 
 			let result: string;
-
-			switch (params.action) {
-				case "move_up":
-					if (gameState.agentCursorRow > 0) gameState.agentCursorRow--;
-					result = `Moved up. Cursor: (${gameState.agentCursorRow}, ${gameState.agentCursorCol})`;
-					break;
-				case "move_down":
-					if (gameState.agentCursorRow < 2) gameState.agentCursorRow++;
-					result = `Moved down. Cursor: (${gameState.agentCursorRow}, ${gameState.agentCursorCol})`;
-					break;
-				case "move_left":
-					if (gameState.agentCursorCol > 0) gameState.agentCursorCol--;
-					result = `Moved left. Cursor: (${gameState.agentCursorRow}, ${gameState.agentCursorCol})`;
-					break;
-				case "move_right":
-					if (gameState.agentCursorCol < 2) gameState.agentCursorCol++;
-					result = `Moved right. Cursor: (${gameState.agentCursorRow}, ${gameState.agentCursorCol})`;
-					break;
-				case "play": {
-					if (gameState.status !== "playing") {
-						throw new TicTacToeError(`Game is over (${gameState.status}).`);
-					}
-					if (gameState.currentTurn !== gameState.agentMark) {
-						throw new TicTacToeError("It is not your turn.");
-					}
-					const r = gameState.agentCursorRow;
-					const c = gameState.agentCursorCol;
-					if (gameState.board[r][c] !== " ") {
-						// Do NOT reset the cursor on failure. The agent can retry
-						// from the cursor's current position.
-						component?.updateState(gameState);
-						pi.appendEntry(SAVE_TYPE, getBoardDetails());
-						throw new TicTacToeError(
-							`Cell (${r},${c}) is already ${gameState.board[r][c]}. Your cursor is still at (${r},${c}). Move to an empty cell and retry play.`,
-						);
-					}
-					gameState.board[r][c] = gameState.agentMark;
-					gameState.status = checkWin(gameState.board);
-					// Reset agent cursor to home ONLY on successful play.
-					gameState.agentCursorRow = AGENT_CURSOR_HOME_ROW;
-					gameState.agentCursorCol = AGENT_CURSOR_HOME_COL;
-					if (gameState.status === "playing") {
-						gameState.currentTurn = gameState.userMark;
-						result = `Placed O at (${r},${c}). Cursor reset to (${AGENT_CURSOR_HOME_ROW},${AGENT_CURSOR_HOME_COL}). Your turn, X!`;
-					} else if (gameState.status === "win_O") {
-						result = `Placed O at (${r},${c}). Player O wins!`;
-						gameActive = false;
-						emitGameOverMessage();
-					} else if (gameState.status === "draw") {
-						result = `Placed O at (${r},${c}). It's a draw!`;
-						gameActive = false;
-						emitGameOverMessage();
-					} else {
-						result = `Placed O at (${r},${c}).`;
-					}
-					break;
-				}
+			if (params.action === "play") {
+				result = handleAgentPlay(emitGameOverMessage, () => pi.appendEntry(SAVE_TYPE, getBoardDetails()));
+			} else {
+				result = applyCursorMove(params.action);
 			}
 
 			component?.updateState(gameState);
@@ -966,9 +266,6 @@ Decide the target cell first, then dump every action for the turn in one go.
 		},
 	});
 
-	// -----------------------------------------------------------------------
-	// tic_tac_toe_see_board tool - inspect board + agent cursor.
-	// -----------------------------------------------------------------------
 	pi.registerTool({
 		name: "tic_tac_toe_see_board",
 		label: "See Board",
@@ -1006,3 +303,44 @@ Decide the target cell first, then dump every action for the turn in one go.
 		},
 	});
 }
+
+function handleAgentPlay(emitGameOverMessage: () => void, appendSave: () => void): string {
+	if (gameState.status !== "playing") {
+		throw new TicTacToeError(`Game is over (${gameState.status}).`);
+	}
+	if (gameState.currentTurn !== gameState.agentMark) {
+		throw new TicTacToeError("It is not your turn.");
+	}
+	const r = gameState.agentCursorRow;
+	const c = gameState.agentCursorCol;
+	if (gameState.board[r][c] !== " ") {
+		// Do NOT reset the cursor on failure. The agent can retry
+		// from the cursor's current position.
+		component?.updateState(gameState);
+		appendSave();
+		throw new TicTacToeError(
+			`Cell (${r},${c}) is already ${gameState.board[r][c]}. Your cursor is still at (${r},${c}). Move to an empty cell and retry play.`,
+		);
+	}
+
+	gameState.board[r][c] = gameState.agentMark;
+	gameState.status = checkWin(gameState.board);
+	// Reset agent cursor to home ONLY on successful play.
+	gameState.agentCursorRow = AGENT_CURSOR_HOME_ROW;
+	gameState.agentCursorCol = AGENT_CURSOR_HOME_COL;
+	if (gameState.status === "playing") {
+		gameState.currentTurn = gameState.userMark;
+		return `Placed O at (${r},${c}). Cursor reset to (${AGENT_CURSOR_HOME_ROW},${AGENT_CURSOR_HOME_COL}). Your turn, X!`;
+	}
+	if (gameState.status === "win_O") {
+		gameActive = false;
+		emitGameOverMessage();
+		return `Placed O at (${r},${c}). Player O wins!`;
+	}
+	if (gameState.status === "draw") {
+		gameActive = false;
+		emitGameOverMessage();
+		return `Placed O at (${r},${c}). It's a draw!`;
+	}
+	return `Placed O at (${r},${c}).`;
+}