pi-tic-tac-toe 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# pi-tic-tac-toe
+
+Play a quick game of tic tac toe against the LLM inside [Pi](https://github.com/earendil-works/pi).
+
+`pi-tic-tac-toe` adds a persistent TUI overlay opened with `/tic-tac-toe`. You play `X`, the LLM plays `O`, and the game stays in your Pi session so you can close the overlay and resume later.
+
+## Features
+
+- Centered terminal overlay, built with Pi TUI
+- Human vs LLM gameplay
+- Arrow-key and number-key input
+- Session persistence across Pi reloads/resumes
+- Validated saved state and legal move checking
+- TypeScript source, no build step required
+- Manual npm publish workflow included
+
+## Install
+
+```bash
+pi install npm:pi-tic-tac-toe
+```
+
+Or add it to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": ["npm:pi-tic-tac-toe"]
+}
+```
+
+## Usage
+
+Start or resume a game:
+
+```text
+/tic-tac-toe
+```
+
+Start a fresh game:
+
+```text
+/tic-tac-toe new
+```
+
+## Controls
+
+| Key | Action |
+| --- | --- |
+| Arrow keys | Move cursor |
+| `1`-`9` | Jump to a square |
+| Enter | Place `X` |
+| `n` | New game |
+| `q` | Close overlay |
+
+The overlay is TUI-only. It will not open in Pi print, JSON, or RPC modes.
+
+## How It Works
+
+After you place `X`, the extension asks the LLM to play `O` by calling:
+
+```text
+make_tic_tac_toe_move
+```
+
+The extension validates every move, so the LLM cannot move out of turn, overwrite a square, or continue after the game is over.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run check
+```
+
+Try the extension locally:
+
+```bash
+pi -e ./extensions/index.ts
+```
+
+Then run:
+
+```text
+/tic-tac-toe
+```
+
+## Package Notes
+
+Pi loads TypeScript extensions directly, so this package publishes the source `.ts` files. Pi core packages are declared as peer dependencies to avoid bundling duplicate Pi runtime packages.
+
+## License
+
+MIT

package/extensions/game.ts

@@ -0,0 +1,128 @@
+export type Mark = "X" | "O";
+export type Winner = Mark | "draw" | null;
+
+export type Move = {
+	cell: number;
+	mark: Mark;
+};
+
+export type GameState = {
+	board: Array<Mark | null>;
+	turn: Mark;
+	history: Move[];
+};
+
+export class TicTacToeGame {
+	board: Array<Mark | null>;
+	turn: Mark;
+	history: Move[];
+
+	constructor(state?: GameState) {
+		const parsed = state ? parseGameState(state) : initialState();
+		this.board = parsed.board;
+		this.turn = parsed.turn;
+		this.history = parsed.history;
+	}
+
+	play(cell: number, mark: Mark): boolean {
+		if (!Number.isInteger(cell) || cell < 0 || cell > 8 || mark !== this.turn || this.board[cell] || this.winner()) return false;
+		this.board[cell] = mark;
+		this.history.push({ cell, mark });
+		this.turn = mark === "X" ? "O" : "X";
+		return true;
+	}
+
+	legalMoves(): number[] {
+		if (this.winner()) return [];
+		return this.board.flatMap((mark, cell) => mark ? [] : [cell]);
+	}
+
+	winner(): Winner {
+		const winners = winnersFor(this.board);
+		if (winners.length) return winners[0];
+		return this.board.every(Boolean) ? "draw" : null;
+	}
+
+	status(): string {
+		const winner = this.winner();
+		if (winner === "draw") return "Draw";
+		if (winner) return `${winner} wins`;
+		return `${this.turn} to move`;
+	}
+
+	toState(): GameState {
+		return { board: this.board.slice(), turn: this.turn, history: this.history.slice() };
+	}
+
+	static fromState(state: unknown): TicTacToeGame {
+		return new TicTacToeGame(parseGameState(state));
+	}
+}
+
+export function boardPrompt(game: TicTacToeGame): string {
+	const cells = game.board.map((mark, i) => mark ?? String(i + 1));
+	return [
+		`${cells[0]} | ${cells[1]} | ${cells[2]}`,
+		`${cells[3]} | ${cells[4]} | ${cells[5]}`,
+		`${cells[6]} | ${cells[7]} | ${cells[8]}`,
+	].join("\n");
+}
+
+export function parseGameState(value: unknown): GameState {
+	if (!isRecord(value)) throw new Error("Invalid state");
+	if (!Array.isArray(value.board) || value.board.length !== 9) throw new Error("Invalid board");
+	if (value.turn !== "X" && value.turn !== "O") throw new Error("Invalid turn");
+	if (!Array.isArray(value.history)) throw new Error("Invalid history");
+
+	const board = value.board.map(parseCell);
+	const turn: Mark = value.turn;
+	const history = value.history.map(parseMove);
+	const state = { board, turn, history };
+	validateState(state);
+	return state;
+}
+
+function initialState(): GameState {
+	return { board: Array<Mark | null>(9).fill(null), turn: "X", history: [] };
+}
+
+function parseCell(value: unknown): Mark | null {
+	if (value === null || value === "X" || value === "O") return value;
+	throw new Error("Invalid board");
+}
+
+function parseMove(value: unknown): Move {
+	if (!isRecord(value) || (value.mark !== "X" && value.mark !== "O")) throw new Error("Invalid history");
+	const cell = value.cell;
+	if (typeof cell !== "number" || !Number.isInteger(cell) || cell < 0 || cell > 8) {
+		throw new Error("Invalid history");
+	}
+	return { cell, mark: value.mark };
+}
+
+function validateState(state: GameState): void {
+	const xs = state.board.filter((mark) => mark === "X").length;
+	const os = state.board.filter((mark) => mark === "O").length;
+	if (os > xs || xs > os + 1) throw new Error("Invalid mark counts");
+
+	const winners = winnersFor(state.board);
+	const winnerSet = new Set(winners);
+	if (winnerSet.size > 1) throw new Error("Invalid board: mixed winners");
+	if (state.turn !== (xs === os ? "X" : "O")) throw new Error("Invalid turn");
+	if (winners[0] === "X" && xs !== os + 1) throw new Error("Invalid winner");
+	if (winners[0] === "O" && xs !== os) throw new Error("Invalid winner");
+}
+
+function winnersFor(board: Array<Mark | null>): Mark[] {
+	return LINES.flatMap(([a, b, c]) => board[a] && board[a] === board[b] && board[a] === board[c] ? [board[a]] : []);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+export const LINES = [
+	[0, 1, 2], [3, 4, 5], [6, 7, 8],
+	[0, 3, 6], [1, 4, 7], [2, 5, 8],
+	[0, 4, 8], [2, 4, 6],
+] as const;

package/extensions/index.ts

@@ -0,0 +1,245 @@
+import type {
+	AgentToolResult,
+	ExtensionAPI,
+	ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	Key,
+	matchesKey,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { boardPrompt, type GameState, TicTacToeGame } from "./game.ts";
+
+const SAVE_TYPE = "tic-tac-toe-save";
+const moveSchema = Type.Object({
+	square: Type.Integer({
+		minimum: 1,
+		maximum: 9,
+		description: "Board square from 1 to 9.",
+	}),
+});
+
+type MoveDetails = { square: number; state: GameState; status: string };
+
+class TicTacToeComponent implements Component {
+	cursor = 4;
+	error = "";
+	private tui: TUI;
+	private game: TicTacToeGame;
+	private onClose: () => void;
+	private onMove: (cell: number) => void;
+	private onNew: () => void;
+
+	constructor(
+		tui: TUI,
+		game: TicTacToeGame,
+		onClose: () => void,
+		onMove: (cell: number) => void,
+		onNew: () => void,
+	) {
+		this.tui = tui;
+		this.game = game;
+		this.onClose = onClose;
+		this.onMove = onMove;
+		this.onNew = onNew;
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "q")) return this.onClose();
+		if (matchesKey(data, "n")) return this.onNew();
+		if (this.game.winner() || this.game.turn !== "X") return;
+
+		const digit = Number(data);
+		if (Number.isInteger(digit) && digit >= 1 && digit <= 9)
+			return this.pick(digit - 1);
+		if (matchesKey(data, Key.enter) || matchesKey(data, Key.return))
+			return this.pick(this.cursor);
+		if (matchesKey(data, Key.up)) this.cursor = Math.max(0, this.cursor - 3);
+		if (matchesKey(data, Key.down)) this.cursor = Math.min(8, this.cursor + 3);
+		if (matchesKey(data, Key.left) && this.cursor % 3) this.cursor--;
+		if (matchesKey(data, Key.right) && this.cursor % 3 < 2) this.cursor++;
+		this.tui.requestRender();
+	}
+
+	pick(cell: number): void {
+		this.cursor = cell;
+		this.onMove(cell);
+	}
+
+	render(width: number): string[] {
+		return [
+			this.center("TIC TAC TOE - You(X) vs LLM(O)", width),
+			"",
+			...this.boardLines(width),
+			"",
+			this.center(`Status: ${this.game.status()}`, width),
+			this.error ? this.center(`Error: ${this.error}`, width) : "",
+			this.center("Arrows/1-9=move  Enter=place  n=new  q=quit", width),
+		].map((line) => truncateToWidth(line, width));
+	}
+
+	boardLines(width: number): string[] {
+		const rows = [0, 3, 6].map((start) =>
+			[0, 1, 2].map((i) => this.cell(start + i)).join("|"),
+		);
+		return rows.flatMap((row, i) =>
+			i < 2
+				? [this.center(row, width), this.center("---+---+---", width)]
+				: [this.center(row, width)],
+		);
+	}
+
+	cell(i: number): string {
+		const mark = this.game.board[i] ?? String(i + 1);
+		return i === this.cursor && this.game.turn === "X" && !this.game.winner()
+			? `[${mark}]`
+			: ` ${mark} `;
+	}
+
+	center(text: string, width: number): string {
+		return (
+			" ".repeat(Math.max(0, Math.floor((width - visibleWidth(text)) / 2))) +
+			text
+		);
+	}
+
+	setGame(game: TicTacToeGame): void {
+		this.game = game;
+		this.cursor = game.legalMoves()[0] ?? 4;
+		this.error = "";
+		this.tui.requestRender();
+	}
+
+	setError(error: string): void {
+		this.error = error;
+		this.tui.requestRender();
+	}
+
+	invalidate(): void {}
+}
+
+export default function ticTacToe(pi: ExtensionAPI): void {
+	let game: TicTacToeGame | null = null;
+	let active: TicTacToeComponent | null = null;
+
+	pi.on("session_start", (_event, ctx) => {
+		game = loadGame(ctx.sessionManager.getBranch());
+	});
+
+	pi.registerCommand("tic-tac-toe", {
+		description: "Play tic tac toe against the LLM",
+		handler: async (args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("Tic tac toe overlay only works in TUI mode", "error");
+				return;
+			}
+			if (!game || game.winner() || args.trim() === "new") {
+				game = new TicTacToeGame();
+				save();
+			}
+			await show(ctx);
+		},
+	});
+
+	pi.registerTool<typeof moveSchema, MoveDetails>({
+		name: "make_tic_tac_toe_move",
+		label: "Tic Tac Toe Move",
+		description: "Place O on the tic tac toe board for the LLM.",
+		parameters: moveSchema,
+		async execute(_id, params) {
+			if (!game || game.turn !== "O") throw new Error("Not the LLM turn.");
+			const cell = params.square - 1;
+			if (!game.play(cell, "O"))
+				throw new Error(`Invalid square. Legal: ${legal()}`);
+			save();
+			active?.setGame(game);
+			return result(
+				`Moved to ${params.square}. ${game.winner() ? game.status() : "X to move."}`,
+				params.square,
+			);
+		},
+	});
+
+	function handleHumanMove(cell: number): void {
+		if (!game?.play(cell, "X"))
+			return active?.setError(`Invalid square: ${cell + 1}`);
+		save();
+		active?.setGame(game);
+		if (game.winner()) return;
+		pi.sendUserMessage(
+			`You are O in tic tac toe. Pick the best legal square and call make_tic_tac_toe_move.\n\nBoard:\n${boardPrompt(game)}\n\nLegal squares: ${legal()}`,
+			{ deliverAs: "steer" },
+		);
+	}
+
+	async function show(ctx: ExtensionCommandContext): Promise<void> {
+		await ctx.ui.custom(
+			(tui, _theme, _keybindings, done) => {
+				active = new TicTacToeComponent(
+					tui,
+					game!,
+					() => {
+						active = null;
+						done(undefined);
+					},
+					handleHumanMove,
+					() => {
+						game = new TicTacToeGame();
+						save();
+						active?.setGame(game);
+					},
+				);
+				return active;
+			},
+			{
+				overlay: true,
+				overlayOptions: {
+					width: "44%",
+					maxHeight: "70%",
+					anchor: "center",
+					margin: { top: 1 },
+				},
+			},
+		);
+	}
+
+	function save(): void {
+		if (game) pi.appendEntry(SAVE_TYPE, game.toState());
+	}
+
+	function legal(): string {
+		return (
+			game
+				?.legalMoves()
+				.map((cell) => cell + 1)
+				.join(", ") ?? ""
+		);
+	}
+
+	function result(text: string, square: number): AgentToolResult<MoveDetails> {
+		return {
+			content: [{ type: "text", text }],
+			details: { square, state: game!.toState(), status: game!.status() },
+		};
+	}
+}
+
+function loadGame(
+	entries: Array<{ type: string; customType?: string; data?: unknown }>,
+): TicTacToeGame | null {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry.type === "custom" && entry.customType === SAVE_TYPE) {
+			try {
+				return TicTacToeGame.fromState(entry.data);
+			} catch {
+				return null;
+			}
+		}
+	}
+	return null;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "pi-tic-tac-toe",
+  "version": "0.1.0",
+  "description": "Tic tac toe extension for Pi",
+  "type": "module",
+  "main": "./extensions/index.ts",
+  "scripts": {
+    "test": "node --test tests/*.test.ts",
+    "check": "tsc --noEmit"
+  },
+  "keywords": ["pi-package", "pi", "extension", "tic-tac-toe"],
+  "files": ["extensions", "README.md"],
+  "pi": {
+    "extensions": ["./extensions/index.ts"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "latest",
+    "@earendil-works/pi-tui": "latest",
+    "@types/node": "latest",
+    "typebox": "latest",
+    "typescript": "latest"
+  },
+  "license": "MIT"
+}