@shanepadgett/tau-agent 0.1.0

package/extensions/appshot/index.ts

@@ -0,0 +1,245 @@
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	defineTool,
+	withFileMutationQueue,
+	type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { encode } from "@toon-format/toon";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { type Static, Type } from "typebox";
+import { createToolRowStateStore, formatToolRowTitle } from "../../shared/tool-row-state.js";
+import { createNativeHelper, type RunHelper } from "./native-helper.ts";
+
+const MAX_PNG_BYTES = 12 * 1024 * 1024;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const listWindowsSchema = Type.Object({}, { additionalProperties: false });
+const screenshotWindowSchema = Type.Object(
+	{
+		window_id: Type.Integer({ minimum: 1, description: "Window ID returned by list_windows" }),
+		path: Type.String({ description: "Destination path for the PNG file (relative or absolute)" }),
+	},
+	{ additionalProperties: false },
+);
+const activateAppSchema = Type.Object(
+	{ pid: Type.Integer({ minimum: 1, description: "Application process ID returned by list_windows" }) },
+	{ additionalProperties: false },
+);
+
+type ScreenshotWindowParams = Static<typeof screenshotWindowSchema>;
+
+interface WindowInfo {
+	window_id: number;
+	title: string;
+	app_name: string;
+	bundle_id: string;
+	pid: number;
+	bounds: { x: number; y: number; width: number; height: number };
+}
+
+interface ScreenshotDetails {
+	path: string;
+	window_id: number;
+}
+
+interface ActivationDetails {
+	pid: number;
+}
+
+function isWindowInfo(value: unknown): value is WindowInfo {
+	if (typeof value !== "object" || value === null) return false;
+	const window = value as Record<string, unknown>;
+	if (typeof window.bounds !== "object" || window.bounds === null) return false;
+	const bounds = window.bounds as Record<string, unknown>;
+	return (
+		typeof window.window_id === "number" &&
+		Number.isInteger(window.window_id) &&
+		typeof window.title === "string" &&
+		typeof window.app_name === "string" &&
+		typeof window.bundle_id === "string" &&
+		typeof window.pid === "number" &&
+		Number.isInteger(window.pid) &&
+		typeof bounds.x === "number" &&
+		Number.isFinite(bounds.x) &&
+		typeof bounds.y === "number" &&
+		Number.isFinite(bounds.y) &&
+		typeof bounds.width === "number" &&
+		Number.isFinite(bounds.width) &&
+		typeof bounds.height === "number" &&
+		Number.isFinite(bounds.height)
+	);
+}
+
+function encodeWindowList(windows: WindowInfo[]): string {
+	const rows = windows.map((window) => ({
+		window_id: window.window_id,
+		title: window.title,
+		app_name: window.app_name,
+		bundle_id: window.bundle_id,
+		pid: window.pid,
+		x: window.bounds.x,
+		y: window.bounds.y,
+		width: window.bounds.width,
+		height: window.bounds.height,
+	}));
+	const render = (count: number, omitted: number) =>
+		encode(omitted === 0 ? { windows: rows.slice(0, count) } : { windows: rows.slice(0, count), omitted }, {
+			indent: 1,
+		});
+	const fits = (value: string) =>
+		Buffer.byteLength(value, "utf8") <= DEFAULT_MAX_BYTES && value.split("\n").length <= DEFAULT_MAX_LINES;
+	const maximumRows = Math.max(0, DEFAULT_MAX_LINES - 2);
+
+	if (rows.length <= maximumRows) {
+		const full = render(rows.length, 0);
+		if (fits(full)) return full;
+	}
+
+	let low = 0;
+	let high = Math.min(rows.length, maximumRows);
+	while (low < high) {
+		const middle = Math.ceil((low + high) / 2);
+		if (fits(render(middle, rows.length - middle))) low = middle;
+		else high = middle - 1;
+	}
+	return render(low, rows.length - low);
+}
+
+function registerAppshotTools(pi: ExtensionAPI, runHelper: RunHelper): void {
+	const rowState = createToolRowStateStore(pi, "appshot.tool-row-state");
+
+	pi.registerTool(
+		defineTool<typeof listWindowsSchema, undefined>({
+			name: "list_windows",
+			label: "List Windows",
+			description:
+				"List visible normal macOS windows as compact TOON with window IDs, titles, application identity, process IDs, and bounds. Requires macOS 14 or newer and Screen & System Audio Recording permission.",
+			promptSnippet: "Discover visible macOS application windows and their IDs",
+			promptGuidelines: [
+				"Use list_windows to discover graphical applications and select an exact window before calling screenshot_window.",
+			],
+			parameters: listWindowsSchema,
+			async execute(_toolCallId, _params, signal) {
+				if (process.platform !== "darwin") throw new Error("list_windows is only available on macOS");
+				const result = await runHelper(["list"], signal, 30_000);
+				if (result.code !== 0)
+					throw new Error(result.stderr.trim() || result.stdout.trim() || "Window listing failed");
+				let parsed: unknown;
+				try {
+					parsed = JSON.parse(result.stdout);
+				} catch {
+					throw new Error("Window listing helper returned invalid data");
+				}
+				if (!Array.isArray(parsed) || !parsed.every(isWindowInfo)) {
+					throw new Error("Window listing helper returned invalid data");
+				}
+				return { content: [{ type: "text", text: encodeWindowList(parsed) }], details: undefined };
+			},
+			renderCall(_args, theme, context) {
+				rowState.watch(context.toolCallId, context.invalidate);
+				const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+				text.setText(formatToolRowTitle(rowState, context.toolCallId, "list_windows", theme));
+				return text;
+			},
+			renderResult(result, _options, _theme, context) {
+				const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+				const content = result.content.find((item) => item.type === "text");
+				text.setText(context.expanded && content?.type === "text" ? content.text : "");
+				return text;
+			},
+		}),
+	);
+
+	pi.registerTool(
+		defineTool<typeof screenshotWindowSchema, ScreenshotDetails | undefined>({
+			name: "screenshot_window",
+			label: "Screenshot Window",
+			description:
+				"Capture one visible macOS window by its list_windows ID, resize it to fit within 1568×1568 pixels, save it as PNG, and inspect the image.",
+			promptSnippet: "Capture and inspect an exact visible macOS window by window ID",
+			promptGuidelines: ["Call list_windows before screenshot_window; pass its exact window_id and a PNG path."],
+			parameters: screenshotWindowSchema,
+			async execute(_toolCallId, params: ScreenshotWindowParams, signal, onUpdate, ctx) {
+				if (process.platform !== "darwin") throw new Error("screenshot_window is only available on macOS");
+				const rawPath = params.path.startsWith("@") ? params.path.slice(1) : params.path;
+				if (!rawPath.trim()) throw new Error("Screenshot path cannot be empty");
+				const absolutePath = isAbsolute(rawPath) ? rawPath : resolve(ctx.cwd, rawPath);
+				if (!absolutePath.toLowerCase().endsWith(".png")) throw new Error("Screenshot path must end in .png");
+
+				await onUpdate?.({
+					content: [{ type: "text", text: `Capturing window ${params.window_id}...` }],
+					details: undefined,
+				});
+				return withFileMutationQueue(absolutePath, async () => {
+					await mkdir(dirname(absolutePath), { recursive: true });
+					const temporaryPath = join(dirname(absolutePath), `.${basename(absolutePath)}.${randomUUID()}.tmp.png`);
+					try {
+						const result = await runHelper(["capture", String(params.window_id), temporaryPath], signal, 30_000);
+						if (result.code !== 0) {
+							throw new Error(result.stderr.trim() || result.stdout.trim() || "Window capture failed");
+						}
+						let imageSize: number;
+						try {
+							imageSize = (await stat(temporaryPath)).size;
+						} catch {
+							throw new Error(result.stderr.trim() || "Window capture produced no PNG file");
+						}
+						if (imageSize > MAX_PNG_BYTES) {
+							throw new Error(`Window capture exceeds the ${MAX_PNG_BYTES / 1024 / 1024} MiB attachment limit`);
+						}
+						const image = await readFile(temporaryPath);
+						if (
+							image.length < PNG_SIGNATURE.length ||
+							!image.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)
+						) {
+							throw new Error("Window capture produced an invalid PNG file");
+						}
+
+						await rename(temporaryPath, absolutePath);
+						return {
+							content: [
+								{ type: "text", text: `Captured window ${params.window_id} to ${absolutePath}` },
+								{ type: "image", data: image.toString("base64"), mimeType: "image/png" },
+							],
+							details: { path: absolutePath, window_id: params.window_id },
+						};
+					} finally {
+						await rm(temporaryPath, { force: true });
+					}
+				});
+			},
+		}),
+	);
+
+	pi.registerTool(
+		defineTool<typeof activateAppSchema, ActivationDetails>({
+			name: "activate_app",
+			label: "Activate App",
+			description:
+				"Bring a running macOS application and its windows to the foreground by process ID. Use a PID returned by list_windows.",
+			promptSnippet: "Bring a listed macOS application to the foreground by process ID",
+			promptGuidelines: [
+				"Use activate_app only when foregrounding a listed application is needed for visual validation because it changes user focus.",
+			],
+			parameters: activateAppSchema,
+			async execute(_toolCallId, params, signal) {
+				if (process.platform !== "darwin") throw new Error("activate_app is only available on macOS");
+				const result = await runHelper(["activate", String(params.pid)], signal, 5000);
+				if (result.code !== 0) throw new Error(result.stderr.trim() || result.stdout.trim() || "Activation failed");
+				return {
+					content: [{ type: "text", text: `Activated application PID ${params.pid}` }],
+					details: { pid: params.pid },
+				};
+			},
+		}),
+	);
+
+	pi.on("session_start", () => rowState.clear());
+}
+
+export default function appshotExtension(pi: ExtensionAPI): void {
+	registerAppshotTools(pi, createNativeHelper(pi));
+}

package/extensions/appshot/native-helper.ts

@@ -0,0 +1,102 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface HelperResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+}
+
+export type RunHelper = (args: string[], signal: AbortSignal | undefined, timeout: number) => Promise<HelperResult>;
+
+const MACH_O_64_MAGIC = Buffer.from([0xcf, 0xfa, 0xed, 0xfe]);
+
+async function validExecutable(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.X_OK);
+		const handle = await open(path, "r");
+		try {
+			const magic = Buffer.alloc(MACH_O_64_MAGIC.length);
+			const { bytesRead } = await handle.read(magic, 0, magic.length, 0);
+			return bytesRead === magic.length && magic.equals(MACH_O_64_MAGIC);
+		} finally {
+			await handle.close();
+		}
+	} catch {
+		return false;
+	}
+}
+
+export function createNativeHelper(pi: Pick<ExtensionAPI, "exec">): RunHelper {
+	let helperPromise: Promise<string> | undefined;
+	let resolvedExecutable: string | undefined;
+
+	async function buildHelper(signal: AbortSignal | undefined): Promise<string> {
+		const architecture = process.arch === "arm64" ? "arm64" : process.arch === "x64" ? "x86_64" : undefined;
+		if (!architecture) throw new Error(`Appshot does not support ${process.arch} macOS processes`);
+
+		const sourcePath = fileURLToPath(new URL("capture.swift", import.meta.url));
+		const source = await readFile(sourcePath);
+		const sourceHash = createHash("sha256").update(source).digest("hex").slice(0, 16);
+		const cacheDirectory = join(homedir(), "Library", "Caches", "tau-agent", "appshot", architecture, sourceHash);
+		const executablePath = join(cacheDirectory, "tau-appshot");
+		if (await validExecutable(executablePath)) return executablePath;
+
+		await rm(executablePath, { force: true });
+		await mkdir(cacheDirectory, { recursive: true });
+		const temporaryPath = `${executablePath}.${process.pid}.${randomUUID()}.tmp`;
+		try {
+			const result = await pi.exec(
+				"xcrun",
+				[
+					"swiftc",
+					"-parse-as-library",
+					"-target",
+					`${architecture}-apple-macosx14.0`,
+					sourcePath,
+					"-o",
+					temporaryPath,
+				],
+				{ signal, timeout: 120_000 },
+			);
+			if (result.code !== 0) {
+				throw new Error(`Failed to build macOS screenshot helper: ${result.stderr.trim() || result.stdout.trim()}`);
+			}
+			await rename(temporaryPath, executablePath);
+			return executablePath;
+		} finally {
+			await rm(temporaryPath, { force: true });
+		}
+	}
+
+	async function executable(signal: AbortSignal | undefined): Promise<string> {
+		return (helperPromise ??= buildHelper(signal)
+			.then((path) => {
+				resolvedExecutable = path;
+				return path;
+			})
+			.catch((error: unknown) => {
+				helperPromise = undefined;
+				throw error;
+			}));
+	}
+
+	return async (args, signal, timeout) => {
+		const path = await executable(signal);
+		try {
+			return await pi.exec(path, args, { signal, timeout });
+		} catch (error) {
+			if (!signal?.aborted && resolvedExecutable === path) {
+				await rm(path, { force: true });
+				resolvedExecutable = undefined;
+				helperPromise = undefined;
+			}
+			throw error;
+		}
+	};
+}

package/extensions/attention/README.md

@@ -0,0 +1,23 @@
+# Attention
+
+Sends a terminal-driven attention notification when Tau is ready for input.
+
+## Behavior
+
+- Emits an attention notification on `agent_end`.
+- Listens for shared event `tau:agent.blocked` when Tau is waiting on user input.
+- Uses the terminal or host OS notification path that best fits the current environment.
+
+Other code can call:
+
+```ts
+emitAgentBlocked(pi, { source: "my-extension", body: "Waiting for your input" });
+```
+
+`title`, `body`, and `source` are optional. Notification defaults are `Tau` and `Ready for input`.
+
+## Limits
+
+- No configuration.
+- No Windows-specific support.
+- Exact notification behavior depends on terminal and OS support.

package/extensions/attention/index.ts

@@ -0,0 +1,71 @@
+import { existsSync } from "node:fs";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { onTauEvent } from "../../shared/events.js";
+
+const DEFAULT_TITLE = "Tau";
+const DEFAULT_BODY = "Ready for input";
+const MACOS_SOUND = "/System/Library/Sounds/Submarine.aiff";
+
+function oscText(value: string): string {
+	return [...value]
+		.map((char) => {
+			const code = char.charCodeAt(0);
+			return code < 32 || code === 127 || char === ";" ? " " : char;
+		})
+		.join("")
+		.trim();
+}
+
+function playMacOSSound(pi: ExtensionAPI): void {
+	if (process.platform !== "darwin") return;
+
+	pi.exec("afplay", [MACOS_SOUND], { timeout: 2000 }).catch(() => undefined);
+}
+
+export default function attentionExtension(pi: ExtensionAPI): void {
+	function notify(data: { title?: string; body?: string }): void {
+		const raw: unknown = data;
+		const record = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+		const title = typeof record.title === "string" && record.title.trim() ? record.title.trim() : DEFAULT_TITLE;
+		const body = typeof record.body === "string" && record.body.trim() ? record.body.trim() : DEFAULT_BODY;
+		const oscTitle = oscText(title);
+		const oscBody = oscText(body);
+		const osc777 = `\x1b]777;notify;${oscTitle};${oscBody}\x07`;
+
+		if (
+			existsSync("/tmp/cmux.sock") ||
+			process.env.CMUX ||
+			process.env.CMUX_SESSION ||
+			Object.keys(process.env).some((key) => key.startsWith("CMUX_"))
+		) {
+			pi.exec("cmux", ["notify", "--title", title, "--body", body], { timeout: 2000 })
+				.then((result) => {
+					if (result.code !== 0) {
+						process.stdout.write(osc777);
+						playMacOSSound(pi);
+					}
+				})
+				.catch(() => {
+					process.stdout.write(osc777);
+					playMacOSSound(pi);
+				});
+			return;
+		}
+
+		if (process.env.KITTY_WINDOW_ID) {
+			process.stdout.write(`\x1b]99;i=1:e=1:d=0:p=title;${oscTitle}\x1b\\`);
+			process.stdout.write(`\x1b]99;i=1:e=1:d=1:p=body;${oscBody}\x1b\\`);
+			return;
+		}
+
+		process.stdout.write(osc777);
+		playMacOSSound(pi);
+	}
+
+	onTauEvent(pi, "attention.agent-blocked", "tau:agent.blocked", notify);
+
+	pi.on("agent_end", (_event, ctx) => {
+		if (ctx.mode === "print") return;
+		notify({ title: DEFAULT_TITLE, body: DEFAULT_BODY });
+	});
+}

package/extensions/auto-name/README.md

@@ -0,0 +1,26 @@
+# Auto-Name
+
+Names chat sessions automatically from the user's first prompt, in the background, while the agent works.
+
+## Why
+
+New sessions show up as their first message in the session selector. Auto-Name gives them a short, descriptive title without making the user run `/name` or interrupting the agent.
+
+## How it works
+
+- On the first user prompt, fires a background model call to summarize it into a short name.
+- Sets the name with `pi.setSessionName()` when it resolves. The agent is never blocked.
+- **Never overwrites an existing name** — a manual `/name` or a prior auto-name always sticks.
+- The model may decline if the prompt is too short, ambiguous, or a bare command.
+- Uses cheap fallback models (shared with `/commit`); a provider that fails is cooled down for both features.
+- Cancels on session switch (`/new`, `/resume`, `/reload`) so a name is never written into the wrong session.
+
+## Usage
+
+No invocation needed. Load extension, then reload:
+
+```text
+/reload
+```
+
+Send a prompt; the session gets named within a few seconds. Rename anytime with `/name`.

package/extensions/auto-name/index.ts

@@ -0,0 +1,163 @@
+import { type ThinkingLevel, type Tool, Type } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	getBranchInjectedContexts,
+	getPendingInjectedContexts,
+	type InjectedContext,
+} from "../../shared/injected-context.ts";
+import { generateToolValidated, resolveCandidates } from "../../shared/model-fallback/index.ts";
+import { errorText, truncAt } from "../../shared/text.ts";
+
+const STATUS_KEY = "auto-name";
+const SENTINEL = "NONE";
+const MAX_NAME_LENGTH = 80;
+const MAX_NAMING_INPUT_CHARS = 120_000;
+const AUTO_NAME_MODELS: ReadonlyArray<{ provider: string; model: string; reasoning: ThinkingLevel }> = [
+	{ provider: "openai-codex", model: "gpt-5.4-mini", reasoning: "medium" },
+	{ provider: "openrouter", model: "cohere/north-mini-code:free", reasoning: "high" },
+];
+
+const NAMING_PROMPT = [
+	"You are naming a chat session based on the user's first message and any injected hidden context.",
+	"Your only job is to call the name_session tool exactly once.",
+	"Do not write any text before or after the tool call. Do not answer in prose. Do not ask a follow-up question.",
+	"Answer the question: what is this chat about?",
+	"",
+	"If injected context is present, treat it as primary; the user message may be generic command text.",
+	"",
+	"Rules:",
+	"- A brief natural phrase that says what the work is about. Not a URL slug, not a keyword list.",
+	"- If the work targets a specific named feature, component, or file in the repository, call it out by name.",
+	"- A person scanning a session list a week later should know what this chat was about.",
+	"- No quotes, no trailing punctuation, no markdown, no code fences.",
+	'- No filler like "task:", "chat about", "working on".',
+	"",
+	'Good: "Improving auto-name model selection and prompt"',
+	'Bad:  "automatic naming function and prompt improvement"',
+	"",
+	'Good: "Cleaning up old plan notes before commit"',
+	'Bad:  "commit plan note and previous plan"',
+	"",
+	"The bad examples are keyword slugs — compressed word salads that tell you nothing about the actual work.",
+	"",
+	`- If the message is too short, ambiguous, a bare command, or has no clear topic, submit exactly: ${SENTINEL}`,
+	"- Call name_session with the name only.",
+].join("\n");
+const NAME_SESSION_TOOL = {
+	name: "name_session",
+	description: "Submit the generated session name. This is the only allowed response.",
+	parameters: Type.Object({
+		name: Type.String({ description: `Session name, or exactly ${SENTINEL} when there is no clear topic.` }),
+	}),
+} satisfies Tool;
+
+let generation = 0;
+let activeController: AbortController | undefined;
+
+export default function autoNameExtension(pi: ExtensionAPI): void {
+	pi.on("before_agent_start", (event, ctx) => {
+		const prompt = buildNamingInput(event.prompt, [
+			...getBranchInjectedContexts(ctx.sessionManager.getBranch()),
+			...getPendingInjectedContexts(),
+		]);
+		if (!prompt || pi.getSessionName()) return;
+
+		const myGen = ++generation;
+		activeController?.abort();
+		const controller = new AbortController();
+		activeController = controller;
+
+		void runAutoName(pi, ctx, controller, myGen, prompt);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		generation++;
+		activeController?.abort();
+		activeController = undefined;
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+	});
+}
+
+async function runAutoName(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	controller: AbortController,
+	myGen: number,
+	prompt: string,
+): Promise<void> {
+	const ui = ctx.ui;
+	try {
+		const candidates = await resolveCandidates(ctx, AUTO_NAME_MODELS);
+		const result = await generateToolValidated(
+			{ ui, signal: controller.signal },
+			candidates,
+			`${NAMING_PROMPT}\n\n${prompt}`,
+			NAME_SESSION_TOOL,
+			nameResultFromToolInput,
+			(error, text) =>
+				[
+					`That session name failed validation: ${error.message}`,
+					`Call ${NAME_SESSION_TOOL.name} again with corrected arguments only.`,
+					"Previous response:",
+					text,
+				].join("\n"),
+			{ statusKey: STATUS_KEY, notifyOnFallback: false, maxAttempts: 3 },
+		);
+
+		if (controller.signal.aborted || myGen !== generation) return;
+		if (!result.name) return;
+		if (pi.getSessionName()) return;
+
+		pi.setSessionName(result.name);
+		ui.notify(`Session named: ${result.name}`, "info");
+	} catch (error) {
+		if (!controller.signal.aborted && myGen === generation) {
+			ui.notify(`Session naming failed: ${errorText(error)}`, "error");
+		}
+	} finally {
+		if (activeController === controller) {
+			activeController = undefined;
+			ui.setStatus(STATUS_KEY, undefined);
+		}
+	}
+}
+
+function buildNamingInput(userMessage: string, contexts: readonly InjectedContext[]): string {
+	const prompt = userMessage.trim();
+	if (!prompt && contexts.length === 0) return "";
+
+	const parts = [
+		"User message:",
+		prompt || "(none)",
+		...contexts.flatMap((context, index) => [
+			"",
+			`Injected context ${index + 1}: ${context.details.title ?? context.details.source}`,
+			truncAt(context.content, MAX_NAMING_INPUT_CHARS),
+		]),
+	];
+	return truncAt(parts.join("\n"), MAX_NAMING_INPUT_CHARS);
+}
+
+interface NameResult {
+	name: string | null;
+}
+
+function nameResultFromToolInput(input: unknown): NameResult {
+	if (!isNameSessionToolInput(input)) throw new Error("Session name tool input is malformed.");
+	return validateName(input.name);
+}
+
+function isNameSessionToolInput(input: unknown): input is { name: string } {
+	return typeof input === "object" && input !== null && "name" in input && typeof input.name === "string";
+}
+
+function validateName(text: string): NameResult {
+	const name = text
+		.trim()
+		.replace(/^["'\s]+|["'\s]+$/g, "")
+		.replace(/[.`]+$/g, "")
+		.trim()
+		.slice(0, MAX_NAME_LENGTH);
+	if (!name || name.toUpperCase() === SENTINEL) return { name: null };
+	return { name };
+}

package/extensions/branch/README.md

@@ -0,0 +1,22 @@
+# Branch
+
+Switch to a recently updated Git branch, or create a typed branch from the
+current `HEAD`.
+
+Run `/branch` to open a picker containing local branches and already-fetched
+remote branches. The picker shows up to 10 branches at once, ordered by their
+latest commit with the most recent first.
+
+Press `Ctrl+F` in the picker to fetch all configured remotes and refresh the
+open list. Selecting a remote branch creates a local branch that tracks it.
+Cancelling the picker does not switch branches.
+
+Run `/branch new`, choose `feature`, `fix`, or `chore`, then enter a branch
+name. The name is lowercased, punctuation and whitespace become hyphens, and
+leading or trailing hyphens are removed.
+
+For example, selecting `fix` and entering `Fix login. Please` creates and
+switches to `fix/fix-login-please`.
+
+Cancelling either creation prompt creates nothing. Uncommitted changes follow
+normal `git switch` behavior for both switching and creation.