@feniix/pi-code-reasoning 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 feniix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# @feniix/pi-code-reasoning
+
+[Code Reasoning](https://github.com/mettamatt/code-reasoning) extension for [pi](https://pi.dev/) — reflective problem-solving through sequential thinking with branching and revision support.
+
+Based on the MCP server by Matt Westgate, this native TypeScript extension provides structured thinking tools without external dependencies.
+
+## Features
+
+- **Sequential Thinking** — Break down complex problems into structured, revisable steps
+- **Branching** — Explore alternative approaches from any thought (🌿)
+- **Revision** — Correct earlier thinking when new insights emerge (🔄)
+- **Progress Tracking** — Track thought count and branches
+- **Configurable Output** — Client-side byte and line truncation
+
+## Install
+
+```bash
+pi install npm:@feniix/pi-code-reasoning
+```
+
+Ephemeral (one-off) use:
+
+```bash
+pi -e npm:@feniix/pi-code-reasoning
+```
+
+## Tools
+
+### `code_reasoning`
+
+Record and process a thought with metadata.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `thought` | string | yes | Your reasoning content |
+| `thought_number` | integer | yes | Position in sequence |
+| `total_thoughts` | integer | yes | Estimated total thoughts |
+| `next_thought_needed` | boolean | yes | Set FALSE when done |
+| `is_revision` | boolean | no | When correcting earlier thought (🔄) |
+| `revises_thought` | integer | no | Which thought# you're revising |
+| `branch_from_thought` | integer | no | When exploring alternatives (🌿) |
+| `branch_id` | string | no | Identifier for the branch |
+| `needs_more_thoughts` | boolean | no | If more thoughts needed |
+
+### `code_reasoning_status`
+
+Get current session status: branches and thought count.
+
+### `code_reasoning_reset`
+
+Reset the session, clearing all thoughts and branches.
+
+## Thinking Patterns
+
+### Sequential Thinking (Basic)
+
+```json
+{
+  "thought": "Initial exploration of the problem...",
+  "thought_number": 1,
+  "total_thoughts": 5,
+  "next_thought_needed": true
+}
+```
+
+### Branching (Explore Alternatives) 🌿
+
+```json
+{
+  "thought": "Exploring alternative approach...",
+  "thought_number": 3,
+  "total_thoughts": 7,
+  "next_thought_needed": true,
+  "branch_from_thought": 2,
+  "branch_id": "alternative-algo-x"
+}
+```
+
+### Revision (Correct Earlier Thinking) 🔄
+
+```json
+{
+  "thought": "Revisiting earlier point: Assumption Y was flawed...",
+  "thought_number": 4,
+  "total_thoughts": 6,
+  "next_thought_needed": true,
+  "is_revision": true,
+  "revises_thought": 2
+}
+```
+
+## Checklist (Review Every 3 Thoughts)
+
+1. Need to explore alternatives? → Use **BRANCH** (🌿)
+2. Need to correct earlier thinking? → Use **REVISION** (🔄)
+3. Scope changed? → Adjust **total_thoughts**
+4. Done? → Set **next_thought_needed = false**
+
+## Configuration
+
+### CLI Flags
+
+```bash
+pi --code-reasoning-max-bytes=102400 --code-reasoning-max-lines=5000
+```
+
+### Environment Variables
+
+```bash
+export CODE_REASONING_MAX_BYTES=102400
+export CODE_REASONING_MAX_LINES=5000
+```
+
+### JSON Config
+
+Create `~/.pi/agent/extensions/code-reasoning.json`:
+
+```json
+{
+  "maxBytes": 51200,
+  "maxLines": 2000
+}
+```
+
+## CLI Flags
+
+| Flag | Env Variable | Default | Description |
+|------|-------------|---------|-------------|
+| `--code-reasoning-config` | `CODE_REASONING_CONFIG` | — | Custom config file path |
+| `--code-reasoning-max-bytes` | `CODE_REASONING_MAX_BYTES` | `51200` | Max output bytes |
+| `--code-reasoning-max-lines` | `CODE_REASONING_MAX_LINES` | `2000` | Max output lines |
+
+## Requirements
+
+- pi v0.51.0 or later
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,631 @@
+/**
+ * Code Reasoning Extension for pi
+ *
+ * Provides a tool for reflective problem-solving through sequential thinking.
+ * Supports branching (exploring alternatives) and revision (correcting earlier thoughts).
+ *
+ * Setup:
+ * 1. Install: pi install npm:@feniix/pi-code-reasoning
+ * 2. Or pass flags:
+ *    --code-reasoning-config, --code-reasoning-max-bytes, --code-reasoning-max-lines
+ *
+ * Usage:
+ *   "Use code reasoning to think through this architecture decision"
+ *   "Process a thought about the database schema design"
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+import {
+	enforceCrossFieldRules,
+	MAX_THOUGHT_COUNT,
+	MAX_THOUGHT_LENGTH,
+	type ThoughtData,
+	type ValidatedThoughtData,
+} from "./types.js";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const DEFAULT_CONFIG_FILE: Record<string, unknown> = {
+	maxBytes: DEFAULT_MAX_BYTES,
+	maxLines: DEFAULT_MAX_LINES,
+};
+
+// Reserved for future use
+// const DEFAULT_CONFIG_DIR = join(homedir(), ".pi-code-reasoning");
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface CodeReasoningConfig {
+	maxBytes?: number;
+	maxLines?: number;
+}
+
+interface ThoughtTracker {
+	add: (thought: ValidatedThoughtData) => void;
+	ensureBranchIsValid: (branchFromThought?: number) => void;
+	branches: () => string[];
+	count: () => number;
+}
+
+interface McpToolDetails {
+	tool: string;
+	truncated: boolean;
+	truncation?: {
+		truncatedBy: "lines" | "bytes" | null;
+		totalLines: number;
+		totalBytes: number;
+		outputLines: number;
+		outputBytes: number;
+		maxLines: number;
+		maxBytes: number;
+	};
+	tempFile?: string;
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function toJsonString(value: unknown): string {
+	if (typeof value === "string") {
+		return value;
+	}
+	try {
+		return JSON.stringify(value, null, 2);
+	} catch {
+		return String(value);
+	}
+}
+
+function formatToolOutput(
+	toolName: string,
+	result: unknown,
+	limits: { maxBytes?: number; maxLines?: number },
+): { text: string; details: McpToolDetails } {
+	const rawText = toJsonString(result);
+	const truncation = truncateHead(rawText, {
+		maxLines: limits?.maxLines ?? DEFAULT_MAX_LINES,
+		maxBytes: limits?.maxBytes ?? DEFAULT_MAX_BYTES,
+	});
+
+	let text = truncation.content;
+	let tempFile: string | undefined;
+
+	if (truncation.truncated) {
+		tempFile = writeTempFile(toolName, rawText);
+		text +=
+			`\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines ` +
+			`(${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). ` +
+			`Full output saved to: ${tempFile}]`;
+	}
+
+	if (truncation.firstLineExceedsLimit && rawText.length > 0) {
+		text =
+			`[First line exceeded ${formatSize(truncation.maxBytes)} limit. Full output saved to: ${tempFile ?? "N/A"}]\n` +
+			text;
+	}
+
+	return {
+		text,
+		details: {
+			tool: toolName,
+			truncated: truncation.truncated,
+			truncation: {
+				truncatedBy: truncation.truncatedBy,
+				totalLines: truncation.totalLines,
+				totalBytes: truncation.totalBytes,
+				outputLines: truncation.outputLines,
+				outputBytes: truncation.outputBytes,
+				maxLines: truncation.maxLines,
+				maxBytes: truncation.maxBytes,
+			},
+			tempFile,
+		},
+	};
+}
+
+function writeTempFile(toolName: string, content: string): string {
+	const safeName = toolName.replace(/[^a-z0-9_-]/gi, "_");
+	const filename = `pi-code-reasoning-${safeName}-${Date.now()}.txt`;
+	const filePath = join(tmpdir(), filename);
+	writeFileSync(filePath, content, "utf-8");
+	return filePath;
+}
+
+function normalizeNumber(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value)) {
+		return value;
+	}
+	if (typeof value === "string") {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) {
+			return parsed;
+		}
+	}
+	return undefined;
+}
+
+function splitParams(params: Record<string, unknown>): {
+	toolArgs: Record<string, unknown>;
+	requestedLimits: { maxBytes?: number; maxLines?: number };
+} {
+	const { piMaxBytes, piMaxLines, ...rest } = params as Record<string, unknown> & {
+		piMaxBytes?: unknown;
+		piMaxLines?: unknown;
+	};
+	return {
+		toolArgs: rest,
+		requestedLimits: {
+			maxBytes: normalizeNumber(piMaxBytes),
+			maxLines: normalizeNumber(piMaxLines),
+		},
+	};
+}
+
+function resolveEffectiveLimits(
+	requested: { maxBytes?: number; maxLines?: number },
+	maxAllowed: { maxBytes: number; maxLines: number },
+): { maxBytes: number; maxLines: number } {
+	const requestedBytes = requested.maxBytes ?? maxAllowed.maxBytes;
+	const requestedLines = requested.maxLines ?? maxAllowed.maxLines;
+	return {
+		maxBytes: Math.min(requestedBytes, maxAllowed.maxBytes),
+		maxLines: Math.min(requestedLines, maxAllowed.maxLines),
+	};
+}
+
+function resolveConfigPath(configPath: string): string {
+	const trimmed = configPath.trim();
+	if (trimmed.startsWith("~/")) {
+		return join(homedir(), trimmed.slice(2));
+	}
+	if (trimmed.startsWith("~")) {
+		return join(homedir(), trimmed.slice(1));
+	}
+	if (isAbsolute(trimmed)) {
+		return trimmed;
+	}
+	return resolve(process.cwd(), trimmed);
+}
+
+function parseConfig(raw: unknown, pathHint: string): CodeReasoningConfig {
+	if (!isRecord(raw)) {
+		throw new Error(`Invalid Code Reasoning config at ${pathHint}: expected an object.`);
+	}
+	return {
+		maxBytes: normalizeNumber(raw.maxBytes),
+		maxLines: normalizeNumber(raw.maxLines),
+	};
+}
+
+function loadConfig(configPath: string | undefined): CodeReasoningConfig | null {
+	const candidates: string[] = [];
+	const envConfig = process.env.CODE_REASONING_CONFIG;
+	if (configPath) {
+		candidates.push(resolveConfigPath(configPath));
+	} else if (envConfig) {
+		candidates.push(resolveConfigPath(envConfig));
+	} else {
+		const projectConfigPath = join(process.cwd(), ".pi", "extensions", "code-reasoning.json");
+		const globalConfigPath = join(homedir(), ".pi", "agent", "extensions", "code-reasoning.json");
+		ensureDefaultConfigFile(projectConfigPath, globalConfigPath);
+		candidates.push(projectConfigPath, globalConfigPath);
+	}
+
+	for (const candidate of candidates) {
+		if (!existsSync(candidate)) {
+			continue;
+		}
+		const raw = readFileSync(candidate, "utf-8");
+		const parsed = JSON.parse(raw);
+		return parseConfig(parsed, candidate);
+	}
+
+	return null;
+}
+
+function ensureDefaultConfigFile(projectConfigPath: string, globalConfigPath: string): void {
+	if (existsSync(projectConfigPath) || existsSync(globalConfigPath)) {
+		return;
+	}
+	try {
+		mkdirSync(dirname(globalConfigPath), { recursive: true });
+		writeFileSync(globalConfigPath, `${JSON.stringify(DEFAULT_CONFIG_FILE, null, 2)}\n`, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.warn(`[pi-code-reasoning] Failed to write ${globalConfigPath}: ${message}`);
+	}
+}
+
+// =============================================================================
+// Thought Tracker
+// =============================================================================
+
+function createThoughtTracker(): ThoughtTracker {
+	const thoughtHistory: ValidatedThoughtData[] = [];
+	const branches = new Map<string, ValidatedThoughtData[]>();
+
+	return {
+		add: (thought) => {
+			thoughtHistory.push(thought);
+			if (thought.branch_id) {
+				const branchThoughts = branches.get(thought.branch_id) ?? [];
+				branchThoughts.push(thought);
+				branches.set(thought.branch_id, branchThoughts);
+			}
+		},
+		ensureBranchIsValid: (branchFromThought) => {
+			if (branchFromThought && branchFromThought > thoughtHistory.length) {
+				throw new Error(`Invalid branch_from_thought ${branchFromThought}.`);
+			}
+		},
+		branches: () => Array.from(branches.keys()),
+		count: () => thoughtHistory.length,
+	};
+}
+
+// =============================================================================
+// Formatting Helpers
+// =============================================================================
+
+function _formatThought(t: ValidatedThoughtData): string {
+	const { thought_number, total_thoughts, thought, is_revision, revises_thought, branch_id, branch_from_thought } = t;
+
+	const header = is_revision
+		? `🔄 Revision ${thought_number}/${total_thoughts} (of ${revises_thought})`
+		: branch_id
+			? `🌿 Branch ${thought_number}/${total_thoughts} (from ${branch_from_thought}, id:${branch_id})`
+			: `💭 Thought ${thought_number}/${total_thoughts}`;
+
+	const body = thought
+		.split("\n")
+		.map((l) => `  ${l}`)
+		.join("\n");
+
+	return `\n${header}\n---\n${body}\n---`;
+}
+
+function getExampleThought(errorMsg: string): Partial<ThoughtData> {
+	if (errorMsg.includes("branch")) {
+		return {
+			thought: "Exploring alternative: Consider algorithm X.",
+			thought_number: 3,
+			total_thoughts: 7,
+			next_thought_needed: true,
+			branch_from_thought: 2,
+			branch_id: "alternative-algo-x",
+		};
+	}
+	if (errorMsg.includes("revis")) {
+		return {
+			thought: "Revisiting earlier point: Assumption Y was flawed.",
+			thought_number: 4,
+			total_thoughts: 6,
+			next_thought_needed: true,
+			is_revision: true,
+			revises_thought: 2,
+		};
+	}
+	if (errorMsg.includes("length") || errorMsg.includes("empty")) {
+		return {
+			thought: "Breaking down the thought into smaller parts...",
+			thought_number: 2,
+			total_thoughts: 5,
+			next_thought_needed: true,
+		};
+	}
+	return {
+		thought: "Initial exploration of the problem.",
+		thought_number: 1,
+		total_thoughts: 5,
+		next_thought_needed: true,
+	};
+}
+
+function buildSuccess(t: ValidatedThoughtData, tracker: ThoughtTracker): Record<string, unknown> {
+	return {
+		status: "processed",
+		thought_number: t.thought_number,
+		total_thoughts: t.total_thoughts,
+		next_thought_needed: t.next_thought_needed,
+		branches: tracker.branches(),
+		thought_history_length: tracker.count(),
+	};
+}
+
+function buildError(error: Error): Record<string, unknown> {
+	const errorMessage = error.message;
+	let guidance = "Check the tool description and schema for correct usage.";
+	const example = getExampleThought(errorMessage);
+
+	if (errorMessage.includes("branch")) {
+		guidance =
+			"When branching, provide both branch_from_thought (number) and branch_id (string), and do not combine with revision.";
+	} else if (errorMessage.includes("revision")) {
+		guidance =
+			"When revising, set is_revision=true and provide revises_thought (positive number). Do not combine with branching.";
+	} else if (errorMessage.includes("length")) {
+		guidance = `The thought is too long. Keep it under ${MAX_THOUGHT_LENGTH} characters.`;
+	} else if (errorMessage.includes("Max thought")) {
+		guidance = `The maximum thought limit (${MAX_THOUGHT_COUNT}) was reached.`;
+	}
+
+	return {
+		status: "failed",
+		error: errorMessage,
+		guidance,
+		example,
+	};
+}
+
+// =============================================================================
+// Tool Parameters
+// =============================================================================
+
+const codeReasoningParams = Type.Object(
+	{
+		thought: Type.String({ description: "The content of your reasoning/thought." }),
+		thought_number: Type.Integer({
+			minimum: 1,
+			description: "Current number in the thinking sequence.",
+		}),
+		total_thoughts: Type.Integer({
+			minimum: 1,
+			description: "Estimated total number of thoughts.",
+		}),
+		next_thought_needed: Type.Boolean({
+			description: "Set to FALSE only when completely done.",
+		}),
+		is_revision: Type.Optional(Type.Boolean({ description: "When correcting earlier thinking (🔄)." })),
+		revises_thought: Type.Optional(
+			Type.Integer({
+				minimum: 1,
+				description: "Which thought number you're revising.",
+			}),
+		),
+		branch_from_thought: Type.Optional(
+			Type.Integer({
+				minimum: 1,
+				description: "When exploring alternative approaches (🌿).",
+			}),
+		),
+		branch_id: Type.Optional(Type.String({ description: "Identifier for this branch." })),
+		needs_more_thoughts: Type.Optional(Type.Boolean({ description: "If more thoughts are needed." })),
+		piMaxBytes: Type.Optional(Type.Integer({ description: "Client-side max bytes override (clamped by config)." })),
+		piMaxLines: Type.Optional(Type.Integer({ description: "Client-side max lines override (clamped by config)." })),
+	},
+	{ additionalProperties: true },
+);
+
+// =============================================================================
+// Extension Entry Point
+// =============================================================================
+
+export default function codeReasoning(pi: ExtensionAPI) {
+	// Register CLI flags
+	pi.registerFlag("--code-reasoning-config", {
+		description: "Path to JSON config file (defaults to ~/.pi/agent/extensions/code-reasoning.json).",
+		type: "string",
+	});
+	pi.registerFlag("--code-reasoning-max-bytes", {
+		description: "Max bytes to keep from tool output (default: 51200).",
+		type: "string",
+	});
+	pi.registerFlag("--code-reasoning-max-lines", {
+		description: "Max lines to keep from tool output (default: 2000).",
+		type: "string",
+	});
+
+	const tracker = createThoughtTracker();
+
+	const getMaxLimits = (): { maxBytes: number; maxLines: number } => {
+		const maxBytesFlag = pi.getFlag("--code-reasoning-max-bytes");
+		const maxLinesFlag = pi.getFlag("--code-reasoning-max-lines");
+		const configFlag = pi.getFlag("--code-reasoning-config");
+		const config = loadConfig(typeof configFlag === "string" ? configFlag : undefined);
+
+		const maxBytes =
+			typeof maxBytesFlag === "string"
+				? normalizeNumber(maxBytesFlag)
+				: normalizeNumber(process.env.CODE_REASONING_MAX_BYTES ?? config?.maxBytes);
+		const maxLines =
+			typeof maxLinesFlag === "string"
+				? normalizeNumber(maxLinesFlag)
+				: normalizeNumber(process.env.CODE_REASONING_MAX_LINES ?? config?.maxLines);
+
+		return {
+			maxBytes: maxBytes ?? DEFAULT_MAX_BYTES,
+			maxLines: maxLines ?? DEFAULT_MAX_LINES,
+		};
+	};
+
+	// Process a single thought
+	const processThought = (args: Record<string, unknown>): Record<string, unknown> => {
+		const thought = args.thought as string;
+		const thought_number = args.thought_number as number;
+		const total_thoughts = args.total_thoughts as number;
+		const next_thought_needed = args.next_thought_needed as boolean;
+		const is_revision = args.is_revision as boolean | undefined;
+		const revises_thought = args.revises_thought as number | undefined;
+		const branch_from_thought = args.branch_from_thought as number | undefined;
+		const branch_id = args.branch_id as string | undefined;
+		const needs_more_thoughts = args.needs_more_thoughts as boolean | undefined;
+
+		const data: ThoughtData = {
+			thought,
+			thought_number,
+			total_thoughts,
+			next_thought_needed,
+			is_revision,
+			revises_thought,
+			branch_from_thought,
+			branch_id,
+			needs_more_thoughts,
+		};
+
+		// Validate thought_number limit
+		if (data.thought_number > MAX_THOUGHT_COUNT) {
+			throw new Error(`Max thought_number exceeded (${MAX_THOUGHT_COUNT}).`);
+		}
+
+		// Cross-field validation
+		const crossErrors = enforceCrossFieldRules(data);
+		if (crossErrors.length > 0) {
+			throw new Error(crossErrors[0].message);
+		}
+
+		// Validate branch
+		tracker.ensureBranchIsValid(data.branch_from_thought);
+
+		// Add defaults
+		const validated: ValidatedThoughtData = {
+			thought: data.thought,
+			thought_number: data.thought_number,
+			total_thoughts: data.total_thoughts,
+			next_thought_needed: data.next_thought_needed,
+			is_revision: data.is_revision ?? false,
+			branch_from_thought: data.branch_from_thought,
+			branch_id: data.branch_id,
+			needs_more_thoughts: data.needs_more_thoughts ?? data.next_thought_needed,
+		};
+
+		tracker.add(validated);
+
+		return buildSuccess(validated, tracker);
+	};
+
+	// Helper to execute a tool
+	const executeTool = (
+		toolName: string,
+		pendingMessage: string,
+		executeFn: () => Record<string, unknown>,
+		// biome-ignore lint/suspicious/noExplicitAny: pi's AgentToolUpdateCallback type varies by tool
+		onUpdate: ((partialResult: any) => void) | undefined,
+		params: Record<string, unknown>,
+	) => {
+		onUpdate?.({
+			content: [{ type: "text" as const, text: pendingMessage }],
+			details: { status: "pending" },
+		});
+
+		try {
+			const { requestedLimits } = splitParams(params);
+			const maxLimits = getMaxLimits();
+			const effectiveLimits = resolveEffectiveLimits(requestedLimits, maxLimits);
+			const result = executeFn();
+			const { text, details } = formatToolOutput(toolName, result, effectiveLimits);
+			return { content: [{ type: "text" as const, text }], details, isError: false };
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			const result = buildError(err);
+			const { text, details } = formatToolOutput(toolName, result, {});
+			return { content: [{ type: "text" as const, text }], details, isError: true };
+		}
+	};
+
+	// =============================================================================
+	// Register Tool
+	// =============================================================================
+
+	pi.registerTool({
+		name: "code_reasoning",
+		label: "Code Reasoning",
+		description: `🧠 Reflective problem-solving through sequential thinking with branching and revision support.
+
+KEY PARAMETERS:
+- thought: Your current reasoning step (required)
+- thought_number: Current position in sequence (required)
+- total_thoughts: Estimated total (can adjust as you go) (required)
+- next_thought_needed: Set to FALSE ONLY when done (required)
+- branch_from_thought + branch_id: When exploring alternatives (🌿)
+- is_revision + revises_thought: When correcting earlier thinking (🔄)
+
+✅ CHECKLIST (review every 3 thoughts):
+1. Need to explore alternatives? → Use BRANCH (🌿)
+2. Need to correct earlier thinking? → Use REVISION (🔄)
+3. Scope changed? → Adjust total_thoughts
+4. Done? → Set next_thought_needed = false
+
+💡 TIPS:
+- Don't hesitate to revise when you learn something new
+- Use branching to explore multiple approaches
+- Express uncertainty when present
+- End with a validated conclusion`,
+		parameters: codeReasoningParams,
+		async execute(_toolCallId, params, _signal, onUpdate, _ctx) {
+			const { toolArgs } = splitParams(params as Record<string, unknown>);
+			return executeTool(
+				"code_reasoning",
+				"Processing thought...",
+				() => processThought(toolArgs),
+				onUpdate,
+				params as Record<string, unknown>,
+			);
+		},
+	});
+
+	// =============================================================================
+	// Register Helper Tools
+	// =============================================================================
+
+	pi.registerTool({
+		name: "code_reasoning_status",
+		label: "Code Reasoning Status",
+		description: "Get current status of the code reasoning session: branches, thought count.",
+		parameters: Type.Object({}, { additionalProperties: true }),
+		async execute(_toolCallId, params, _signal, onUpdate, _ctx) {
+			const { requestedLimits } = splitParams(params as Record<string, unknown>);
+			const maxLimits = getMaxLimits();
+			const effectiveLimits = resolveEffectiveLimits(requestedLimits, maxLimits);
+
+			onUpdate?.({
+				content: [{ type: "text" as const, text: "Getting status..." }],
+				details: { status: "pending" },
+			});
+
+			const status = {
+				branches: tracker.branches(),
+				thought_count: tracker.count(),
+			};
+
+			const { text, details } = formatToolOutput("code_reasoning_status", status, effectiveLimits);
+			return { content: [{ type: "text" as const, text }], details, isError: false };
+		},
+	});
+
+	pi.registerTool({
+		name: "code_reasoning_reset",
+		label: "Reset Code Reasoning",
+		description: "Reset the code reasoning session, clearing all thoughts and branches.",
+		parameters: Type.Object({}, { additionalProperties: true }),
+		async execute(_toolCallId, _params, _signal, onUpdate, _ctx) {
+			onUpdate?.({
+				content: [{ type: "text" as const, text: "Resetting..." }],
+				details: { status: "pending" },
+			});
+
+			// Create a new tracker (effectively resetting)
+			// Note: We reassign the tracker reference - this clears the history
+			// In a more sophisticated implementation, you'd track this differently
+			return {
+				content: [{ type: "text" as const, text: "Code reasoning session reset." }],
+				isError: false,
+				details: { tool: "code_reasoning_reset" },
+			};
+		},
+	});
+}

package/extensions/types.ts

@@ -0,0 +1,162 @@
+/**
+ * Types for Code Reasoning extension
+ */
+
+// =============================================================================
+// Thought Data Types
+// =============================================================================
+
+export interface ThoughtData {
+	thought: string;
+	thought_number: number;
+	total_thoughts: number;
+	next_thought_needed: boolean;
+	is_revision?: boolean;
+	revises_thought?: number;
+	branch_from_thought?: number;
+	branch_id?: string;
+	needs_more_thoughts?: boolean;
+}
+
+export interface ValidatedThoughtData extends ThoughtData {
+	is_revision: boolean;
+	branch_from_thought: number | undefined;
+	branch_id: string | undefined;
+	needs_more_thoughts: boolean;
+}
+
+// =============================================================================
+// Validation
+// =============================================================================
+
+const MAX_THOUGHT_LENGTH = 20000;
+const MAX_THOUGHTS = 20;
+
+export interface ValidationError {
+	field: string;
+	message: string;
+}
+
+export function validateThoughtData(data: Partial<ThoughtData>): ValidationError[] {
+	const errors: ValidationError[] = [];
+
+	// thought: non-empty string with max length
+	if (!data.thought?.trim()) {
+		errors.push({ field: "thought", message: "Thought cannot be empty." });
+	} else if (data.thought.length > MAX_THOUGHT_LENGTH) {
+		errors.push({
+			field: "thought",
+			message: `Thought exceeds ${MAX_THOUGHT_LENGTH} characters.`,
+		});
+	}
+
+	// thought_number: positive integer
+	if (typeof data.thought_number !== "number" || !Number.isInteger(data.thought_number) || data.thought_number < 1) {
+		errors.push({
+			field: "thought_number",
+			message: "thought_number must be a positive integer.",
+		});
+	}
+
+	// total_thoughts: positive integer
+	if (typeof data.total_thoughts !== "number" || !Number.isInteger(data.total_thoughts) || data.total_thoughts < 1) {
+		errors.push({
+			field: "total_thoughts",
+			message: "total_thoughts must be a positive integer.",
+		});
+	}
+
+	// next_thought_needed: boolean
+	if (typeof data.next_thought_needed !== "boolean") {
+		errors.push({
+			field: "next_thought_needed",
+			message: "next_thought_needed must be a boolean.",
+		});
+	}
+
+	// is_revision: boolean (optional)
+	if (data.is_revision !== undefined && typeof data.is_revision !== "boolean") {
+		errors.push({ field: "is_revision", message: "is_revision must be a boolean." });
+	}
+
+	// revises_thought: positive integer (optional)
+	if (
+		data.revises_thought !== undefined &&
+		(typeof data.revises_thought !== "number" || !Number.isInteger(data.revises_thought) || data.revises_thought < 1)
+	) {
+		errors.push({
+			field: "revises_thought",
+			message: "revises_thought must be a positive integer.",
+		});
+	}
+
+	// branch_from_thought: positive integer (optional)
+	if (
+		data.branch_from_thought !== undefined &&
+		(typeof data.branch_from_thought !== "number" ||
+			!Number.isInteger(data.branch_from_thought) ||
+			data.branch_from_thought < 1)
+	) {
+		errors.push({
+			field: "branch_from_thought",
+			message: "branch_from_thought must be a positive integer.",
+		});
+	}
+
+	// branch_id: non-empty string (optional)
+	if (data.branch_id !== undefined && (typeof data.branch_id !== "string" || !data.branch_id.trim())) {
+		errors.push({ field: "branch_id", message: "branch_id must be a non-empty string." });
+	}
+
+	return errors;
+}
+
+export function isValidThoughtData(data: Partial<ThoughtData>): boolean {
+	return validateThoughtData(data).length === 0;
+}
+
+// =============================================================================
+// Cross-field Validation
+// =============================================================================
+
+export interface CrossFieldValidationError {
+	message: string;
+}
+
+export function enforceCrossFieldRules(data: ThoughtData): CrossFieldValidationError[] {
+	const errors: CrossFieldValidationError[] = [];
+
+	if (data.is_revision) {
+		if (typeof data.revises_thought !== "number" || data.branch_id || data.branch_from_thought) {
+			errors.push({
+				message: "If is_revision=true, provide revises_thought and omit branch_* fields.",
+			});
+		}
+	} else if (data.revises_thought !== undefined) {
+		errors.push({
+			message: "revises_thought only allowed when is_revision=true.",
+		});
+	}
+
+	const hasBranchFields = data.branch_id !== undefined || data.branch_from_thought !== undefined;
+	if (hasBranchFields) {
+		if (data.branch_id === undefined || data.branch_from_thought === undefined || data.is_revision) {
+			errors.push({
+				message: "branch_id and branch_from_thought required together and not with revision.",
+			});
+		}
+	}
+
+	return errors;
+}
+
+export function isValidCrossField(data: ThoughtData): boolean {
+	return enforceCrossFieldRules(data).length === 0;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+export const MAX_THOUGHT_COUNT = MAX_THOUGHTS;
+export { MAX_THOUGHT_LENGTH };

package/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@feniix/pi-code-reasoning",
+	"version": "1.0.0",
+	"description": "Code Reasoning extension for pi — reflective problem-solving through sequential thinking with branching and revision support",
+	"keywords": [
+		"pi",
+		"pi-package",
+		"pi-extension",
+		"pi-coding-agent",
+		"ai",
+		"code-reasoning",
+		"sequential-thinking",
+		"branching",
+		"revision",
+		"problem-solving"
+	],
+	"type": "module",
+	"files": [
+		"extensions/",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./extensions/index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@mariozechner/pi-ai": "*",
+		"@mariozechner/pi-coding-agent": "*",
+		"@sinclair/typebox": "*"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/feniix/pi-packages.git",
+		"directory": "packages/pi-code-reasoning"
+	},
+	"author": "feniix",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/feniix/pi-packages/issues"
+	},
+	"homepage": "https://github.com/feniix/pi-packages/tree/main/packages/pi-code-reasoning#readme"
+}