@pandi-coding-agent/typescript-lsp 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# @pandi-coding-agent/typescript-lsp
+
+TypeScript **diagnostics feedback** from inside a Pi session. After the agent
+finishes a turn that wrote or edited TypeScript, this extension runs
+`tsc --noEmit` on the relevant project(s), keeps only the **files the turn
+actually touched**, and surfaces a bounded top-N report.
+
+> **Not a full LSP.** The package name says "lsp", but the real contract is
+> diagnostics only — there is **no hover, no go-to-definition, no completions**.
+> Think of it as "did my TypeScript edits still compile?" feedback.
+
+## Why the coherent edge?
+
+Diagnostics fire on **`agent_end`** — the coherent edge, after the whole turn
+finishes — not after every individual write/edit. Mid-turn a file is often
+half-edited and would report transient, misleading errors. Checking once at the
+edge, scoped to touched files, gives honest signal with minimal noise. It is
+**non-blocking**: a tool call is never blocked, and a missing tsconfig/tsc is a
+quiet NO-OP (one advisory warning), never a broken session.
+
+## Surfaces
+
+- **Automatic feedback** on `agent_end` (advisory by default).
+- **`typescript_diagnostics`** — a model-callable tool (pull / on-demand).
+- **`/tsc`** — a human slash command.
+
+`tsc` is always spawned with an **argv array (never a shell string)**, exactly as
+`pi-worktree` spawns `git`, so paths cannot inject shell commands.
+
+## Feedback modes
+
+- **advisory** (default): if touched files have type errors, the report is sent
+  as a non-blocking message delivered on the next turn
+  (`sendMessage({ deliverAs: "nextTurn" })`). Identical reports are de-duplicated
+  so the same errors are not re-injected turn after turn.
+- **autofix** (opt-in): the report is delivered as a follow-up that triggers a
+  turn (`deliverAs: "followUp", triggerTurn: true`) so the agent fixes the errors
+  immediately. There is a **per-prompt budget** (default 1 auto-triggered fix)
+  plus the same de-duplication, so it can never loop. It **never** blocks.
+
+## Tool
+
+`typescript_diagnostics` takes an optional `scope`:
+
+- `touched` (default): only the files edited so far this turn.
+- `project`: the whole `<cwd>/tsconfig.json`.
+
+It returns a text summary plus structured `details`
+(`{ scope, hasErrors, count, diagnostics }`).
+
+## Command
+
+```text
+/tsc                       show status
+/tsc status                show status
+/tsc on | off              enable / disable automatic feedback
+/tsc run                   run a check now and report
+/tsc scope touched|project set the default scope
+/tsc autofix on|off        switch advisory ↔ autofix
+/tsc max <n>               cap how many diagnostics are surfaced
+```
+
+## tsc resolution
+
+In order:
+
+1. `PI_TS_LSP_TSC` — absolute path to a `tsc.js`, executed with the current
+   `node`.
+2. The nearest `node_modules/typescript/bin/tsc`, walking up from the tsconfig
+   directory.
+3. Fallback: `npx tsc`.
+
+If neither a tsconfig nor a tsc can be found, the extension is a NO-OP with a
+single advisory warning.
+
+## Configuration (env)
+
+| Variable          | Meaning                                  | Default    |
+| ----------------- | ---------------------------------------- | ---------- |
+| `PI_TS_LSP`       | `on` / `off` — enable the extension      | `on`       |
+| `PI_TS_LSP_MODE`  | `advisory` / `autofix`                   | `advisory` |
+| `PI_TS_LSP_MAX`   | max diagnostics surfaced (positive int)  | `20`       |
+| `PI_TS_LSP_AUTOFIX` | `on` / `off` — opt into autofix turns  | `off`      |
+| `PI_TS_LSP_TSC`   | absolute path to a `tsc.js` to run       | (auto)     |
+
+## Install
+
+```sh
+pi install ./extensions/pi-typescript-lsp
+# or, to try without installing:
+pi --no-extensions -e ./extensions/pi-typescript-lsp
+```

package/diagnostics.ts

@@ -0,0 +1,262 @@
+/**
+ * pi-typescript-lsp helpers: pure, UI-free logic for turning a `tsc --noEmit`
+ * run into a bounded, touched-file diagnostics report.
+ *
+ * Everything here is deliberately free of pi's ExtensionContext / UI so it can be
+ * unit-tested in isolation against the same bundle the extension ships. The only
+ * side effects are filesystem reads (tsconfig / tsc discovery, realpath
+ * canonicalization) — never a spawn. Spawning `tsc` (with an ARGV array, never a
+ * shell string) lives in index.ts, mirroring how pi-worktree keeps `runGit`
+ * beside its pure helpers.
+ *
+ * Contract note: this is NOT a full Language Server. There is no hover, no
+ * go-to-definition, no completions. The single contract is *diagnostics
+ * feedback*: parse `tsc` output, keep only the files the turn actually touched,
+ * and surface a top-N summary.
+ *
+ * Depth-one sibling module imported by index.ts via "./diagnostics.js".
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import * as path from "node:path";
+
+/** Default wall-clock budget for a single `tsc` invocation. */
+export const DEFAULT_TSC_TIMEOUT_MS = 60_000;
+
+/** Default cap on how many diagnostics are surfaced in one report. */
+export const DEFAULT_MAX_ERRORS = 20;
+
+/** A single parsed `tsc` diagnostic. */
+export interface Diagnostic {
+	/** File path exactly as tsc emitted it (may be relative to tsc's cwd). */
+	file: string;
+	line: number;
+	col: number;
+	/** TypeScript error code, e.g. "TS2322". */
+	code: string;
+	severity: "error" | "warning";
+	message: string;
+}
+
+/** Result of a single `tsc` spawn (returned by index.ts's runner). */
+export interface TscRunResult {
+	/** true when tsc exited 0 and was neither aborted nor timed out. */
+	ok: boolean;
+	exitCode: number | null;
+	stdout: string;
+	stderr: string;
+	signal: NodeJS.Signals | null;
+	timedOut: boolean;
+	/** set when we never managed to spawn tsc at all. */
+	spawnError?: string;
+}
+
+/** How `tsc` should be invoked (command + leading args before the tsc flags). */
+export interface TscCommand {
+	/** Executable to spawn (node for env/local tsc.js, "npx" for the fallback). */
+	command: string;
+	/** Leading args (the tsc.js path for node, or ["tsc"] for npx). */
+	args: string[];
+	/** Which resolution branch produced this command (for diagnostics/tests). */
+	kind: "env" | "local" | "npx";
+}
+
+/**
+ * A TypeScript source file we care about: .ts/.tsx/.mts/.cts but NOT a .d.ts
+ * declaration file (editing a .d.ts is rare and re-checking it adds noise).
+ */
+export function isTsFile(filePath: string): boolean {
+	if (!filePath) return false;
+	const lower = filePath.toLowerCase();
+	if (lower.endsWith(".d.ts")) return false;
+	return /\.(ts|tsx|mts|cts)$/.test(lower);
+}
+
+/**
+ * Parse `tsc --pretty false` output into structured diagnostics.
+ *
+ * Each diagnostic is a line of the form:
+ *   `path/to/file.ts(line,col): error TSxxxx: message`
+ * Handles CRLF, and folds INDENTED continuation lines (tsc wraps long messages)
+ * into the preceding diagnostic's message. Non-matching, non-indented lines (e.g.
+ * a trailing "Found N errors." summary) are ignored.
+ */
+export function parseTscDiagnostics(stdout: string): Diagnostic[] {
+	const diags: Diagnostic[] = [];
+	if (!stdout) return diags;
+	const re = /^(.+?)\((\d+),(\d+)\):\s+(error|warning)\s+(TS\d+):\s+(.*)$/;
+	let current: Diagnostic | null = null;
+	for (const rawLine of stdout.split("\n")) {
+		const line = rawLine.replace(/\r$/, "");
+		const match = re.exec(line);
+		if (match) {
+			if (current) diags.push(current);
+			current = {
+				file: match[1],
+				line: Number(match[2]),
+				col: Number(match[3]),
+				severity: match[4] as "error" | "warning",
+				code: match[5],
+				message: match[6],
+			};
+			continue;
+		}
+		// Indented, non-empty line that is not a new diagnostic → message continuation.
+		if (current && /^\s+\S/.test(line)) {
+			current.message += `\n${line.trim()}`;
+		}
+	}
+	if (current) diags.push(current);
+	return diags;
+}
+
+/** True when `dir` is `root` or a descendant of `root`. */
+function isWithinOrEqual(root: string, dir: string): boolean {
+	if (dir === root) return true;
+	const rel = path.relative(root, dir);
+	return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+/**
+ * Find the nearest tsconfig.json by walking UP from `file`'s directory, stopping
+ * at `cwd` (inclusive). Falls back to `<cwd>/tsconfig.json` (whether or not it
+ * exists) so callers always get a stable path to gate on with existsSync.
+ */
+export function findNearestTsconfig(file: string, cwd: string): string {
+	const root = path.resolve(cwd);
+	const fallback = path.join(root, "tsconfig.json");
+	let dir = path.dirname(path.resolve(file));
+	if (!isWithinOrEqual(root, dir)) return fallback;
+	for (;;) {
+		const candidate = path.join(dir, "tsconfig.json");
+		if (existsSync(candidate)) return candidate;
+		if (dir === root) break;
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return fallback;
+}
+
+/** Build the tsc flag array for a project check. Pure; touches nothing. */
+export function buildTscArgs(tsconfigPath: string): string[] {
+	return ["--noEmit", "--pretty", "false", "-p", tsconfigPath];
+}
+
+/**
+ * Resolve HOW to run tsc, in order:
+ *   1. env PI_TS_LSP_TSC — absolute path to tsc.js, run with the current node.
+ *   2. nearest node_modules/typescript/bin/tsc walking up from `tsconfigDir`.
+ *   3. fallback: `npx tsc`.
+ * Pure aside from existsSync probes; `env` is injectable for tests.
+ */
+export function resolveTscCommand(tsconfigDir: string, env: NodeJS.ProcessEnv = process.env): TscCommand {
+	const envTsc = env.PI_TS_LSP_TSC?.trim();
+	if (envTsc) return { command: process.execPath, args: [envTsc], kind: "env" };
+
+	let dir = path.resolve(tsconfigDir);
+	for (;;) {
+		const candidate = path.join(dir, "node_modules", "typescript", "bin", "tsc");
+		if (existsSync(candidate)) return { command: process.execPath, args: [candidate], kind: "local" };
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return { command: "npx", args: ["tsc"], kind: "npx" };
+}
+
+/**
+ * Canonicalize a path for comparison: resolve to absolute, then follow symlinks
+ * via realpath when the path exists (so macOS /var ↔ /private/var and other
+ * symlinked temp dirs compare equal). Falls back to the resolved path otherwise.
+ */
+function canonicalize(filePath: string): string {
+	const abs = path.resolve(filePath);
+	try {
+		return realpathSync.native(abs);
+	} catch {
+		return abs;
+	}
+}
+
+/**
+ * Stable 5-field dedupe key for a single diagnostic, given its already-canonical
+ * file path. Used by both the touched-file filter and the feedback dedupe so the
+ * key string stays identical in both places.
+ */
+function diagKey(canonicalFile: string, d: Diagnostic): string {
+	return `${canonicalFile}:${d.line}:${d.col}:${d.code}:${d.message}`;
+}
+
+/**
+ * Keep only diagnostics whose file is one of `touchedAbsPaths`, normalizing both
+ * sides (realpath-aware) so symlinked temp dirs match, and de-duplicating
+ * identical diagnostics. Returned diagnostics carry the canonical absolute path.
+ */
+export function filterToTouched(diags: Diagnostic[], touchedAbsPaths: string[]): Diagnostic[] {
+	const touched = new Set(touchedAbsPaths.map(canonicalize));
+	const seen = new Set<string>();
+	const out: Diagnostic[] = [];
+	for (const diag of diags) {
+		const file = canonicalize(diag.file);
+		if (!touched.has(file)) continue;
+		const key = diagKey(file, diag);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push({ ...diag, file });
+	}
+	return out;
+}
+
+/** Result of formatting diagnostics for display. */
+export interface FormatResult {
+	hasErrors: boolean;
+	text: string;
+}
+
+/**
+ * Format diagnostics as a top-N list. Each line is
+ *   `file(line,col): severity TSxxxx: message` (first line of the message only).
+ * When there are more than `maxErrors`, a trailing `(+N más)` is appended.
+ * `hasErrors` is true when any diagnostic has error severity.
+ */
+export function formatDiagnostics(diags: Diagnostic[], opts: { maxErrors?: number } = {}): FormatResult {
+	const maxErrors = opts.maxErrors ?? DEFAULT_MAX_ERRORS;
+	if (diags.length === 0) return { hasErrors: false, text: "" };
+	const shown = diags.slice(0, Math.max(0, maxErrors));
+	const lines = shown.map((d) => {
+		const firstLine = d.message.split("\n")[0];
+		return `${d.file}(${d.line},${d.col}): ${d.severity} ${d.code}: ${firstLine}`;
+	});
+	const extra = diags.length - shown.length;
+	let text = lines.join("\n");
+	if (extra > 0) text += `\n(+${extra} más)`;
+	return { hasErrors: diags.some((d) => d.severity === "error"), text };
+}
+
+/** Inputs to the run gate. `touched` is the COUNT of touched TS files. */
+export interface ShouldRunState {
+	touched: number;
+	aborted: boolean;
+	idle: boolean;
+	pending: boolean;
+}
+
+/**
+ * The coherent-edge gate: run only when the turn touched TS files, was not
+ * aborted, the agent is idle, and nothing else is queued. Pure boolean logic.
+ */
+export function shouldRun(state: ShouldRunState): boolean {
+	return state.touched > 0 && !state.aborted && state.idle && !state.pending;
+}
+
+/**
+ * Stable, order-independent key for a set of diagnostics, used to DEDUPE feedback
+ * so identical reports are not re-injected turn after turn.
+ */
+export function diagnosticsKey(diags: Diagnostic[]): string {
+	return diags
+		.map((d) => diagKey(canonicalize(d.file), d))
+		.sort()
+		.join("|");
+}

package/index.ts

@@ -0,0 +1,527 @@
+/**
+ * pi-typescript-lsp: TypeScript diagnostics feedback that fires on the COHERENT
+ * EDGE (agent_end), scoped to the files the turn actually touched.
+ *
+ * This is NOT a full Language Server — there is no hover, no go-to-definition,
+ * no completions. The single contract is *diagnostics feedback*: after the agent
+ * finishes a turn that wrote/edited TypeScript, we run `tsc --noEmit` on the
+ * relevant project(s), keep only the touched files' errors, and surface a bounded
+ * top-N report. It is non-blocking by design (never `block`s a tool call).
+ *
+ * Surfaces (the project convention — see pi-worktree / pi-auto-compact):
+ *   - automatic feedback on `agent_end` (advisory by default; opt-in autofix)
+ *   - `typescript_diagnostics`  model-callable tool (pull, on-demand)
+ *   - `/tsc`                    human slash command (status/on/off/run/scope/…)
+ *
+ * `tsc` is always spawned with an ARGV array (never a shell string), exactly as
+ * pi-worktree spawns `git`, so paths can never inject shell commands. If neither
+ * a tsconfig nor a usable tsc can be found, the extension is a NO-OP with a
+ * single advisory warning — it never breaks the session.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+	buildTscArgs,
+	DEFAULT_MAX_ERRORS,
+	DEFAULT_TSC_TIMEOUT_MS,
+	type Diagnostic,
+	diagnosticsKey,
+	filterToTouched,
+	findNearestTsconfig,
+	formatDiagnostics,
+	isTsFile,
+	parseTscDiagnostics,
+	resolveTscCommand,
+	shouldRun,
+	type TscRunResult,
+} from "./diagnostics.js";
+import { advisoryMessage, autofixMessage } from "./messages.js";
+import { type FeedbackMode, parseMax, parseMode, parseOnOff, parseScope, type Scope } from "./settings.js";
+
+// Re-exported for the integration suite to unit-test the pure helpers directly
+// against the same bundle (an `export … from` re-export creates no local binding,
+// so there is no clash with the import above).
+export {
+	buildTscArgs,
+	diagnosticsKey,
+	filterToTouched,
+	findNearestTsconfig,
+	formatDiagnostics,
+	isTsFile,
+	parseTscDiagnostics,
+	resolveTscCommand,
+	shouldRun,
+} from "./diagnostics.js";
+
+// Setting parsers live in settings.ts (mirrors the diagnostics.ts split); re-exported
+// here so the extension's public surface stays identical.
+export { parseMax, parseMode, parseOnOff, parseScope } from "./settings.js";
+
+/** Custom message type owned by this extension (for dedupe/rendering). */
+const CUSTOM_TYPE = "pi-typescript-lsp";
+const MAX_TSC_OUTPUT_BYTES = 2_000_000;
+/** Default autofix budget per prompt: at most one auto-triggered fix turn. */
+const DEFAULT_AUTOFIX_BUDGET = 1;
+
+// --------------------------------------------------------------------------
+// tsc runner — argv array, never a shell (mirrors pi-worktree's runGit)
+// --------------------------------------------------------------------------
+
+interface RunTscOptions {
+	cwd: string;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+}
+
+/**
+ * Run `command args…` (a resolved tsc invocation) in `cwd` and resolve with a
+ * typed result. NEVER rejects: spawn failure, non-zero exit, timeout, or abort
+ * all come back as a TscRunResult. Output is byte-bounded so a runaway tsc cannot
+ * flood memory.
+ */
+function runTsc(command: string, args: string[], options: RunTscOptions): Promise<TscRunResult> {
+	const { cwd, signal, timeoutMs = DEFAULT_TSC_TIMEOUT_MS } = options;
+	return new Promise<TscRunResult>((resolve) => {
+		let stdout = "";
+		let stderr = "";
+		let stdoutBytes = 0;
+		let stderrBytes = 0;
+		let settled = false;
+		let timedOut = false;
+
+		const child = spawn(command, args, { cwd, windowsHide: true });
+
+		const finish = (result: TscRunResult): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			if (signal) signal.removeEventListener("abort", onAbort);
+			resolve(result);
+		};
+
+		const onAbort = (): void => {
+			try {
+				child.kill("SIGTERM");
+			} catch {
+				/* already gone */
+			}
+			finish({ ok: false, exitCode: null, stdout, stderr, signal: "SIGTERM", timedOut: false });
+		};
+
+		const timer = setTimeout(() => {
+			timedOut = true;
+			try {
+				child.kill("SIGTERM");
+			} catch {
+				/* already gone */
+			}
+		}, timeoutMs);
+		if (typeof timer.unref === "function") timer.unref();
+
+		if (signal) {
+			if (signal.aborted) {
+				onAbort();
+				return;
+			}
+			signal.addEventListener("abort", onAbort, { once: true });
+		}
+
+		child.stdout?.on("data", (chunk: Buffer) => {
+			if (stdoutBytes >= MAX_TSC_OUTPUT_BYTES) return;
+			stdoutBytes += chunk.length;
+			stdout += chunk.toString("utf8");
+			if (stdoutBytes > MAX_TSC_OUTPUT_BYTES) stdout = stdout.slice(0, MAX_TSC_OUTPUT_BYTES);
+		});
+		child.stderr?.on("data", (chunk: Buffer) => {
+			if (stderrBytes >= MAX_TSC_OUTPUT_BYTES) return;
+			stderrBytes += chunk.length;
+			stderr += chunk.toString("utf8");
+			if (stderrBytes > MAX_TSC_OUTPUT_BYTES) stderr = stderr.slice(0, MAX_TSC_OUTPUT_BYTES);
+		});
+
+		child.on("error", (err) => {
+			finish({
+				ok: false,
+				exitCode: null,
+				stdout,
+				stderr,
+				signal: null,
+				timedOut,
+				spawnError: err.message,
+			});
+		});
+		child.on("close", (code, sig) => {
+			finish({
+				ok: code === 0 && !timedOut,
+				exitCode: code,
+				stdout,
+				stderr,
+				signal: sig,
+				timedOut,
+			});
+		});
+	});
+}
+
+/**
+ * Run tsc for a single tsconfig and return the parsed diagnostics with their file
+ * paths resolved to absolute (tsc emits paths relative to its cwd). Returns
+ * `null` only when tsc could not be spawned at all, so callers can warn once.
+ */
+async function checkProject(
+	tsconfigPath: string,
+	signal: AbortSignal | undefined,
+	timeoutMs: number,
+): Promise<Diagnostic[] | null> {
+	const dir = path.dirname(tsconfigPath);
+	const cmd = resolveTscCommand(dir, process.env);
+	const args = [...cmd.args, ...buildTscArgs(tsconfigPath)];
+	const result = await runTsc(cmd.command, args, { cwd: dir, signal, timeoutMs });
+	if (result.spawnError) return null;
+	const parsed = parseTscDiagnostics(`${result.stdout}\n${result.stderr}`);
+	return parsed.map((d) => ({
+		...d,
+		file: path.isAbsolute(d.file) ? d.file : path.resolve(dir, d.file),
+	}));
+}
+
+// --------------------------------------------------------------------------
+// Extension
+// --------------------------------------------------------------------------
+
+export default function typescriptLspExtension(pi: ExtensionAPI): void {
+	let enabled = parseOnOff(process.env.PI_TS_LSP) ?? true;
+	let mode: FeedbackMode = parseMode(process.env.PI_TS_LSP_MODE) ?? "advisory";
+	let maxErrors = parseMax(process.env.PI_TS_LSP_MAX) ?? DEFAULT_MAX_ERRORS;
+	let autofix = parseOnOff(process.env.PI_TS_LSP_AUTOFIX) ?? false;
+	let scope: Scope = "touched";
+
+	// Per-prompt set of touched TS files (absolute). Tracked in tool_result,
+	// consumed and cleared in agent_end.
+	const touched = new Set<string>();
+	// Only one tsc check in flight at a time.
+	let running = false;
+	// Dedupe: last diagnostics key we surfaced (cleared when the project is clean).
+	let lastKey: string | undefined;
+	// Per-prompt autofix budget.
+	let autofixBudget = DEFAULT_AUTOFIX_BUDGET;
+	// One-time NO-OP warning (no tsconfig/tsc) per session.
+	let warnedNoEngine = false;
+
+	const notify = (ctx: ExtensionContext, message: string, level: "info" | "warning" | "error" = "info"): void => {
+		if (ctx.mode === "print") {
+			(level === "info" ? console.log : console.error)(message);
+			return;
+		}
+		if (ctx.hasUI) {
+			ctx.ui.notify(message, level);
+			return;
+		}
+		if (level !== "info") console.error(message);
+	};
+
+	const warnNoEngine = (ctx: ExtensionContext): void => {
+		if (warnedNoEngine) return;
+		warnedNoEngine = true;
+		notify(
+			ctx,
+			"pi-typescript-lsp: no tsconfig.json or tsc found — TypeScript diagnostics disabled for this session.",
+			"warning",
+		);
+	};
+
+	/**
+	 * Group `files` by nearest tsconfig, run tsc per group, and return diagnostics
+	 * filtered to those files. `null` means there was no engine to run (no tsconfig
+	 * found, or tsc could not be spawned) — distinct from "clean" (empty array).
+	 */
+	const runTouchedCheck = async (ctx: ExtensionContext, files: string[]): Promise<Diagnostic[] | null> => {
+		const groups = new Map<string, string[]>();
+		for (const file of files) {
+			const tsconfig = findNearestTsconfig(file, ctx.cwd);
+			if (!existsSync(tsconfig)) continue;
+			const list = groups.get(tsconfig) ?? [];
+			list.push(file);
+			groups.set(tsconfig, list);
+		}
+		if (groups.size === 0) return null;
+
+		const all: Diagnostic[] = [];
+		let spawned = false;
+		for (const [tsconfig, groupFiles] of groups) {
+			const diags = await checkProject(tsconfig, ctx.signal, DEFAULT_TSC_TIMEOUT_MS);
+			if (diags === null) continue;
+			spawned = true;
+			all.push(...filterToTouched(diags, groupFiles));
+		}
+		return spawned ? all : null;
+	};
+
+	/** Run a whole-project check against `<cwd>/tsconfig.json` (no touched filter). */
+	const runProjectCheck = async (ctx: ExtensionContext): Promise<Diagnostic[] | null> => {
+		const tsconfig = path.join(ctx.cwd, "tsconfig.json");
+		if (!existsSync(tsconfig)) return null;
+		return checkProject(tsconfig, ctx.signal, DEFAULT_TSC_TIMEOUT_MS);
+	};
+
+	// --- tracker: record touched TS files. NEVER check here. ----------------
+	pi.on("tool_result", (event, ctx) => {
+		if (event.isError) return;
+		const name = event.toolName;
+		if (name !== "write" && name !== "edit" && name !== "multi_edit") return;
+		const raw = (event.input as { path?: unknown }).path;
+		if (typeof raw !== "string" || !isTsFile(raw)) return;
+		touched.add(path.isAbsolute(raw) ? raw : path.resolve(ctx.cwd, raw));
+	});
+
+	// --- reset the per-prompt autofix budget at the start of each prompt. ----
+	pi.on("agent_start", () => {
+		autofixBudget = DEFAULT_AUTOFIX_BUDGET;
+	});
+
+	// --- coherent edge: run the check after the turn fully finishes. ---------
+	pi.on("agent_end", async (_event, ctx) => {
+		if (!enabled) {
+			touched.clear();
+			return;
+		}
+		if (touched.size === 0) return;
+		if (ctx.signal?.aborted) {
+			touched.clear();
+			return;
+		}
+		// Gate on the pure predicate so it stays unit-testable.
+		if (
+			!shouldRun({
+				touched: touched.size,
+				aborted: ctx.signal?.aborted ?? false,
+				idle: ctx.isIdle(),
+				pending: ctx.hasPendingMessages(),
+			})
+		) {
+			// Not idle or messages queued: keep `touched` and retry on a later edge.
+			return;
+		}
+		if (running) return;
+		running = true;
+		try {
+			const files = [...touched];
+			const diags = await runTouchedCheck(ctx, files);
+			if (diags === null) {
+				warnNoEngine(ctx);
+				return;
+			}
+			const formatted = formatDiagnostics(diags, { maxErrors });
+			if (!formatted.hasErrors) {
+				lastKey = undefined;
+				return;
+			}
+			const key = diagnosticsKey(diags);
+			if (key === lastKey) return; // identical report already surfaced
+
+			if (mode === "autofix" && autofix) {
+				// Don't poison dedupe state when the budget blocks delivery: only
+				// remember a key for reports we actually send.
+				if (autofixBudget <= 0) return;
+				autofixBudget -= 1;
+				lastKey = key;
+				pi.sendMessage(
+					{
+						customType: CUSTOM_TYPE,
+						content: autofixMessage(formatted),
+						display: true,
+						details: { kind: "autofix", count: diags.length, diagnostics: diags },
+					},
+					{ deliverAs: "followUp", triggerTurn: true },
+				);
+				return;
+			}
+
+			lastKey = key;
+			pi.sendMessage(
+				{
+					customType: CUSTOM_TYPE,
+					content: advisoryMessage(formatted),
+					display: true,
+					details: { kind: "advisory", count: diags.length, diagnostics: diags },
+				},
+				{ deliverAs: "nextTurn" },
+			);
+		} finally {
+			running = false;
+			touched.clear();
+		}
+	});
+
+	// --- tool: typescript_diagnostics (pull / on-demand) --------------------
+	pi.registerTool({
+		name: "typescript_diagnostics",
+		label: "TypeScript Diagnostics",
+		description:
+			"Run TypeScript diagnostics (tsc --noEmit) on demand and return the errors. scope='touched' (default) checks only files written/edited so far this turn; scope='project' type-checks the whole project (<cwd>/tsconfig.json). This is diagnostics feedback only — not a full language server (no hover/go-to-definition). tsc is invoked with an argv array, never a shell.",
+		promptSnippet: "Type-check touched files or the project with typescript_diagnostics.",
+		promptGuidelines: [
+			"Use typescript_diagnostics to verify your TypeScript edits compile (tsc --noEmit) instead of hand-writing `tsc` or `npx tsc` bash commands.",
+			"Prefer scope='touched' to check just the files you changed; use scope='project' for a full type-check before declaring done.",
+			"typescript_diagnostics reports diagnostics only — it cannot do hover, go-to-definition, or completions.",
+		],
+		parameters: Type.Object({
+			scope: Type.Optional(
+				StringEnum(["touched", "project"] as const, {
+					description:
+						"'touched' (default): only files edited so far this turn. 'project': the whole <cwd>/tsconfig.json.",
+				}),
+			),
+		}),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const requested = parseScope(params.scope) ?? scope;
+			const effectiveCtx: ExtensionContext = { ...ctx, signal: signal ?? ctx.signal };
+
+			let diags: Diagnostic[] | null;
+			if (requested === "project") {
+				diags = await runProjectCheck(effectiveCtx);
+			} else {
+				if (touched.size === 0) {
+					return {
+						content: [{ type: "text" as const, text: "No TypeScript files have been touched this turn." }],
+						details: { scope: "touched", count: 0, diagnostics: [] },
+					};
+				}
+				diags = await runTouchedCheck(effectiveCtx, [...touched]);
+			}
+
+			if (diags === null) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "No tsconfig.json or tsc found — cannot run TypeScript diagnostics.",
+						},
+					],
+					details: { isError: true, scope: requested },
+				};
+			}
+
+			const formatted = formatDiagnostics(diags, { maxErrors });
+			const text = formatted.hasErrors
+				? `TypeScript diagnostics (${diags.length}):\n${formatted.text}`
+				: "No TypeScript diagnostics — clean.";
+			return {
+				content: [{ type: "text" as const, text }],
+				details: {
+					scope: requested,
+					hasErrors: formatted.hasErrors,
+					count: diags.length,
+					diagnostics: diags,
+				},
+			};
+		},
+	});
+
+	// --- command: /tsc -------------------------------------------------------
+	const SUBCOMMANDS = ["status", "on", "off", "run", "scope", "autofix", "max"] as const;
+
+	pi.registerCommand("tsc", {
+		description:
+			"TypeScript diagnostics: status | on | off | run | scope <touched|project> | autofix <on|off> | max <n>",
+		getArgumentCompletions: (prefix: string) => {
+			const tokens = prefix.split(/\s+/);
+			if (tokens.length > 1) return null;
+			const needle = (tokens[0] ?? "").toLowerCase();
+			const items = SUBCOMMANDS.filter((sub) => sub.startsWith(needle));
+			return items.length > 0 ? items.map((sub) => ({ value: sub, label: sub })) : null;
+		},
+		handler: async (args, ctx) => {
+			const tokens = args.trim().split(/\s+/).filter(Boolean);
+			const head = (tokens[0] ?? "status").toLowerCase();
+
+			if (head === "status") {
+				notify(
+					ctx,
+					`TypeScript diagnostics: ${enabled ? "on" : "off"}; mode: ${mode}; scope: ${scope}; autofix: ${autofix ? "on" : "off"}; max: ${maxErrors}`,
+					"info",
+				);
+				return;
+			}
+
+			if (head === "on") {
+				enabled = true;
+				lastKey = undefined;
+				notify(ctx, "TypeScript diagnostics enabled.", "info");
+				return;
+			}
+
+			if (head === "off") {
+				enabled = false;
+				touched.clear();
+				notify(ctx, "TypeScript diagnostics disabled.", "warning");
+				return;
+			}
+
+			if (head === "scope") {
+				const next = parseScope(tokens[1]);
+				if (!next) {
+					notify(ctx, "Usage: /tsc scope <touched|project>", "warning");
+					return;
+				}
+				scope = next;
+				notify(ctx, `TypeScript diagnostics scope: ${scope}`, "info");
+				return;
+			}
+
+			if (head === "autofix") {
+				const next = parseOnOff(tokens[1]);
+				if (next === undefined) {
+					notify(ctx, "Usage: /tsc autofix <on|off>", "warning");
+					return;
+				}
+				autofix = next;
+				mode = autofix ? "autofix" : "advisory";
+				notify(ctx, `TypeScript diagnostics autofix: ${autofix ? "on" : "off"}`, "info");
+				return;
+			}
+
+			if (head === "max") {
+				const next = parseMax(tokens[1]);
+				if (next === undefined) {
+					notify(ctx, "Usage: /tsc max <positive integer>", "warning");
+					return;
+				}
+				maxErrors = next;
+				notify(ctx, `TypeScript diagnostics max errors: ${maxErrors}`, "info");
+				return;
+			}
+
+			if (head === "run") {
+				const diags = scope === "project" ? await runProjectCheck(ctx) : await runTouchedCheck(ctx, [...touched]);
+				if (diags === null) {
+					notify(
+						ctx,
+						scope === "touched" && touched.size === 0
+							? "No TypeScript files touched this turn."
+							: "No tsconfig.json or tsc found — cannot run TypeScript diagnostics.",
+						"warning",
+					);
+					return;
+				}
+				const formatted = formatDiagnostics(diags, { maxErrors });
+				notify(
+					ctx,
+					formatted.hasErrors
+						? `TypeScript diagnostics (${diags.length}):\n${formatted.text}`
+						: "No TypeScript diagnostics — clean.",
+					formatted.hasErrors ? "warning" : "info",
+				);
+				return;
+			}
+
+			notify(ctx, "Usage: /tsc [status|on|off|run|scope <touched|project>|autofix <on|off>|max <n>]", "warning");
+		},
+	});
+}

package/messages.ts

@@ -0,0 +1,23 @@
+import type { FormatResult } from "./diagnostics.js";
+
+/** Build the advisory feedback body (non-blocking, surfaced next turn). */
+export function advisoryMessage(formatted: FormatResult): string {
+	return [
+		"TypeScript diagnostics on the files you just changed:",
+		"",
+		formatted.text,
+		"",
+		"Fix these when you continue; run typescript_diagnostics to re-check.",
+	].join("\n");
+}
+
+/** Build the autofix follow-up body (triggers a turn so the agent fixes them). */
+export function autofixMessage(formatted: FormatResult): string {
+	return [
+		"TypeScript diagnostics were found on the files you just changed:",
+		"",
+		formatted.text,
+		"",
+		"Fix these type errors now, then re-run typescript_diagnostics to confirm a clean result.",
+	].join("\n");
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+	"name": "@pandi-coding-agent/typescript-lsp",
+	"version": "0.1.0",
+	"description": "Pi extension for TypeScript diagnostics feedback: runs tsc --noEmit on the coherent edge (agent_end) over touched files, plus a typescript_diagnostics tool and a /tsc command. Not a full LSP (no hover/go-to-def).",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/andrestobelem/pi-dynamic-workflows.git",
+		"directory": "extensions/pi-typescript-lsp"
+	},
+	"type": "module",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-extension",
+		"typescript",
+		"diagnostics",
+		"tsc"
+	],
+	"files": [
+		"*.ts",
+		"README.md"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"typebox": "*"
+	}
+}

package/settings.ts

@@ -0,0 +1,47 @@
+/**
+ * pi-typescript-lsp settings: the small, pure setting parsers (env + subcommand
+ * share these — mirrors pi-auto-compact) plus the feedback-mode/scope
+ * value types they produce.
+ *
+ * Like diagnostics.ts, this module is deliberately free of pi's ExtensionContext
+ * / UI so it can be unit-tested in isolation against the same bundle the
+ * extension ships. No side effects.
+ *
+ * Depth-one sibling module imported by index.ts via "./settings.js".
+ */
+
+export type FeedbackMode = "advisory" | "autofix";
+export type Scope = "touched" | "project";
+
+/** Parse an on/off-style setting. Returns undefined for unrecognised input. */
+export function parseOnOff(value: string | undefined): boolean | undefined {
+	if (value === undefined) return undefined;
+	const v = value.trim().toLowerCase();
+	if (v === "on" || v === "1" || v === "true" || v === "yes") return true;
+	if (v === "off" || v === "0" || v === "false" || v === "no") return false;
+	return undefined;
+}
+
+/** Parse the feedback mode setting (advisory | autofix). */
+export function parseMode(value: string | undefined): FeedbackMode | undefined {
+	if (value === undefined) return undefined;
+	const v = value.trim().toLowerCase();
+	if (v === "advisory" || v === "autofix") return v;
+	return undefined;
+}
+
+/** Parse a positive integer max-errors setting. */
+export function parseMax(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	const n = Number(value.trim());
+	if (!Number.isInteger(n) || n <= 0) return undefined;
+	return n;
+}
+
+/** Parse a scope setting (touched | project). */
+export function parseScope(value: string | undefined): Scope | undefined {
+	if (value === undefined) return undefined;
+	const v = value.trim().toLowerCase();
+	if (v === "touched" || v === "project") return v;
+	return undefined;
+}