pi-studio 0.9.56 → 0.9.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.9.56",
+  "version": "0.9.57",
   "description": "Two-pane browser workspace for pi with prompt/response editing, annotations, critiques, active quiz, prompt/response history, live previews, and tmux-backed REPL/literate REPL workflows",
   "type": "module",
   "license": "MIT",

package/shared/REPL_SESSION_RECORD_PROTOCOL.md

@@ -57,7 +57,7 @@ Each entry has a stable `id`, optional `requestId`, timestamps, session/runtime
 
 Record updates take a short cross-process directory lock, read the latest snapshot, upsert by stable entry ID, and replace the snapshot atomically. A stale lock can be recovered. The implementation retains at most 300 entries, bounds individual prose/code/output fields, and caps the serialized record at 16 MiB by dropping the oldest entries first.
 
-Attribution-sensitive sends also take a separate cross-client send lease. A compatible client holds it from the pre-send pane capture through the completion/output capture. The lease has an owner token, heartbeat, bounded wait, and stale recovery. If a caller times out or aborts after submission, the live client continues heartbeating the lease until the runtime completion marker appears or that exact tmux session lifetime ends; a caller timeout does not imply that submitted code stopped. This prevents `pi-repl` and `pi-studio` from concurrently claiming each other's output; it cannot prevent a person typing directly into an attached tmux pane.
+Attribution-sensitive sends also take a separate cross-client send lease. A compatible client holds it from the pre-send pane capture through the completion/output capture. The lease has an owner token, heartbeat, bounded wait, and stale recovery. If a caller times out or aborts after submission, the live client continues heartbeating the lease until the runtime completion signal appears or that exact tmux session lifetime ends; a caller timeout does not imply that submitted code stopped. This prevents `pi-repl` and `pi-studio` from concurrently claiming each other's output; it cannot prevent a person typing directly into an attached tmux pane.
 
 ## Clean record versus raw history
 
@@ -65,6 +65,29 @@ The clean record includes submissions whose semantic boundaries are known to a c
 
 Canonical Markdown exports identify origin, mode, status, runtime, and timestamp and include this direct-input limitation.
 
+## Optional raw-history display and alignment anchors
+
+Compatible clients may add protocol-independent submission displays to the raw pane while retaining the same clean record. Display version 1 derives a non-secret 12-hex-character anchor as the first 12 characters of SHA-256 over `pi-repl-submission-display-v1`, a NUL byte, and the stable clean-record entry ID. The entry ID itself is not written to the pane.
+
+**Off** is the default and writes no optional display or alignment anchors. Opt-in **Summary** shows a short submission in full, truncating after 6 source lines or 600 source characters. **Full** raises those bounds to 40 lines or 4,000 characters and warns that source becomes part of persistent raw terminal history. Display text normalizes newlines and tabs, removes trailing display whitespace, and escapes terminal, line-separator, and bidirectional control characters.
+
+```text
+── pi-repl · a1b2c3d4e5f6 · 2 lines ──
+│ x = 1
+│ x + 1
+── output ──
+2
+── done · a1b2c3d4e5f6 ──
+```
+
+The compact submitted and completion anchors remain in raw tmux history for human readability and deterministic future alignment. A plain unanchored `── output ──` divider separates the source preview from runtime output without repeating the ID or other metadata. Clients remove the exact request-specific header, source preview, divider, and footer from captured tool output and clean-record output. These markers are presentation metadata, not clean-record authority: missing, malformed, duplicated, or user-produced marker-like text must never cause inferred raw activity to be promoted silently into protocol-v1 entries.
+
+## Runtime control files (outside protocol v1)
+
+Runtime-specific source wrappers and completion files are client implementation details, not shared-record state or authority. Compatible clients use compact request-unique names under a current-user-owned mode-`0700` `/tmp/pi-rc-<user-key>` root on POSIX systems, with mode-`0600` source files created exclusively. This avoids both verbose per-session paths and fixed global filenames that can collide across clients, processes, tmux servers, or runtimes.
+
+A client removes the source and completion files after output capture. If a send times out or is aborted after submission, the same watcher that retains any shared lease also retains those files until the wrapper signals completion or the exact session lifetime disappears. Orphans left by a process crash are pruned after 24 hours on a later send. These files remain protocol-independent: their names and presence never turn raw pane activity into a clean-record entry.
+
 ## Compatibility
 
 A client that sees an unsupported version leaves it untouched. Existing tmux sessions gain v1 metadata lazily when inspected or used. Studio may import legacy browser-local entries as `pi-studio` entries using their stable IDs, making retries idempotent.

package/shared/repl-control-files.js

@@ -0,0 +1,158 @@
+import { randomBytes } from "node:crypto";
+import {
+	chmodSync,
+	closeSync,
+	existsSync,
+	fchmodSync,
+	lstatSync,
+	mkdirSync,
+	openSync,
+	readdirSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+const REPL_CONTROL_TOKEN_BYTES = 8;
+const REPL_CONTROL_STALE_MS = 24 * 60 * 60 * 1_000;
+const prunedRoots = new Set();
+
+function currentUid() {
+	return typeof process.getuid === "function" ? process.getuid() : null;
+}
+
+export function getPrivateReplControlRoot() {
+	const uid = currentUid();
+	const base = process.platform === "win32" ? tmpdir() : "/tmp";
+	const userKey = uid === null ? "user" : uid.toString(36);
+	return join(base, `pi-rc-${userKey}`);
+}
+
+function assertPrivateReplControlRoot(root) {
+	const stats = lstatSync(root);
+	if (!stats.isDirectory() || stats.isSymbolicLink()) {
+		throw new Error(`REPL control root is not a real directory: ${root}`);
+	}
+	const uid = currentUid();
+	if (uid !== null && stats.uid !== uid) {
+		throw new Error(`REPL control root is not owned by the current user: ${root}`);
+	}
+	if (process.platform !== "win32" && (stats.mode & 0o777) !== 0o700) {
+		throw new Error(`REPL control root must have mode 0700: ${root}`);
+	}
+}
+
+function pruneStaleReplControlFiles(root, now = Date.now()) {
+	if (prunedRoots.has(root)) return;
+	prunedRoots.add(root);
+	let entries = [];
+	try {
+		entries = readdirSync(root);
+	} catch {
+		return;
+	}
+	const uid = currentUid();
+	for (const entry of entries) {
+		if (!/^[a-f0-9]{16}\.(?:[A-Za-z0-9]{1,8}|done)$/.test(entry)) continue;
+		const file = join(root, entry);
+		try {
+			const stats = lstatSync(file);
+			if (!stats.isFile() || stats.isSymbolicLink()) continue;
+			if (uid !== null && stats.uid !== uid) continue;
+			if (now - stats.mtimeMs < REPL_CONTROL_STALE_MS) continue;
+			unlinkSync(file);
+		} catch {
+			// Another process may have removed the same stale file.
+		}
+	}
+}
+
+export function ensurePrivateReplControlRoot(root = getPrivateReplControlRoot()) {
+	let created = false;
+	try {
+		mkdirSync(root, { mode: 0o700 });
+		created = true;
+	} catch (error) {
+		if (!error || typeof error !== "object" || error.code !== "EEXIST") throw error;
+	}
+	if (created && process.platform !== "win32") chmodSync(root, 0o700);
+	assertPrivateReplControlRoot(root);
+	pruneStaleReplControlFiles(root);
+	return root;
+}
+
+function normalizeExtension(extension) {
+	const normalized = String(extension || "").replace(/^\.+/, "");
+	if (!/^[A-Za-z0-9]{1,8}$/.test(normalized)) {
+		throw new Error(`Invalid REPL control-file extension: ${extension}`);
+	}
+	return normalized;
+}
+
+/**
+ * Create and populate one private, collision-resistant REPL control file.
+ * The builder receives the final paths so it can embed the matching done-file
+ * path in the runtime-specific wrapper.
+ */
+export function createPrivateReplControlFiles(options) {
+	const extension = normalizeExtension(options?.extension);
+	const root = ensurePrivateReplControlRoot(options?.root || getPrivateReplControlRoot());
+	if (typeof options?.buildSource !== "function") {
+		throw new Error("REPL control-file source builder is required.");
+	}
+
+	for (let attempt = 0; attempt < 20; attempt += 1) {
+		const token = randomBytes(REPL_CONTROL_TOKEN_BYTES).toString("hex");
+		const paths = {
+			dir: root,
+			sourceFile: join(root, `${token}.${extension}`),
+			doneFile: join(root, `${token}.done`),
+		};
+		if (existsSync(paths.doneFile)) continue;
+
+		let descriptor;
+		try {
+			descriptor = openSync(paths.sourceFile, "wx", 0o600);
+		} catch (error) {
+			if (error && typeof error === "object" && error.code === "EEXIST") continue;
+			throw error;
+		}
+
+		let complete = false;
+		try {
+			const source = String(options.buildSource(paths));
+			writeFileSync(descriptor, source, "utf8");
+			if (process.platform !== "win32") fchmodSync(descriptor, 0o600);
+			complete = true;
+			return paths;
+		} finally {
+			closeSync(descriptor);
+			if (!complete) {
+				try {
+					unlinkSync(paths.sourceFile);
+				} catch {
+					// Preserve the source-builder error.
+				}
+			}
+		}
+	}
+	throw new Error("Could not allocate a unique REPL control file.");
+}
+
+export function cleanupPrivateReplControlFiles(paths) {
+	if (!paths || typeof paths !== "object") return;
+	const root = String(paths.dir || "");
+	const sourceFile = String(paths.sourceFile || "");
+	const doneFile = String(paths.doneFile || "");
+	const sourceName = basename(sourceFile);
+	const token = sourceName.match(/^([a-f0-9]{16})\.[A-Za-z0-9]{1,8}$/)?.[1];
+	if (!token || dirname(sourceFile) !== root || dirname(doneFile) !== root || basename(doneFile) !== `${token}.done`) return;
+	for (const file of [sourceFile, doneFile]) {
+		try {
+			unlinkSync(file);
+		} catch {
+			// Cleanup is idempotent and best effort.
+		}
+	}
+}

package/shared/repl-submission-display.js

@@ -0,0 +1,227 @@
+import { createHash } from "node:crypto";
+
+export const REPL_SUBMISSION_DISPLAY_VERSION = 1;
+export const DEFAULT_REPL_SUBMISSION_ECHO_MODE = "off";
+export const REPL_SUBMISSION_ECHO_MODES = Object.freeze(["off", "summary", "full"]);
+export const REPL_SUBMISSION_SUMMARY_MAX_CHARS = 600;
+export const REPL_SUBMISSION_SUMMARY_MAX_LINES = 6;
+export const REPL_SUBMISSION_FULL_MAX_CHARS = 4_000;
+export const REPL_SUBMISSION_FULL_MAX_LINES = 40;
+
+const UNSAFE_UNICODE_PATTERN = /[\u2028\u2029\u202a-\u202e\u2066-\u2069]/g;
+const OTHER_CONTROL_PATTERN = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g;
+const COMPACT_BEGIN_MARKER_PATTERN = /^── ([a-z0-9][a-z0-9-]{0,31}) · ([a-f0-9]{12}) · ([1-9]\d*) (line|lines) ──$/;
+const COMPACT_OUTPUT_MARKER = "── output ──";
+const COMPACT_END_MARKER_PATTERN = /^── done · ([a-f0-9]{12}) ──$/;
+const LEGACY_MARKER_PATTERN = /^── ([a-z0-9][a-z0-9-]{0,31}) (submitted|output|complete)(?: · ([1-9]\d*) (line|lines))? · ([a-f0-9]{12}) ──$/;
+
+export function normalizeReplSubmissionEchoMode(value, fallback = DEFAULT_REPL_SUBMISSION_ECHO_MODE) {
+	const normalizedFallback = REPL_SUBMISSION_ECHO_MODES.includes(String(fallback || "").trim().toLowerCase())
+		? String(fallback).trim().toLowerCase()
+		: DEFAULT_REPL_SUBMISSION_ECHO_MODE;
+	const normalized = String(value || "").trim().toLowerCase();
+	return REPL_SUBMISSION_ECHO_MODES.includes(normalized) ? normalized : normalizedFallback;
+}
+
+function escapeCodePoint(char) {
+	const codePoint = char.codePointAt(0) ?? 0;
+	return codePoint <= 0xff
+		? `\\x${codePoint.toString(16).padStart(2, "0")}`
+		: `\\u{${codePoint.toString(16)}}`;
+}
+
+export function sanitizeReplSubmissionDisplayText(value) {
+	return String(value || "")
+		.replace(/\r\n?/g, "\n")
+		.replace(/\t/g, "    ")
+		.replace(OTHER_CONTROL_PATTERN, escapeCodePoint)
+		.replace(UNSAFE_UNICODE_PATTERN, escapeCodePoint);
+}
+
+function truncateCodePoints(value, maxChars) {
+	const chars = Array.from(String(value || ""));
+	if (chars.length <= maxChars) return { text: chars.join(""), truncated: false };
+	return { text: `${chars.slice(0, Math.max(0, maxChars - 1)).join("")}…`, truncated: true };
+}
+
+function normalizeDisplayCode(code) {
+	const sanitized = sanitizeReplSubmissionDisplayText(code)
+		.split("\n")
+		.map((line) => line.replace(/ +$/g, ""))
+		.join("\n")
+		.replace(/\n+$/, "");
+	return sanitized || "(empty submission)";
+}
+
+function formatPreviewLine(line) {
+	return line ? `│ ${line}` : "│";
+}
+
+function buildBoundedPreviewLines(codeLines, maxLines, maxChars) {
+	const shown = [];
+	let usedChars = 0;
+	let truncated = false;
+	for (let index = 0; index < codeLines.length; index += 1) {
+		if (shown.length >= maxLines) {
+			truncated = true;
+			break;
+		}
+		const line = codeLines[index];
+		const remaining = maxChars - usedChars;
+		if (remaining <= 0) {
+			truncated = true;
+			break;
+		}
+		const clipped = truncateCodePoints(line, remaining);
+		shown.push(formatPreviewLine(clipped.text));
+		usedChars += Array.from(clipped.text).length + 1;
+		if (clipped.truncated) {
+			truncated = true;
+			break;
+		}
+	}
+	if (shown.length < codeLines.length) truncated = true;
+	if (truncated) shown.push(`│ … preview truncated; ${codeLines.length} ${codeLines.length === 1 ? "line" : "lines"} total`);
+	return shown;
+}
+
+export function createReplSubmissionDisplay(details = {}) {
+	const mode = normalizeReplSubmissionEchoMode(details.mode);
+	const origin = String(details.origin || "pi")
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 32) || "pi";
+	const entryId = String(details.entryId || "");
+	const anchorId = createHash("sha256")
+		.update(`pi-repl-submission-display-v${REPL_SUBMISSION_DISPLAY_VERSION}\0${entryId}`, "utf8")
+		.digest("hex")
+		.slice(0, 12);
+	const displayCode = normalizeDisplayCode(details.code);
+	const codeLines = displayCode.split("\n");
+	const lineLabel = `${codeLines.length} ${codeLines.length === 1 ? "line" : "lines"}`;
+	const beginMarker = `── ${origin} · ${anchorId} · ${lineLabel} ──`;
+	const outputMarker = COMPACT_OUTPUT_MARKER;
+	const endMarker = `── done · ${anchorId} ──`;
+	const enabled = mode !== "off";
+	const previewLines = !enabled
+		? []
+		: mode === "full"
+			? buildBoundedPreviewLines(codeLines, REPL_SUBMISSION_FULL_MAX_LINES, REPL_SUBMISSION_FULL_MAX_CHARS)
+			: buildBoundedPreviewLines(codeLines, REPL_SUBMISSION_SUMMARY_MAX_LINES, REPL_SUBMISSION_SUMMARY_MAX_CHARS);
+	return {
+		version: REPL_SUBMISSION_DISPLAY_VERSION,
+		mode,
+		enabled,
+		origin,
+		entryId,
+		anchorId,
+		beginMarker,
+		outputMarker,
+		endMarker,
+		previewLines,
+		prefixLines: enabled ? [beginMarker, ...previewLines, outputMarker] : [],
+	};
+}
+
+function parseLineCount(countText, countLabel) {
+	const lineCount = Number(countText);
+	if (!Number.isSafeInteger(lineCount) || lineCount < 1) return null;
+	if ((lineCount === 1) !== (countLabel === "line")) return null;
+	return lineCount;
+}
+
+export function parseReplSubmissionDisplayMarker(line) {
+	const normalized = String(line || "").replace(/\r$/, "");
+	const compactBegin = normalized.match(COMPACT_BEGIN_MARKER_PATTERN);
+	if (compactBegin) {
+		const [, origin, anchorId, countText, countLabel] = compactBegin;
+		const lineCount = parseLineCount(countText, countLabel);
+		return lineCount === null
+			? null
+			: { version: REPL_SUBMISSION_DISPLAY_VERSION, origin, phase: "submitted", anchorId, lineCount };
+	}
+	if (normalized === COMPACT_OUTPUT_MARKER) {
+		return { version: REPL_SUBMISSION_DISPLAY_VERSION, phase: "output" };
+	}
+	const compactEnd = normalized.match(COMPACT_END_MARKER_PATTERN);
+	if (compactEnd) {
+		return { version: REPL_SUBMISSION_DISPLAY_VERSION, phase: "complete", anchorId: compactEnd[1] };
+	}
+
+	// Accept the earlier three-marker development format so raw histories made
+	// while testing it remain interpretable; new displays do not emit this form.
+	const legacy = normalized.match(LEGACY_MARKER_PATTERN);
+	if (!legacy) return null;
+	const [, origin, phase, countText, countLabel, anchorId] = legacy;
+	if (phase === "submitted") {
+		if (!countText) return null;
+		const lineCount = parseLineCount(countText, countLabel);
+		return lineCount === null
+			? null
+			: { version: REPL_SUBMISSION_DISPLAY_VERSION, origin, phase, anchorId, lineCount, legacy: true };
+	}
+	if (countText) return null;
+	return { version: REPL_SUBMISSION_DISPLAY_VERSION, origin, phase, anchorId, legacy: true };
+}
+
+function consumeExactDisplayLine(value, offset, line) {
+	if (!value.startsWith(line, offset)) return null;
+	let end = offset + line.length;
+	while (end < value.length && (value[end] === " " || value[end] === "\t")) end += 1;
+	if (end < value.length && value[end] !== "\n") return null;
+	return value[end] === "\n" ? end + 1 : end;
+}
+
+function findExactDisplayLine(value, line, useLast = false) {
+	let index = useLast ? value.lastIndexOf(line) : value.indexOf(line);
+	while (index >= 0) {
+		const startsLine = index === 0 || value[index - 1] === "\n";
+		const end = consumeExactDisplayLine(value, index, line);
+		if (startsLine && end !== null) return { index, end };
+		if (useLast) {
+			if (index === 0) break;
+			index = value.lastIndexOf(line, index - 1);
+		} else {
+			index = value.indexOf(line, index + line.length);
+		}
+	}
+	return null;
+}
+
+function removeMarkerLine(value, marker, useLast = false) {
+	const found = findExactDisplayLine(value, marker, useLast);
+	return found ? value.slice(0, found.index) + value.slice(found.end) : value;
+}
+
+export function stripReplSubmissionDisplay(output, display) {
+	let value = String(output || "").replace(/\r\n?/g, "\n");
+	if (!display || display.enabled !== true) return value;
+	const begin = findExactDisplayLine(value, display.beginMarker);
+	if (begin) {
+		const beginIndex = begin.index;
+		const afterBegin = value.slice(begin.end);
+		const outputDivider = display.outputMarker
+			? findExactDisplayLine(afterBegin, display.outputMarker)
+			: null;
+		if (outputDivider) {
+			// The plain divider is an unambiguous boundary because it is emitted
+			// before user code runs. Removing through it is resilient to terminal
+			// wrapping or whitespace changes within the displayed source preview.
+			const suffixStart = begin.end + outputDivider.end;
+			value = value.slice(0, beginIndex) + value.slice(suffixStart);
+		} else {
+			// If the runtime disappears mid-prefix, remove only contiguous exact
+			// request lines and preserve any different error text after them.
+			let suffixStart = beginIndex;
+			for (const line of display.prefixLines) {
+				const next = consumeExactDisplayLine(value, suffixStart, line);
+				if (next === null) break;
+				suffixStart = next;
+			}
+			value = value.slice(0, beginIndex) + value.slice(suffixStart);
+		}
+	}
+	return removeMarkerLine(value, display.endMarker, true);
+}