pi-studio 0.9.11 → 0.9.13

package/index.ts

@@ -4,7 +4,7 @@ import { completeSimple, type ThinkingLevel } from "@earendil-works/pi-ai";
 import { Type } from "@sinclair/typebox";
 import { spawn, spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { homedir, tmpdir } from "node:os";
@@ -365,6 +365,7 @@ interface ReplStartRequestMessage {
 	requestId: string;
 	runtime: StudioReplRuntime;
 	newSession?: boolean;
+	command?: string;
 }
 
 interface ReplStopRequestMessage {
@@ -1861,6 +1862,36 @@ function expandHome(pathInput: string): string {
 	return join(home, pathInput.slice(2));
 }
 
+function normalizeStudioResourceDirectoryInput(resourceDir: string): string {
+	let value = stripMatchingPathQuotes(String(resourceDir || "").trim());
+	if (!value) return "";
+	if (/^file:\/\//i.test(value)) {
+		try {
+			value = decodeURIComponent(new URL(value).pathname || value).trim();
+		} catch {
+			// Keep the original value if URL parsing fails.
+		}
+	}
+	const windowsMatch = value.match(/.*([A-Za-z]:[\\/].*)$/);
+	if (windowsMatch?.[1]) return windowsMatch[1].trim();
+	const markers = ["/Users/", "/home/", "/Volumes/", "/private/", "/tmp/", "/var/", "/opt/", "/Applications/"];
+	let embeddedAbsoluteIndex = -1;
+	for (const marker of markers) {
+		const index = value.lastIndexOf(marker);
+		if (index > 0) embeddedAbsoluteIndex = Math.max(embeddedAbsoluteIndex, index);
+	}
+	if (embeddedAbsoluteIndex > 0) value = value.slice(embeddedAbsoluteIndex).trim();
+	return value;
+}
+
+function recoverLikelyDroppedLeadingSlashPath(pathInput: string): string {
+	const value = String(pathInput || "").trim();
+	if (!value || isAbsolute(value)) return value;
+	if (!/^(?:Users|home|Volumes|private|tmp|var|opt|Applications)\//.test(value)) return value;
+	const candidate = `/${value}`;
+	return existsSync(candidate) ? candidate : value;
+}
+
 function resolveStudioPath(pathArg: string, cwd: string): { ok: true; resolved: string; label: string } | { ok: false; message: string } {
 	const normalized = normalizePathInput(pathArg);
 	if (!normalized) {
@@ -2331,23 +2362,53 @@ function resolveStudioBaseDir(sourcePath: string | undefined, resourceDir: strin
 		return dirname(isAbsolute(expanded) ? expanded : resolve(fallbackCwd, expanded));
 	}
 
-	const resource = typeof resourceDir === "string" ? resourceDir.trim() : "";
+	const resource = normalizeStudioResourceDirectoryInput(typeof resourceDir === "string" ? resourceDir : "");
 	if (resource) {
-		const expanded = expandHome(resource);
+		const expanded = recoverLikelyDroppedLeadingSlashPath(expandHome(resource));
 		return isAbsolute(expanded) ? expanded : resolve(fallbackCwd, expanded);
 	}
 
 	return fallbackCwd;
 }
 
+function isPathInsideOrEqualDirectory(childPath: string, parentDir: string): boolean {
+	const rel = relative(parentDir, childPath);
+	return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function resolveStudioPreviewResourceContext(sourcePath: string | undefined, resourceDir: string | undefined, fallbackCwd: string): { baseDir: string; boundaryDir: string } {
+	const source = typeof sourcePath === "string" ? sourcePath.trim() : "";
+	const sourceBaseDir = source
+		? dirname(isAbsolute(recoverLikelyDroppedLeadingSlashPath(expandHome(source)))
+			? recoverLikelyDroppedLeadingSlashPath(expandHome(source))
+			: resolve(fallbackCwd, recoverLikelyDroppedLeadingSlashPath(expandHome(source))))
+		: "";
+
+	const resource = normalizeStudioResourceDirectoryInput(typeof resourceDir === "string" ? resourceDir : "");
+	const resourceBaseDir = resource
+		? (isAbsolute(recoverLikelyDroppedLeadingSlashPath(expandHome(resource)))
+			? recoverLikelyDroppedLeadingSlashPath(expandHome(resource))
+			: resolve(fallbackCwd, recoverLikelyDroppedLeadingSlashPath(expandHome(resource))))
+		: "";
+
+	const baseDir = sourceBaseDir || resourceBaseDir || fallbackCwd;
+	let boundaryDir = baseDir;
+	if (resourceBaseDir) {
+		boundaryDir = !sourceBaseDir || isPathInsideOrEqualDirectory(resolve(sourceBaseDir), resolve(resourceBaseDir))
+			? resourceBaseDir
+			: baseDir;
+	}
+	return { baseDir, boundaryDir };
+}
+
 function resolveStudioGitDiffBaseDir(sourcePath: string | undefined, resourceDir: string | undefined, fallbackCwd: string): string {
 	return resolveStudioBaseDir(sourcePath, resourceDir, fallbackCwd);
 }
 
 function resolveStudioCompanionResourceDir(sourcePath: string | undefined, resourceDir: string | undefined, fallbackCwd: string): string | undefined {
-	const explicitResource = typeof resourceDir === "string" ? resourceDir.trim() : "";
+	const explicitResource = normalizeStudioResourceDirectoryInput(typeof resourceDir === "string" ? resourceDir : "");
 	if (explicitResource) {
-		const expanded = expandHome(explicitResource);
+		const expanded = recoverLikelyDroppedLeadingSlashPath(expandHome(explicitResource));
 		return isAbsolute(expanded) ? expanded : resolve(fallbackCwd, expanded);
 	}
 
@@ -2364,9 +2425,184 @@ function buildStudioCompanionLabel(_label: string | undefined): string {
 	return "copy of editor text";
 }
 
+const STUDIO_HTML_PREVIEW_RESOURCE_MAX_BYTES = 25 * 1024 * 1024;
+const STUDIO_HTML_PREVIEW_IMAGE_MIME_BY_EXT = new Map<string, string>([
+	[".png", "image/png"],
+	[".jpg", "image/jpeg"],
+	[".jpeg", "image/jpeg"],
+	[".gif", "image/gif"],
+	[".webp", "image/webp"],
+]);
+const STUDIO_LOCAL_LINK_TEXT_EXTENSIONS = new Set([
+	".md", ".markdown", ".mdx", ".qmd", ".txt", ".tex", ".latex", ".rst", ".adoc",
+	".html", ".htm", ".css", ".xml", ".yaml", ".yml", ".toml", ".json", ".jsonc", ".json5", ".csv", ".tsv", ".log",
+	".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx",
+	".py", ".pyw", ".sh", ".bash", ".zsh", ".rs", ".c", ".h", ".cpp", ".cxx", ".cc", ".hpp", ".hxx",
+	".jl", ".f90", ".f95", ".f03", ".f", ".for", ".r", ".m", ".java", ".go", ".rb", ".swift", ".lua",
+	".diff", ".patch",
+]);
+const STUDIO_LOCAL_LINK_IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
+
+type StudioLocalPreviewResourceKind = "pdf" | "text" | "image" | "other";
+
+interface StudioLocalPreviewResource {
+	filePath: string;
+	label: string;
+	extension: string;
+	kind: StudioLocalPreviewResourceKind;
+	page: number | null;
+	resourceDir: string;
+}
+
 function resolveStudioPdfResourcePath(pdfPath: string | undefined, sourcePath: string | undefined, resourceDir: string | undefined, fallbackCwd: string): string {
-	const baseDir = resolveStudioBaseDir(sourcePath, resourceDir, fallbackCwd);
-	return resolveStudioPdfResourceFile(pdfPath, baseDir);
+	const rawPath = typeof pdfPath === "string" ? pdfPath.trim() : "";
+	if (!rawPath) throw new Error("Missing PDF path.");
+	if (/\0/.test(rawPath)) throw new Error("Invalid PDF path.");
+	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
+		throw new Error("Only local PDF paths are supported.");
+	}
+
+	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
+	const cleanedPath = decodeStudioHtmlPreviewResourcePath(stripStudioHtmlPreviewResourceUrlSuffix(rawPath));
+	const expandedPath = recoverLikelyDroppedLeadingSlashPath(expandHome(cleanedPath));
+	const candidate = isAbsolute(expandedPath) ? expandedPath : resolve(context.baseDir, expandedPath);
+	if (extname(candidate).toLowerCase() !== ".pdf") throw new Error("Only .pdf files can be embedded.");
+
+	const boundaryReal = realpathSync(context.boundaryDir);
+	const candidateReal = realpathSync(candidate);
+	const rel = relative(boundaryReal, candidateReal);
+	if (rel.startsWith("..") || isAbsolute(rel)) {
+		throw new Error("PDF path must stay within the current Studio resource directory.");
+	}
+
+	const stat = statSync(candidateReal);
+	if (!stat.isFile()) throw new Error("PDF path does not refer to a file.");
+	return candidateReal;
+}
+
+function stripStudioHtmlPreviewResourceUrlSuffix(resourcePath: string): string {
+	const withoutHash = resourcePath.split("#")[0] ?? resourcePath;
+	return withoutHash.split("?")[0] ?? withoutHash;
+}
+
+function decodeStudioHtmlPreviewResourcePath(resourcePath: string): string {
+	try {
+		return decodeURIComponent(resourcePath);
+	} catch {
+		return resourcePath;
+	}
+}
+
+function parseStudioLocalPreviewResourcePage(resourcePath: string): number | null {
+	const raw = String(resourcePath || "");
+	const parts: string[] = [];
+	const queryIndex = raw.indexOf("?");
+	if (queryIndex >= 0) {
+		const queryEnd = raw.indexOf("#", queryIndex);
+		parts.push(raw.slice(queryIndex + 1, queryEnd >= 0 ? queryEnd : raw.length));
+	}
+	const hashIndex = raw.indexOf("#");
+	if (hashIndex >= 0) parts.push(raw.slice(hashIndex + 1));
+	for (const part of parts) {
+		try {
+			const params = new URLSearchParams(part);
+			const rawPage = params.get("page") || params.get("p");
+			if (rawPage) {
+				const page = Number.parseInt(rawPage, 10);
+				if (Number.isFinite(page) && page > 0) return page;
+			}
+		} catch {
+			const match = part.match(/(?:^|[&;])page=(\d+)/i) || part.match(/^page=(\d+)$/i);
+			if (match && match[1]) {
+				const page = Number.parseInt(match[1], 10);
+				if (Number.isFinite(page) && page > 0) return page;
+			}
+		}
+	}
+	return null;
+}
+
+function getStudioLocalPreviewResourceKind(extension: string): StudioLocalPreviewResourceKind {
+	const ext = extension.toLowerCase();
+	if (ext === ".pdf") return "pdf";
+	if (STUDIO_LOCAL_LINK_TEXT_EXTENSIONS.has(ext)) return "text";
+	if (STUDIO_LOCAL_LINK_IMAGE_EXTENSIONS.has(ext)) return "image";
+	return "other";
+}
+
+function resolveStudioLocalPreviewResourcePath(
+	resourcePath: string | undefined,
+	sourcePath: string | undefined,
+	resourceDir: string | undefined,
+	fallbackCwd: string,
+): StudioLocalPreviewResource {
+	const rawPath = typeof resourcePath === "string" ? resourcePath.trim() : "";
+	if (!rawPath) throw new Error("Missing local resource path.");
+	if (/\0/.test(rawPath)) throw new Error("Invalid local resource path.");
+	if (/^\/\//.test(rawPath)) throw new Error("Network resources are not local Studio resources.");
+	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
+		throw new Error("Only local relative resources are supported.");
+	}
+
+	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
+	const cleanedPath = decodeStudioHtmlPreviewResourcePath(stripStudioHtmlPreviewResourceUrlSuffix(rawPath));
+	if (!cleanedPath || cleanedPath.startsWith("#")) throw new Error("Missing local resource path.");
+	const expandedPath = recoverLikelyDroppedLeadingSlashPath(expandHome(cleanedPath));
+	const candidate = isAbsolute(expandedPath) ? expandedPath : resolve(context.baseDir, expandedPath);
+	const extension = extname(candidate).toLowerCase();
+	const boundaryReal = realpathSync(context.boundaryDir);
+	const candidateReal = realpathSync(candidate);
+	const rel = relative(boundaryReal, candidateReal);
+	if (rel.startsWith("..") || isAbsolute(rel)) {
+		throw new Error("Local resource path must stay within the current Studio resource directory.");
+	}
+
+	const stat = statSync(candidateReal);
+	if (!stat.isFile()) throw new Error("Local resource path does not refer to a file.");
+	return {
+		filePath: candidateReal,
+		label: rel && rel !== "" ? rel : basename(candidateReal),
+		extension,
+		kind: getStudioLocalPreviewResourceKind(extension),
+		page: parseStudioLocalPreviewResourcePage(rawPath),
+		resourceDir: boundaryReal,
+	};
+}
+
+function resolveStudioHtmlPreviewResourcePath(
+	resourcePath: string | undefined,
+	sourcePath: string | undefined,
+	resourceDir: string | undefined,
+	fallbackCwd: string,
+): { filePath: string; mimeType: string } {
+	const rawPath = typeof resourcePath === "string" ? resourcePath.trim() : "";
+	if (!rawPath) throw new Error("Missing HTML preview resource path.");
+	if (/\0/.test(rawPath)) throw new Error("Invalid HTML preview resource path.");
+	if (/^[a-z][a-z0-9+.-]*:/i.test(rawPath) && !/^[a-z]:[\\/]/i.test(rawPath)) {
+		throw new Error("Only local HTML preview resources are supported.");
+	}
+
+	const context = resolveStudioPreviewResourceContext(sourcePath, resourceDir, fallbackCwd);
+	const cleanedPath = decodeStudioHtmlPreviewResourcePath(stripStudioHtmlPreviewResourceUrlSuffix(rawPath));
+	const expandedPath = recoverLikelyDroppedLeadingSlashPath(expandHome(cleanedPath));
+	const candidate = isAbsolute(expandedPath) ? expandedPath : resolve(context.baseDir, expandedPath);
+	const ext = extname(candidate).toLowerCase();
+	const mimeType = STUDIO_HTML_PREVIEW_IMAGE_MIME_BY_EXT.get(ext);
+	if (!mimeType) throw new Error("Only local PNG, JPEG, GIF, and WebP images can be embedded in HTML previews.");
+
+	const boundaryReal = realpathSync(context.boundaryDir);
+	const candidateReal = realpathSync(candidate);
+	const rel = relative(boundaryReal, candidateReal);
+	if (rel.startsWith("..") || isAbsolute(rel)) {
+		throw new Error("HTML preview resource path must stay within the current Studio resource directory.");
+	}
+
+	const stat = statSync(candidateReal);
+	if (!stat.isFile()) throw new Error("HTML preview resource path does not refer to a file.");
+	if (stat.size > STUDIO_HTML_PREVIEW_RESOURCE_MAX_BYTES) {
+		throw new Error("HTML preview resource is too large to embed.");
+	}
+	return { filePath: candidateReal, mimeType };
 }
 
 function resolveStudioPandocWorkingDir(baseDir: string | undefined): string | undefined {
@@ -6279,6 +6515,151 @@ function respondPdfFile(req: IncomingMessage, res: ServerResponse, filePath: str
 	res.end(method === "HEAD" ? undefined : pdf);
 }
 
+function respondHtmlPreviewResourceJson(req: IncomingMessage, res: ServerResponse, filePath: string, mimeType: string): void {
+	const method = (req.method ?? "GET").toUpperCase();
+	if (method !== "GET" && method !== "HEAD") {
+		res.setHeader("Allow", "GET, HEAD");
+		respondJson(res, 405, { ok: false, error: "Method not allowed. Use GET." });
+		return;
+	}
+
+	const data = method === "HEAD" ? "" : readFileSync(filePath).toString("base64");
+	respondJson(res, 200, {
+		ok: true,
+		mimeType,
+		filename: basename(filePath),
+		dataUrl: method === "HEAD" ? "" : `data:${mimeType};base64,${data}`,
+	});
+}
+
+function respondLocalPreviewLinkJson(req: IncomingMessage, res: ServerResponse, requestUrl: URL, resource: StudioLocalPreviewResource, serverState: StudioServerState): void {
+	const method = (req.method ?? "GET").toUpperCase();
+	if (method !== "GET" && method !== "HEAD") {
+		res.setHeader("Allow", "GET, HEAD");
+		respondJson(res, 405, { ok: false, error: "Method not allowed. Use GET." });
+		return;
+	}
+
+	const action = (requestUrl.searchParams.get("action") ?? "resolve").trim().toLowerCase();
+	const basePayload = {
+		ok: true,
+		kind: resource.kind,
+		path: resource.filePath,
+		label: resource.label,
+		extension: resource.extension,
+		page: resource.page,
+		resourceDir: resource.resourceDir,
+	};
+
+	if (method === "HEAD" || action === "resolve") {
+		respondJson(res, 200, basePayload);
+		return;
+	}
+
+	if (action !== "document" && action !== "editor-url") {
+		respondJson(res, 400, { ok: false, error: "Unsupported local link action." });
+		return;
+	}
+	if (resource.kind !== "text") {
+		respondJson(res, 400, { ok: false, error: "This local resource is not a text document Studio can load into the editor." });
+		return;
+	}
+
+	const file = readStudioFile(resource.filePath, dirname(resource.filePath));
+	if (file.ok === false) {
+		respondJson(res, 400, { ok: false, error: file.message });
+		return;
+	}
+
+	const document: InitialStudioDocument = {
+		text: file.text,
+		label: resource.label || file.label,
+		source: "file",
+		path: file.resolvedPath,
+		resourceDir: resource.resourceDir,
+	};
+	if (action === "document") {
+		respondJson(res, 200, {
+			...basePayload,
+			text: file.text,
+			resourceDir: resource.resourceDir,
+		});
+		return;
+	}
+
+	const docId = storeTransientStudioDocument(document);
+	const url = buildStudioUrl(serverState.port, serverState.token, "editor-only", document, docId);
+	const parsedUrl = new URL(url);
+	respondJson(res, 200, {
+		...basePayload,
+		url,
+		relativeUrl: `${parsedUrl.pathname}${parsedUrl.search}`,
+	});
+}
+
+function revealStudioLocalFile(filePath: string): { ok: true; message: string } | { ok: false; message: string } {
+	if (isSshSession()) {
+		return { ok: false, message: "Cannot reveal files from an SSH/headless Studio session. Copy the path instead." };
+	}
+
+	let command = "";
+	let args: string[] = [];
+	if (process.platform === "darwin") {
+		command = "open";
+		args = ["-R", filePath];
+	} else if (process.platform === "win32") {
+		command = "explorer.exe";
+		args = [`/select,${filePath}`];
+	} else {
+		command = "xdg-open";
+		args = [dirname(filePath)];
+	}
+
+	const result = spawnSync(command, args, { stdio: "ignore" });
+	if (result.error) {
+		return { ok: false, message: `Could not open file manager: ${result.error.message}` };
+	}
+	if (result.status !== 0) {
+		return { ok: false, message: "Could not open file manager for this resource." };
+	}
+	return { ok: true, message: process.platform === "linux" ? "Opened containing folder." : "Revealed resource in file manager." };
+}
+
+async function handleRevealLocalPreviewResourceRequest(req: IncomingMessage, res: ServerResponse, studioCwd: string): Promise<void> {
+	const method = (req.method ?? "GET").toUpperCase();
+	if (method !== "POST") {
+		res.setHeader("Allow", "POST");
+		respondJson(res, 405, { ok: false, error: "Method not allowed. Use POST." });
+		return;
+	}
+
+	const rawBody = await readRequestBody(req, REQUEST_BODY_MAX_BYTES);
+	let payload: Record<string, unknown> = {};
+	try {
+		payload = rawBody ? JSON.parse(rawBody) : {};
+	} catch {
+		respondJson(res, 400, { ok: false, error: "Invalid JSON body." });
+		return;
+	}
+
+	try {
+		const resource = resolveStudioLocalPreviewResourcePath(
+			typeof payload.path === "string" ? payload.path : "",
+			typeof payload.sourcePath === "string" ? payload.sourcePath : undefined,
+			typeof payload.resourceDir === "string" ? payload.resourceDir : undefined,
+			studioCwd,
+		);
+		const result = revealStudioLocalFile(resource.filePath);
+		if (!result.ok) {
+			respondJson(res, 409, { ok: false, error: result.message, path: resource.filePath });
+			return;
+		}
+		respondJson(res, 200, { ok: true, message: result.message, path: resource.filePath, label: resource.label });
+	} catch (error) {
+		respondJson(res, 404, { ok: false, error: `Local resource unavailable: ${error instanceof Error ? error.message : String(error)}` });
+	}
+}
+
 function openUrlInDefaultBrowser(url: string): Promise<void> {
 	const openCommand =
 		process.platform === "darwin"
@@ -7183,6 +7564,7 @@ function parseIncomingMessage(data: RawData): IncomingStudioMessage | null {
 				requestId: msg.requestId,
 				runtime,
 				newSession: Boolean(msg.newSession),
+				command: typeof msg.command === "string" ? msg.command : undefined,
 			};
 		}
 	}
@@ -7326,37 +7708,184 @@ function isGenericToolActivityLabel(label: string | null | undefined): boolean {
 		|| normalized === "editing file";
 }
 
+function splitStudioShellWords(segment: string): string[] {
+	const words: string[] = [];
+	let current = "";
+	let quote: "'" | "\"" | null = null;
+	let escaped = false;
+
+	for (const char of String(segment || "")) {
+		if (escaped) {
+			current += char;
+			escaped = false;
+			continue;
+		}
+		if (char === "\\" && quote !== "'") {
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			if (char === quote) quote = null;
+			else current += char;
+			continue;
+		}
+		if (char === "'" || char === "\"") {
+			quote = char;
+			continue;
+		}
+		if (/\s/.test(char)) {
+			if (current) {
+				words.push(current);
+				current = "";
+			}
+			continue;
+		}
+		current += char;
+	}
+	if (escaped) current += "\\";
+	if (current) words.push(current);
+	return words;
+}
+
+function normalizeStudioShellCommandToken(token: string): string {
+	let value = String(token || "").trim();
+	if (!value) return "";
+	const slashIndex = value.lastIndexOf("/");
+	if (slashIndex >= 0) value = value.slice(slashIndex + 1);
+	return value.toLowerCase();
+}
+
+function isStudioShellAssignmentToken(token: string): boolean {
+	return /^[A-Za-z_][A-Za-z0-9_]*=/.test(String(token || ""));
+}
+
+function getStudioShellSegmentCommand(segment: string): { name: string; words: string[]; commandIndex: number } | null {
+	const words = splitStudioShellWords(segment);
+	let index = 0;
+	const skipAssignments = () => {
+		while (index < words.length && isStudioShellAssignmentToken(words[index] || "")) index += 1;
+	};
+
+	skipAssignments();
+	let guard = 0;
+	while (index < words.length && guard < 12) {
+		guard += 1;
+		const name = normalizeStudioShellCommandToken(words[index] || "");
+		if (!name) {
+			index += 1;
+			continue;
+		}
+		if (name === "command" || name === "builtin" || name === "exec") {
+			index += 1;
+			skipAssignments();
+			continue;
+		}
+		if (name === "time") {
+			index += 1;
+			while (index < words.length && String(words[index] || "").startsWith("-")) index += 1;
+			skipAssignments();
+			continue;
+		}
+		if (name === "env") {
+			index += 1;
+			while (index < words.length) {
+				const token = String(words[index] || "");
+				const lowerToken = token.toLowerCase();
+				if (isStudioShellAssignmentToken(token)) {
+					index += 1;
+					continue;
+				}
+				if (lowerToken === "-u" || lowerToken === "--unset" || lowerToken === "-s" || lowerToken === "-S") {
+					index += 2;
+					continue;
+				}
+				if (lowerToken.startsWith("-")) {
+					index += 1;
+					continue;
+				}
+				break;
+			}
+			skipAssignments();
+			continue;
+		}
+		if (name === "sudo") {
+			index += 1;
+			while (index < words.length) {
+				const option = String(words[index] || "");
+				if (!option.startsWith("-")) break;
+				const lowerOption = option.toLowerCase();
+				index += 1;
+				if (["-c", "-g", "-h", "-p", "-t", "-u"].includes(lowerOption) && index < words.length) {
+					index += 1;
+				}
+			}
+			skipAssignments();
+			continue;
+		}
+		return { name, words, commandIndex: index };
+	}
+	return null;
+}
+
+function getStudioGitSubcommand(args: string[]): string {
+	for (let index = 0; index < args.length; index += 1) {
+		const token = String(args[index] || "").toLowerCase();
+		if (!token) continue;
+		if (["-c", "-C", "--git-dir", "--work-tree", "--namespace", "--exec-path"].map((value) => value.toLowerCase()).includes(token)) {
+			index += 1;
+			continue;
+		}
+		if (/^--(?:git-dir|work-tree|namespace|exec-path)=/.test(token)) continue;
+		if (token.startsWith("-")) continue;
+		return normalizeStudioShellCommandToken(token);
+	}
+	return "";
+}
+
 function deriveBashActivityLabel(command: string): string | null {
 	const normalized = String(command || "").trim();
 	if (!normalized) return null;
-	const lower = normalized.toLowerCase();
 
-	const segments = lower
+	const segments = normalized
 		.split(/(?:&&|\|\||;|\n)+/g)
 		.map((segment) => segment.trim())
 		.filter((segment) => segment.length > 0);
 
 	let hasPwd = false;
+	let hasLs = false;
 	let hasLsCurrent = false;
 	let hasLsParent = false;
 	let hasFind = false;
 	let hasFindCurrentListing = false;
 	let hasFindParentListing = false;
+	let hasTextSearch = false;
+	let hasFileRead = false;
+	let hasGit = false;
+	let hasGitStatus = false;
+	let hasGitDiff = false;
+	let hasNpm = false;
+	let hasPython = false;
+	let hasNode = false;
 
 	for (const segment of segments) {
-		if (/\bpwd\b/.test(segment)) hasPwd = true;
+		const commandInfo = getStudioShellSegmentCommand(segment);
+		if (!commandInfo) continue;
+		const commandName = commandInfo.name;
+		const args = commandInfo.words.slice(commandInfo.commandIndex + 1);
+
+		if (commandName === "pwd") hasPwd = true;
 
-		if (/\bls\b/.test(segment)) {
-			if (/\.\./.test(segment)) hasLsParent = true;
+		if (commandName === "ls") {
+			hasLs = true;
+			if (args.some((arg) => arg === ".." || arg === "../" || arg.startsWith("../"))) hasLsParent = true;
 			else hasLsCurrent = true;
 		}
 
-		if (/\bfind\b/.test(segment)) {
+		if (commandName === "find") {
 			hasFind = true;
-			const pathMatch = segment.match(/\bfind\s+([^\s]+)/);
-			const pathToken = pathMatch ? pathMatch[1] : "";
-			const hasSelector = /-(?:name|iname|regex|path|ipath|newer|mtime|mmin|size|user|group)\b/.test(segment);
-			const listingLike = /-maxdepth\s+\d+\b/.test(segment) && !hasSelector;
+			const pathToken = args.find((arg) => arg && !String(arg).startsWith("-")) || "";
+			const hasSelector = /-(?:name|iname|regex|path|ipath|newer|mtime|mmin|size|user|group)\b/i.test(segment);
+			const listingLike = /-maxdepth\s+\d+\b/i.test(segment) && !hasSelector;
 
 			if (listingLike) {
 				if (pathToken === ".." || pathToken === "../") {
@@ -7366,6 +7895,18 @@ function deriveBashActivityLabel(command: string): string | null {
 				}
 			}
 		}
+
+		if (commandName === "rg" || commandName === "grep") hasTextSearch = true;
+		if (commandName === "cat" || commandName === "sed" || commandName === "awk") hasFileRead = true;
+		if (commandName === "git") {
+			hasGit = true;
+			const subcommand = getStudioGitSubcommand(args);
+			if (subcommand === "status") hasGitStatus = true;
+			if (subcommand === "diff") hasGitDiff = true;
+		}
+		if (commandName === "npm") hasNpm = true;
+		if (/^python(?:3(?:\.\d+)?)?$/.test(commandName)) hasPython = true;
+		if (commandName === "node") hasNode = true;
 	}
 
 	const hasCurrentListing = hasLsCurrent || hasFindCurrentListing;
@@ -7380,34 +7921,34 @@ function deriveBashActivityLabel(command: string): string | null {
 	if (hasParentListing) {
 		return "Listing parent directory files";
 	}
-	if (hasCurrentListing || /\bls\b/.test(lower)) {
+	if (hasCurrentListing || hasLs) {
 		return "Listing directory files";
 	}
-	if (hasFind || /\bfind\b/.test(lower)) {
+	if (hasFind) {
 		return "Searching files";
 	}
-	if (/\brg\b/.test(lower) || /\bgrep\b/.test(lower)) {
+	if (hasTextSearch) {
 		return "Searching text in files";
 	}
-	if (/\bcat\b/.test(lower) || /\bsed\b/.test(lower) || /\bawk\b/.test(lower)) {
+	if (hasFileRead) {
 		return "Reading file content";
 	}
-	if (/\bgit\s+status\b/.test(lower)) {
+	if (hasGitStatus) {
 		return "Checking git status";
 	}
-	if (/\bgit\s+diff\b/.test(lower)) {
+	if (hasGitDiff) {
 		return "Reviewing git changes";
 	}
-	if (/\bgit\b/.test(lower)) {
+	if (hasGit) {
 		return "Running git command";
 	}
-	if (/\bnpm\b/.test(lower)) {
+	if (hasNpm) {
 		return "Running npm command";
 	}
-	if (/\bpython3?\b/.test(lower)) {
+	if (hasPython) {
 		return "Running Python command";
 	}
-	if (/\bnode\b/.test(lower)) {
+	if (hasNode) {
 		return "Running Node.js command";
 	}
 	return "Running shell command";
@@ -7749,7 +8290,7 @@ function normalizeStudioReplRuntime(value: unknown): StudioReplRuntime | null {
 	return isStudioReplRuntime(normalized) ? normalized : null;
 }
 
-function getStudioReplRuntimeCommand(runtime: StudioReplRuntime): string {
+function getDefaultStudioReplRuntimeCommand(runtime: StudioReplRuntime): string {
 	if (runtime === "shell") return String(process.env.SHELL || "bash").trim() || "bash";
 	if (runtime === "python") return "python3";
 	if (runtime === "ipython") return "ipython";
@@ -7759,13 +8300,31 @@ function getStudioReplRuntimeCommand(runtime: StudioReplRuntime): string {
 	return "clojure";
 }
 
-function getStudioReplSessionName(runtime: StudioReplRuntime): string {
-	return `pi-studio-repl-${runtime}`;
+function normalizeStudioReplCommandOverride(runtime: StudioReplRuntime, command: string | undefined): string | undefined {
+	const normalized = String(command ?? "").replace(/\r?\n/g, " ").replace(/\s+/g, " ").trim();
+	if (!normalized) return undefined;
+	if (normalized.length > 240) return undefined;
+	if (normalized === getDefaultStudioReplRuntimeCommand(runtime)) return undefined;
+	return normalized;
+}
+
+function getStudioReplRuntimeCommand(runtime: StudioReplRuntime, command?: string): string {
+	return normalizeStudioReplCommandOverride(runtime, command) || getDefaultStudioReplRuntimeCommand(runtime);
+}
+
+function getStudioReplCommandSessionSuffix(runtime: StudioReplRuntime, command?: string): string {
+	const normalized = normalizeStudioReplCommandOverride(runtime, command);
+	if (!normalized) return "";
+	return `-${createHash("sha1").update(`${runtime}\n${normalized}`).digest("hex").slice(0, 8)}`;
+}
+
+function getStudioReplSessionName(runtime: StudioReplRuntime, command?: string): string {
+	return `pi-studio-repl-${runtime}${getStudioReplCommandSessionSuffix(runtime, command)}`;
 }
 
-function getNewStudioReplSessionName(runtime: StudioReplRuntime): string {
+function getNewStudioReplSessionName(runtime: StudioReplRuntime, command?: string): string {
 	const suffix = `${Date.now().toString(36)}-${randomUUID().slice(0, 6)}`;
-	return `pi-studio-repl-${runtime}-${suffix}`;
+	return `pi-studio-repl-${runtime}${getStudioReplCommandSessionSuffix(runtime, command)}-${suffix}`;
 }
 
 function getStudioReplPaneTarget(sessionName: string): string {
@@ -7865,9 +8424,10 @@ function captureStudioReplSession(sessionName: string): { ok: true; transcript:
 	return { ok: true, transcript: String(result.stdout || "").replace(/[\t ]+$/gm, "").trimEnd(), session };
 }
 
-function startStudioReplSession(runtime: StudioReplRuntime, cwd: string, options?: { newSession?: boolean }): { ok: true; session: StudioReplSessionInfo; message: string } | { ok: false; message: string } {
+function startStudioReplSession(runtime: StudioReplRuntime, cwd: string, options?: { newSession?: boolean; command?: string }): { ok: true; session: StudioReplSessionInfo; message: string } | { ok: false; message: string } {
 	if (!isTmuxAvailable()) return { ok: false, message: "tmux is not available. Install tmux to use Studio REPL sessions." };
-	const sessionName = options?.newSession ? getNewStudioReplSessionName(runtime) : getStudioReplSessionName(runtime);
+	const commandOverride = normalizeStudioReplCommandOverride(runtime, options?.command);
+	const sessionName = options?.newSession ? getNewStudioReplSessionName(runtime, commandOverride) : getStudioReplSessionName(runtime, commandOverride);
 	const existing = runStudioTmux(["has-session", "-t", sessionName], { timeout: 3_000 });
 	if (existing.ok) {
 		const inferred = inferStudioReplSessionRuntime(sessionName);
@@ -7883,7 +8443,7 @@ function startStudioReplSession(runtime: StudioReplRuntime, cwd: string, options
 			message: `${STUDIO_REPL_RUNTIME_LABELS[runtime]} REPL is already running.`,
 		};
 	}
-	const command = getStudioReplRuntimeCommand(runtime);
+	const command = getStudioReplRuntimeCommand(runtime, commandOverride);
 	const result = runStudioTmux(["new-session", "-d", "-s", sessionName, "-c", cwd || process.cwd(), command], { timeout: 5_000 });
 	if (!result.ok) return { ok: false, message: result.message || `Failed to start ${STUDIO_REPL_RUNTIME_LABELS[runtime]} REPL.` };
 	return {
@@ -7895,7 +8455,7 @@ function startStudioReplSession(runtime: StudioReplRuntime, cwd: string, options
 			label: formatStudioReplSessionLabel(sessionName, runtime, "studio"),
 			source: "studio",
 		},
-		message: `Started ${options?.newSession ? "new " : ""}${STUDIO_REPL_RUNTIME_LABELS[runtime]} REPL.`,
+		message: `Started ${options?.newSession ? "new " : ""}${STUDIO_REPL_RUNTIME_LABELS[runtime]} REPL${commandOverride ? ` with custom command: ${commandOverride}` : ""}.`,
 	};
 }
 
@@ -8398,7 +8958,7 @@ function resolveRequestedStudioDocumentFromUrl(
 				label: requestedLabel || file.label,
 				source: "file",
 				path: file.resolvedPath,
-				resourceDir: requestedResourceDir || undefined,
+				resourceDir: requestedResourceDir || dirname(file.resolvedPath),
 			};
 		}
 	}
@@ -8754,6 +9314,7 @@ ${cssVarsBlock}
       <button id="saveAsBtn" type="button" title="Save editor content to a new file path. Cmd/Ctrl+S falls back here when no direct save path is available.">Save editor as…</button>
       <button id="saveOverBtn" type="button" title="Overwrite current file with editor content. Shortcut: Cmd/Ctrl+S.">Save editor</button>
       <button id="refreshFromDiskBtn" type="button" title="Reload the current file-backed document from disk.">Refresh from disk</button>
+      <button id="clearWorkspaceBtn" type="button" title="Clear the current editor draft in this browser tab. Saved files and responses are not changed.">Clear editor</button>
       <label class="file-label" title="Load a local file into editor text.">Load file content<input id="fileInput" type="file" accept=".md,.markdown,.mdx,.qmd,.js,.mjs,.cjs,.jsx,.ts,.mts,.cts,.tsx,.py,.pyw,.sh,.bash,.zsh,.json,.jsonc,.json5,.rs,.c,.h,.cpp,.cxx,.cc,.hpp,.hxx,.jl,.f90,.f95,.f03,.f,.for,.r,.R,.m,.tex,.latex,.diff,.patch,.java,.go,.rb,.swift,.html,.htm,.css,.xml,.yaml,.yml,.toml,.lua,.txt,.rst,.adoc" /></label>
       <button id="loadGitDiffBtn" type="button" title="Load the current git diff from the Studio context into the editor.">Load git diff</button>
       <button id="getEditorBtn" type="button" title="Load the current terminal editor draft into Studio.">Load from pi editor</button>
@@ -8937,6 +9498,8 @@ ${cssVarsBlock}
       </div>
     </section>
 
+    <div id="paneResizeHandle" class="pane-resize-handle" role="separator" aria-label="Resize editor and response panes" aria-orientation="vertical" tabindex="0" title="Drag to resize panes. Double-click or press Enter/Space to reset; drag very close to the middle to snap to 50/50."></div>
+
     <section id="rightPane">
       <div id="rightSectionHeader" class="section-header">
         <div class="section-header-main">
@@ -9045,6 +9608,14 @@ ${cssVarsBlock}
             <div><dt>Tab / Shift+Tab</dt><dd>Indent or unindent selected editor text</dd></div>
           </dl>
         </section>
+        <section class="shortcuts-group">
+          <h3>Response</h3>
+          <dl>
+            <div><dt>Alt/Option+←</dt><dd>Previous response when not editing text</dd></div>
+            <div><dt>Alt/Option+→</dt><dd>Next response when not editing text</dd></div>
+            <div><dt>Alt/Option+l</dt><dd>Latest response when not editing text</dd></div>
+          </dl>
+        </section>
         <section class="shortcuts-group">
           <h3>REPL</h3>
           <dl>
@@ -9998,7 +10569,11 @@ export default function (pi: ExtensionAPI) {
 				}
 				lastSpecificToolActivityLabel = baseLabel;
 			} else {
-				nextLabel = baseLabel;
+				// Generic shell/tool labels such as "Running git command" are often
+				// stale or too broad once the model has moved on. Keep the precise
+				// Working trace entry, but do not promote generic labels into the
+				// live Studio/terminal status line.
+				nextLabel = null;
 			}
 		} else {
 			nextLabel = null;
@@ -10759,7 +11334,7 @@ export default function (pi: ExtensionAPI) {
 				sendToClient(client, { type: "error", requestId: msg.requestId, message: "Invalid request ID." });
 				return;
 			}
-			const started = startStudioReplSession(msg.runtime, studioCwd, { newSession: msg.newSession });
+			const started = startStudioReplSession(msg.runtime, studioCwd, { newSession: msg.newSession, command: msg.command });
 			if (!started.ok) {
 				sendReplStateToClient(client, { requestId: msg.requestId, replError: started.message });
 				sendToClient(client, { type: "error", requestId: msg.requestId, message: started.message });
@@ -10972,6 +11547,7 @@ export default function (pi: ExtensionAPI) {
 				label: result.label,
 				source: "file",
 				path: result.resolvedPath,
+				resourceDir: dirname(result.resolvedPath),
 			};
 
 			sendToClient(client, {
@@ -10979,6 +11555,7 @@ export default function (pi: ExtensionAPI) {
 				requestId: msg.requestId,
 				path: result.resolvedPath,
 				label: result.label,
+				resourceDir: dirname(result.resolvedPath),
 				message: `Saved editor text to ${result.label}`,
 			});
 			return;
@@ -11058,6 +11635,7 @@ export default function (pi: ExtensionAPI) {
 				label: refreshed.label,
 				source: "file",
 				path: refreshed.resolvedPath,
+				resourceDir: dirname(refreshed.resolvedPath),
 			};
 
 			broadcast({
@@ -12091,6 +12669,40 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
+		if (requestUrl.pathname === "/local-preview-link") {
+			const token = requestUrl.searchParams.get("token") ?? "";
+			if (token !== serverState.token) {
+				respondJson(res, 403, { ok: false, error: "Invalid or expired studio token. Re-run /studio." });
+				return;
+			}
+
+			try {
+				const resource = resolveStudioLocalPreviewResourcePath(
+					requestUrl.searchParams.get("path") ?? "",
+					requestUrl.searchParams.get("sourcePath") ?? undefined,
+					requestUrl.searchParams.get("resourceDir") ?? undefined,
+					studioCwd,
+				);
+				respondLocalPreviewLinkJson(req, res, requestUrl, resource, serverState);
+			} catch (error) {
+				respondJson(res, 404, { ok: false, error: `Local resource unavailable: ${error instanceof Error ? error.message : String(error)}` });
+			}
+			return;
+		}
+
+		if (requestUrl.pathname === "/reveal-local-resource") {
+			const token = requestUrl.searchParams.get("token") ?? "";
+			if (token !== serverState.token) {
+				respondJson(res, 403, { ok: false, error: "Invalid or expired studio token. Re-run /studio." });
+				return;
+			}
+
+			void handleRevealLocalPreviewResourceRequest(req, res, studioCwd).catch((error) => {
+				respondJson(res, 500, { ok: false, error: `Reveal failed: ${error instanceof Error ? error.message : String(error)}` });
+			});
+			return;
+		}
+
 		if (requestUrl.pathname === "/pdf-resource") {
 			const token = requestUrl.searchParams.get("token") ?? "";
 			if (token !== serverState.token) {
@@ -12112,6 +12724,27 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
+		if (requestUrl.pathname === "/html-preview-resource") {
+			const token = requestUrl.searchParams.get("token") ?? "";
+			if (token !== serverState.token) {
+				respondJson(res, 403, { ok: false, error: "Invalid or expired studio token. Re-run /studio." });
+				return;
+			}
+
+			try {
+				const resource = resolveStudioHtmlPreviewResourcePath(
+					requestUrl.searchParams.get("path") ?? "",
+					requestUrl.searchParams.get("sourcePath") ?? undefined,
+					requestUrl.searchParams.get("resourceDir") ?? undefined,
+					studioCwd,
+				);
+				respondHtmlPreviewResourceJson(req, res, resource.filePath, resource.mimeType);
+			} catch (error) {
+				respondJson(res, 404, { ok: false, error: `HTML preview resource unavailable: ${error instanceof Error ? error.message : String(error)}` });
+			}
+			return;
+		}
+
 		if (requestUrl.pathname !== "/") {
 			respondText(res, 404, "Not found");
 			return;
@@ -12731,6 +13364,7 @@ export default function (pi: ExtensionAPI) {
 			label: file.label,
 			source: "file",
 			path: file.resolvedPath,
+			resourceDir: dirname(file.resolvedPath),
 		};
 	};