@shanepadgett/tau-agent 0.29.0 → 0.31.0

package/extensions/explore/ast/read/hook.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ReadToolDetails } from "@earendil-works/pi-coding-agent";
 import { loadTauExtensionSettings } from "../../../../shared/settings/load.ts";
 import exploreSettings from "../../settings.ts";
 import { resolveExplorePath } from "../../traverse.ts";
@@ -9,6 +9,7 @@ import { formatLargeReadOutline, readCallKind, shouldOutlineFullRead, type Explo
 
 type ReadOverlayResult = {
 	content: Array<{ type: "text"; text: string }>;
+	details: ReadToolDetails;
 	isError: boolean;
 };
 
@@ -80,6 +81,7 @@ async function substituteLargeFullRead(options: {
 			result.file.rows.length === 0 ? "No declarations" : formatOutlineFile(result.file, options.engine.cwd, false);
 		return {
 			content: [{ type: "text", text: formatLargeReadOutline(outlineText) }],
+			details: {},
 			isError: false,
 		};
 	} catch {

package/extensions/ideas/browser.ts

@@ -6,17 +6,15 @@ import {
 	type TextRecordSelectPanelConfig,
 	type TextRecordSelectResult,
 } from "@shanepadgett/tau-tui";
+import { errorText } from "../../shared/text.ts";
 import { deleteIdea, type Idea, ideasFilePath, loadIdeas, updateIdea } from "./store.ts";
 
-const CONFIG: Omit<TextRecordSelectPanelConfig, "path"> = {
+const CONFIG: Omit<TextRecordSelectPanelConfig<Idea>, "path" | "destructiveAction"> = {
 	title: "Ideas",
 	emptyMessage: "No ideas yet. Use /ideas <text> to log one.",
 	primaryLabel: "insert",
 	expandActiveItem: true,
-	actions: [
-		{ id: "edit", key: Key.ctrl("e"), hint: rawHint("ctrl+e", "edit") },
-		{ id: "delete", key: Key.ctrl("d"), hint: rawHint("ctrl+d", "delete") },
-	],
+	actions: [{ id: "edit", key: Key.ctrl("e"), hint: rawHint("ctrl+e", "edit") }],
 };
 
 export async function browseIdeas(ctx: ExtensionCommandContext): Promise<Idea | undefined> {
@@ -34,15 +32,6 @@ export async function browseIdeas(ctx: ExtensionCommandContext): Promise<Idea |
 		if (result.kind === "cancel") return undefined;
 		if (result.kind === "primary") return result.item;
 
-		if (result.actionId === "delete") {
-			const ok = await ctx.ui.confirm("Delete idea?", result.item.text);
-			if (ok) {
-				await deleteIdea(ctx.cwd, result.item.id);
-				ctx.ui.notify("Idea deleted.", "info");
-			}
-			continue;
-		}
-
 		// edit: native multiline editor, prefilled with the current text.
 		const edited = await ctx.ui.editor("Edit idea", result.item.text);
 		if (edited == null) continue;
@@ -60,7 +49,29 @@ async function show(
 	ideas: readonly Idea[],
 	path: string,
 ): Promise<TextRecordSelectResult<Idea>> {
-	return ctx.ui.custom<TextRecordSelectResult<Idea>>((_tui, theme, _keybindings, done) =>
-		createTextRecordSelectPanel(theme, ideas, { ...CONFIG, path }, done),
+	return ctx.ui.custom<TextRecordSelectResult<Idea>>((tui, theme, _keybindings, done) =>
+		createTextRecordSelectPanel(
+			tui,
+			theme,
+			ideas,
+			{
+				...CONFIG,
+				path,
+				destructiveAction: {
+					id: "delete",
+					key: Key.ctrl("d"),
+					hint: rawHint("ctrl+d", "delete"),
+					confirmLabel: () => "Delete idea?",
+					runningLabel: "Deleting idea…",
+					onConfirm: async (item) => {
+						const next = await deleteIdea(ctx.cwd, item.id);
+						ctx.ui.notify("Idea deleted.", "info");
+						return next;
+					},
+					onError: (error) => ctx.ui.notify(`Idea delete failed: ${errorText(error)}`, "error"),
+				},
+			},
+			done,
+		),
 	);
 }

package/extensions/review/README.md

@@ -0,0 +1,11 @@
+# Review
+
+Run `/review` to inspect current repository's staged, unstaged, and untracked work in a fresh isolated session. Choose one focused pass:
+
+- `simplify` looks for code and concepts that can disappear or reuse what already exists.
+- `architecture` performs a nuclear maintainability review and accepts substantial redesign when ownership, reuse, or structure is poor.
+- `correctness` checks runtime bugs and failures after architecture is accepted.
+
+Run a mode directly with `/review simplify`, `/review architecture`, or `/review correctness`. Run `/review show` to reopen latest result on current session branch.
+
+Results stay outside parent agent context. In result view, press `a` to send review to agent's next turn or `e` to export Markdown under `.pi/tau/reviews/`.

package/extensions/review/index.ts

@@ -0,0 +1,135 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { createGitRunner, loadRepoStatus } from "../../shared/git.ts";
+import { createInjectedContext } from "../../shared/injected-context.ts";
+import { errorText } from "../../shared/text.ts";
+import {
+	formatReviewMarkdown,
+	isReviewRecord,
+	isReviewMode,
+	REVIEW_ENTRY_TYPE,
+	type ReviewMode,
+	type ReviewRecord,
+} from "./model.ts";
+import { ReviewProgressPanel, ReviewResultPanel, type ReviewResultAction } from "./panel.ts";
+import { runReview } from "./session.ts";
+
+export default function reviewExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("review", {
+		description: "Run or show an isolated simplify, architecture, or correctness review",
+		handler: async (args, ctx) => {
+			if (ctx.mode !== "tui" || !ctx.isProjectTrusted()) {
+				ctx.ui.notify("/review requires a trusted TUI project", "warning");
+				return;
+			}
+			await ctx.waitForIdle();
+			const requested = args.trim().toLowerCase();
+			if (requested === "show") {
+				const latest = latestReview(ctx.sessionManager.getBranch());
+				if (!latest) {
+					ctx.ui.notify("No review exists on this session branch", "warning");
+					return;
+				}
+				await showReview(pi, ctx, latest);
+				return;
+			}
+
+			let mode: ReviewMode | undefined;
+			if (requested) {
+				if (!isReviewMode(requested)) {
+					ctx.ui.notify("Usage: /review [simplify|architecture|correctness|show]", "warning");
+					return;
+				}
+				mode = requested;
+			} else {
+				const selected = await ctx.ui.select("Review mode", ["Simplify", "Architecture", "Correctness"]);
+				if (!selected) return;
+				const normalized = selected.toLowerCase();
+				if (!isReviewMode(normalized)) return;
+				mode = normalized;
+			}
+
+			const status = await loadRepoStatus(createGitRunner(pi, ctx));
+			if (!status) {
+				ctx.ui.notify("/review requires a Git repository", "warning");
+				return;
+			}
+			if (status.fileCount === 0) {
+				ctx.ui.notify("Nothing to review: working tree is clean", "info");
+				return;
+			}
+
+			const controller = new AbortController();
+			const signal = ctx.signal ? AbortSignal.any([controller.signal, ctx.signal]) : controller.signal;
+			let failure: string | undefined;
+			const output = await ctx.ui.custom<ReviewRecord | undefined>((tui, theme, keys, done) => {
+				const panel = new ReviewProgressPanel(tui, theme, mode, keys, () => controller.abort());
+				void runReview({
+					ctx,
+					root: status.root,
+					mode,
+					parentThinkingLevel: pi.getThinkingLevel(),
+					signal,
+					onProgress: (line) => panel.update(line),
+				})
+					.then((result) => done({ ...result, mode, root: status.root, createdAt: new Date().toISOString() }))
+					.catch((error: unknown) => {
+						failure = errorText(error);
+						done(undefined);
+					});
+				return panel;
+			});
+			if (!output) {
+				ctx.ui.notify(
+					signal.aborted ? "Review cancelled" : `Review failed: ${failure ?? "unknown error"}`,
+					signal.aborted ? "info" : "error",
+				);
+				return;
+			}
+			pi.appendEntry(REVIEW_ENTRY_TYPE, output);
+			await showReview(pi, ctx, output);
+		},
+	});
+}
+
+export function latestReview(entries: readonly SessionEntry[]): ReviewRecord | undefined {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const entry = entries[index];
+		if (entry?.type !== "custom" || entry.customType !== REVIEW_ENTRY_TYPE) continue;
+		if (isReviewRecord(entry.data)) return entry.data;
+	}
+	return undefined;
+}
+
+async function showReview(pi: ExtensionAPI, ctx: ExtensionContext, review: ReviewRecord): Promise<void> {
+	const action = await ctx.ui.custom<ReviewResultAction>(
+		(tui, theme, keys, done) => new ReviewResultPanel(tui, theme, keys, review, done),
+		{
+			overlay: true,
+			overlayOptions: { anchor: "top-center", width: "80%", minWidth: 68, maxHeight: "90%", margin: 1 },
+		},
+	);
+	if (action === "send") {
+		try {
+			await pi.sendMessage(
+				createInjectedContext(formatReviewMarkdown(review), { source: "review", title: `${review.mode} review` }),
+				{ triggerTurn: false, deliverAs: "nextTurn" },
+			);
+			ctx.ui.notify("Review queued for agent's next turn", "info");
+		} catch (error) {
+			ctx.ui.notify(`Failed to send review: ${errorText(error)}`, "error");
+		}
+	} else if (action === "export") {
+		try {
+			const directory = join(review.root, ".pi", "tau", "reviews");
+			await mkdir(directory, { recursive: true });
+			const timestamp = review.createdAt.replace(/[^0-9A-Za-z-]/g, "-");
+			const path = join(directory, `${timestamp}-${review.mode}.md`);
+			await writeFile(path, formatReviewMarkdown(review), { encoding: "utf8", mode: 0o600 });
+			ctx.ui.notify(`Review exported to ${path}`, "info");
+		} catch (error) {
+			ctx.ui.notify(`Failed to export review: ${errorText(error)}`, "error");
+		}
+	}
+}

package/extensions/review/model.ts

@@ -0,0 +1,144 @@
+import type { Tool } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+
+const MAX_SUMMARY_LENGTH = 2_000;
+const MAX_FINDINGS = 12;
+const MAX_PATH_LENGTH = 400;
+const MAX_LINES_LENGTH = 80;
+const MAX_FINDING_LENGTH = 1_500;
+const REVIEW_MODE_SCHEMA = Type.Union([
+	Type.Literal("simplify"),
+	Type.Literal("architecture"),
+	Type.Literal("correctness"),
+]);
+const REVIEW_FINDING_SCHEMA = Type.Object(
+	{
+		severity: Type.Union([
+			Type.Literal("critical"),
+			Type.Literal("high"),
+			Type.Literal("medium"),
+			Type.Literal("low"),
+		]),
+		path: Type.String({
+			minLength: 1,
+			maxLength: MAX_PATH_LENGTH,
+			description: "Repository-relative file path",
+		}),
+		lines: Type.String({
+			minLength: 1,
+			maxLength: MAX_LINES_LENGTH,
+			description: "Exact line or line range, or N/A when no source line exists",
+		}),
+		finding: Type.String({
+			minLength: 1,
+			maxLength: MAX_FINDING_LENGTH,
+			description: "Failure mechanism or concrete maintenance cost",
+		}),
+		fix: Type.String({
+			minLength: 1,
+			maxLength: MAX_FINDING_LENGTH,
+			description: "Smallest credible fix direction",
+		}),
+	},
+	{ additionalProperties: false },
+);
+const REVIEW_OUTPUT_SCHEMA = Type.Object(
+	{
+		verdict: Type.Union([Type.Literal("pass"), Type.Literal("changes-required")]),
+		summary: Type.String({
+			minLength: 1,
+			maxLength: MAX_SUMMARY_LENGTH,
+			description: "Short, blunt prose verdict",
+		}),
+		findings: Type.Array(REVIEW_FINDING_SCHEMA, { maxItems: MAX_FINDINGS }),
+	},
+	{ additionalProperties: false },
+);
+const REVIEW_RECORD_SCHEMA = Type.Object(
+	{
+		...REVIEW_OUTPUT_SCHEMA.properties,
+		mode: REVIEW_MODE_SCHEMA,
+		root: Type.String({ minLength: 1 }),
+		createdAt: Type.String({ minLength: 1 }),
+	},
+	{ additionalProperties: false },
+);
+
+export type ReviewMode = Static<typeof REVIEW_MODE_SCHEMA>;
+export type ReviewOutput = Static<typeof REVIEW_OUTPUT_SCHEMA>;
+export type ReviewRecord = Static<typeof REVIEW_RECORD_SCHEMA>;
+
+export const REVIEW_ENTRY_TYPE = "tau.review.result";
+
+export const REVIEW_RESULT_TOOL = {
+	name: "review_result",
+	description: "Submit final review. This is the only allowed final response.",
+	parameters: REVIEW_OUTPUT_SCHEMA,
+} satisfies Tool;
+
+const MODE_INSTRUCTIONS: Record<ReviewMode, string> = {
+	simplify: [
+		"Delete concepts before improving them.",
+		"Find behavior that was not requested, code the repository or platform already provides, duplicate concepts, needless files, wrappers, helpers, types, options, and branches.",
+		"Judge against the smallest credible implementation. Runtime correctness is out of scope unless a problem directly proves needless complexity.",
+	].join(" "),
+	architecture: [
+		"Assume the current architecture is poor and likely needs substantial rework. Make existing structure prove it should remain.",
+		"Inspect ownership, boundaries, shared roots, reuse, sources of truth, coupling, cohesion, and clean coding patterns.",
+		"Prefer a coherent redesign over preserving a bad local structure. Runtime correctness is secondary and should appear only when it supports an architectural finding.",
+	].join(" "),
+	correctness: [
+		"Architecture is accepted for this pass.",
+		"Look only for concrete runtime bugs, broken state transitions, unsafe boundaries, data loss, error-handling failures, and affected callers.",
+		"Do not report style, simplification, or architecture preferences.",
+	].join(" "),
+};
+
+export function buildReviewPrompt(root: string, mode: ReviewMode): string {
+	return [
+		`Review uncommitted work in ${root}.`,
+		"Inspect staged, unstaged, and untracked changes. Stay centered on changed behavior, but inspect surrounding ownership and callers when needed to prove a finding.",
+		"Do not modify files. Do not report theoretical concerns or personal preferences. Use the cheapest evidence that settles each point.",
+		MODE_INSTRUCTIONS[mode],
+		`Call ${REVIEW_RESULT_TOOL.name} exactly once as the final action. Write no final prose outside that tool call.`,
+		"Order findings by severity. Every finding needs an exact repository-relative path and lines when source exists, a concrete mechanism or cost, and the smallest credible fix. Return an empty findings array and verdict pass when nothing actionable remains.",
+	].join("\n\n");
+}
+
+export function formatReviewMarkdown(review: ReviewRecord): string {
+	const findings = review.findings.length
+		? review.findings.flatMap((finding, index) => [
+				`### ${index + 1}. ${finding.severity.toUpperCase()} — ${finding.path}:${finding.lines}`,
+				"",
+				finding.finding,
+				"",
+				`**Fix:** ${finding.fix}`,
+				"",
+			])
+		: ["No actionable findings.", ""];
+	return [
+		`# ${reviewModeLabel(review.mode)} review`,
+		"",
+		`**Verdict:** ${review.verdict}`,
+		`**Created:** ${review.createdAt}`,
+		"",
+		review.summary,
+		"",
+		"## Findings",
+		"",
+		...findings,
+	].join("\n");
+}
+
+export function isReviewMode(value: string): value is ReviewMode {
+	return Value.Check(REVIEW_MODE_SCHEMA, value);
+}
+
+export function reviewModeLabel(mode: ReviewMode): string {
+	return `${mode.charAt(0).toUpperCase()}${mode.slice(1)}`;
+}
+
+export function isReviewRecord(value: unknown): value is ReviewRecord {
+	return Value.Check(REVIEW_RECORD_SCHEMA, value);
+}

package/extensions/review/panel.ts

@@ -0,0 +1,128 @@
+import { bindingHint, bindingsHint, rawHint, ToolPanel } from "@shanepadgett/tau-tui";
+import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
+import { Markdown, type Component, type KeybindingsManager, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
+import { formatReviewMarkdown, reviewModeLabel, type ReviewMode, type ReviewRecord } from "./model.ts";
+
+export class ReviewProgressPanel implements Component {
+	private readonly tui: TUI;
+	private readonly panel: ToolPanel;
+	private readonly lines: string[] = [];
+
+	constructor(tui: TUI, theme: Theme, mode: ReviewMode, keys: KeybindingsManager, cancel: () => void) {
+		this.tui = tui;
+		this.panel = new ToolPanel(theme, {
+			title: `${reviewModeLabel(mode)} review`,
+			secondary: "Fresh isolated review · hidden from parent context",
+			body: {
+				render: (width) =>
+					(this.lines.length ? this.lines.slice(-5) : ["Starting review"]).map((line) =>
+						truncateToWidth(theme.fg("muted", line), width, "…"),
+					),
+				invalidate() {},
+			},
+			footer: { kind: "hints", hints: [bindingHint("tui.select.cancel", "cancel")] },
+			border: "box",
+		});
+		this.handleInput = (data) => {
+			if (!keys.matches(data, "tui.select.cancel")) return;
+			cancel();
+			this.update("Cancelling review");
+		};
+	}
+
+	handleInput: (data: string) => void;
+
+	update(status: string): void {
+		if (this.lines.at(-1) !== status) {
+			this.lines.push(status);
+			if (this.lines.length > 5) this.lines.shift();
+		}
+		this.tui.requestRender();
+	}
+
+	render(width: number): string[] {
+		return this.panel.render(width);
+	}
+
+	invalidate(): void {
+		this.panel.invalidate();
+	}
+}
+
+export type ReviewResultAction = "send" | "export" | "close";
+
+export class ReviewResultPanel implements Component {
+	private readonly panel: ToolPanel;
+	private readonly body: ReviewMarkdownBody;
+
+	constructor(
+		tui: TUI,
+		theme: Theme,
+		keys: KeybindingsManager,
+		review: ReviewRecord,
+		done: (action: ReviewResultAction) => void,
+	) {
+		this.body = new ReviewMarkdownBody(tui, formatReviewMarkdown(review));
+		this.panel = new ToolPanel(theme, {
+			title: `${reviewModeLabel(review.mode)} review · ${review.verdict}`,
+			secondary: `${review.findings.length} finding${review.findings.length === 1 ? "" : "s"} · not in parent context`,
+			body: this.body,
+			footer: {
+				kind: "hints",
+				hints: [
+					bindingsHint(["tui.select.up", "tui.select.down"], "scroll"),
+					rawHint("a", "send to agent"),
+					rawHint("e", "export"),
+					bindingHint("tui.select.cancel", "close"),
+				],
+			},
+			border: "box",
+		});
+		this.handleInput = (data) => {
+			if (keys.matches(data, "tui.select.up")) this.body.scroll(-1);
+			else if (keys.matches(data, "tui.select.down")) this.body.scroll(1);
+			else if (data === "a") done("send");
+			else if (data === "e") done("export");
+			else if (keys.matches(data, "tui.select.cancel")) done("close");
+		};
+	}
+
+	handleInput: (data: string) => void;
+
+	render(width: number): string[] {
+		return this.panel.render(width);
+	}
+
+	invalidate(): void {
+		this.panel.invalidate();
+	}
+}
+
+class ReviewMarkdownBody implements Component {
+	private readonly tui: TUI;
+	private readonly markdown: Markdown;
+	private offset = 0;
+	private maxOffset = 0;
+
+	constructor(tui: TUI, content: string) {
+		this.tui = tui;
+		this.markdown = new Markdown(content, 0, 0, getMarkdownTheme());
+	}
+
+	scroll(delta: number): void {
+		this.offset = Math.max(0, Math.min(this.maxOffset, this.offset + delta));
+		this.tui.requestRender();
+	}
+
+	render(width: number): string[] {
+		const lines = this.markdown.render(width);
+		const height = Math.max(4, Math.floor(this.tui.terminal.rows * 0.9) - 9);
+		this.maxOffset = Math.max(0, lines.length - height);
+		this.offset = Math.min(this.offset, this.maxOffset);
+		return lines.slice(this.offset, this.offset + height);
+	}
+
+	invalidate(): void {
+		this.markdown.invalidate();
+	}
+}

package/extensions/review/session.ts

@@ -0,0 +1,106 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineTool, type AgentSessionEvent, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	createIsolatedSessionResource,
+	resolveIsolatedSessionModel,
+	type IsolatedSessionResource,
+} from "../../shared/isolated-session.ts";
+import { buildReviewPrompt, REVIEW_RESULT_TOOL, type ReviewMode, type ReviewOutput } from "./model.ts";
+
+const REVIEW_MODEL = "openai-codex/gpt-5.6-sol";
+const REVIEW_TOOLS = [
+	"read",
+	"bash",
+	"outline",
+	"show",
+	"discover",
+	"ast_search",
+	"deps",
+	"reverse_deps",
+	"callers",
+	"callees",
+	"references",
+	"implementations",
+	"impact",
+	"context",
+	REVIEW_RESULT_TOOL.name,
+];
+const EXPLORE_EXTENSION = join(dirname(fileURLToPath(import.meta.url)), "..", "explore", "index.ts");
+
+export async function runReview(options: {
+	ctx: ExtensionContext;
+	root: string;
+	mode: ReviewMode;
+	parentThinkingLevel: NonNullable<ExtensionContext["thinkingLevel"]>;
+	signal: AbortSignal;
+	onProgress: (status: string) => void;
+}): Promise<ReviewOutput> {
+	const { ctx, root, mode, signal, onProgress } = options;
+	let output: ReviewOutput | undefined;
+	const outputTool = defineTool({
+		...REVIEW_RESULT_TOOL,
+		label: "Review Result",
+		async execute(_toolCallId, params) {
+			output = params;
+			return {
+				content: [{ type: "text" as const, text: "Review recorded" }],
+				details: params,
+				terminate: true,
+			};
+		},
+	});
+	let resource: IsolatedSessionResource | undefined;
+	let unsubscribe: (() => void) | undefined;
+	try {
+		const selected = await resolveIsolatedSessionModel({
+			label: "Review",
+			preferredModel: REVIEW_MODEL,
+			preferredThinkingLevel: "high",
+			usePreferredThinkingAfterModelFallback: false,
+			ctx,
+			parentThinkingLevel: options.parentThinkingLevel,
+			signal,
+			onWarning: onProgress,
+		});
+		resource = await createIsolatedSessionResource(
+			{
+				...selected,
+				label: "Review",
+				extensionPaths: [EXPLORE_EXTENSION],
+				cwd: root,
+				tools: REVIEW_TOOLS,
+				customTools: [outputTool],
+				bindTarget: { mode: "print" },
+			},
+			signal,
+		);
+		const { session } = resource;
+		unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+			if (event.type === "tool_execution_start") {
+				onProgress(`${event.toolName} ${summarizeArgs(event.args)}`.trim());
+			} else if (event.type === "tool_execution_end") {
+				onProgress(event.isError ? `${event.toolName} failed` : `${event.toolName} complete`);
+			}
+		});
+		const abort = () => void session.abort().catch(() => undefined);
+		signal.addEventListener("abort", abort, { once: true });
+		try {
+			onProgress(`Running ${mode} review`);
+			await session.prompt(buildReviewPrompt(root, mode), { expandPromptTemplates: false });
+		} finally {
+			signal.removeEventListener("abort", abort);
+		}
+		if (signal.aborted) throw new Error("Review cancelled");
+		if (!output) throw new Error("Review ended without structured output");
+		return output;
+	} finally {
+		unsubscribe?.();
+		await resource?.dispose();
+	}
+}
+
+function summarizeArgs(args: unknown): string {
+	const text = typeof args === "string" ? args : (JSON.stringify(args) ?? String(args));
+	return text.length > 140 ? `${text.slice(0, 139)}…` : text;
+}

package/extensions/script-runner/README.md

@@ -0,0 +1,7 @@
+# Script Runner
+
+Gives the agent a first-class `script_runner` tool for running Python and TypeScript instead of falling back to bash. The agent picks whichever language is more efficient for the task.
+
+When a run fails, the tool keeps the script and returns a `scriptId`. The agent retries with targeted `{oldText, newText}` edits against what it just wrote instead of resending the whole script, saving output tokens and keeping duplicate scripts out of context. Only the source the agent already sent is referenced; no file path is exposed.
+
+Languages are detected from the environment: Python via `python3`/`python`, TypeScript via Node with `--experimental-strip-types` (Node 22.6 or newer). The tool registers only the languages actually available and is hidden from the prompt entirely when neither is present.