pi-repl-py 0.1.0 → 0.2.0

package/src/engine/session.ts

@@ -0,0 +1,149 @@
+// --- Jupyter messaging over ZMTP: [identities] <IDS|MSG> [sig, h, p, m, c] ---
+// ids are empty for a client's own channels (kernel ROUTER strips them);
+// sig = hex(HMAC-SHA256(key, h||p||m||c)) over the exact bytes; key from the
+// connection file. Checked against jupyter_client's session.py.
+
+import { createHmac, randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+/** The kernel's connection file: ip/ports/key, written by ipykernel at boot. */
+export interface ConnectionFile {
+	ip: string;
+	transport: "tcp" | "ipc";
+	shell_port: number;
+	iopub_port: number;
+	stdin_port: number;
+	control_port: number;
+	hb_port: number;
+	key: string;
+	signature_scheme: string;
+	kernel_name?: string;
+}
+
+export function readConnectionFile(path: string): ConnectionFile {
+	return JSON.parse(readFileSync(path, "utf8")) as ConnectionFile;
+}
+
+const DELIM = Buffer.from("<IDS|MSG>");
+/** The protocol version ipykernel 7 advertises; we send the same on our own headers. */
+const PROTOCOL_VERSION = "5.3";
+
+export interface JupyterHeader {
+	msg_id: string;
+	msg_type: string;
+	username: string;
+	session: string;
+	date: string;
+	version: string;
+}
+
+/** A parsed inbound message: JSON parts + whether the signature verified. */
+export interface ParsedMessage {
+	msg_id: string;
+	msg_type: string;
+	header: JupyterHeader;
+	parent: Record<string, unknown>;
+	metadata: Record<string, unknown>;
+	content: Record<string, unknown>;
+	signatureOk: boolean;
+}
+
+function pack(obj: unknown): Buffer {
+	return Buffer.from(JSON.stringify(obj));
+}
+
+/** One client-side session: mints ids, signs and frames outbound messages. */
+export class JupyterSession {
+	readonly sessionId: string;
+	readonly username: string;
+	private counter = 0;
+	private readonly key: Buffer;
+
+	constructor(opts: { key: string; sessionId?: string; username?: string }) {
+		this.key = Buffer.from(opts.key, "utf8");
+		this.sessionId = opts.sessionId ?? randomUUID();
+		this.username = opts.username ?? "pi-repl";
+	}
+
+	nextMsgId(): string {
+		// --- ids only need uniqueness; a monotone counter over a session id keeps them short ---
+		return `${this.sessionId}_${process.pid}_${this.counter++}`;
+	}
+
+	private sign(parts: Buffer[]): Buffer {
+		if (this.key.length === 0) return Buffer.alloc(0);
+		const hmac = createHmac("sha256", this.key);
+		for (const part of parts) hmac.update(part);
+		return Buffer.from(hmac.digest("hex"), "ascii");
+	}
+
+	/** Build the wire frames for an outbound message: [DELIM, sig, h, p, m, c]. */
+	buildFrames(
+		msgType: string,
+		content: Record<string, unknown>,
+		parent?: JupyterHeader | null,
+		msgId?: string,
+	): Buffer[] {
+		const header: JupyterHeader = {
+			msg_id: msgId ?? this.nextMsgId(),
+			msg_type: msgType,
+			username: this.username,
+			session: this.sessionId,
+			date: new Date().toISOString(),
+			version: PROTOCOL_VERSION,
+		};
+		const h = pack(header);
+		const p = pack(parent ?? {});
+		const m = pack({});
+		const c = pack(content);
+		const signature = this.sign([h, p, m, c]);
+		return [DELIM, signature, h, p, m, c];
+	}
+
+	/** Parse an inbound multipart message (identities stripped by ZMTP); null if malformed. */
+	parseMessage(frames: Buffer[]): ParsedMessage | null {
+		// --- indexOf uses ===; frames are distinct Buffers, so match by value ---
+		const delimIdx = frames.findIndex((f) => f.equals(DELIM));
+		if (delimIdx < 0) return null;
+		const rest = frames.slice(delimIdx + 1);
+		if (rest.length < 5) return null;
+		const [signature, h, p, m, c] = rest;
+		const expected = this.sign([h, p, m, c]);
+		const signatureOk = this.key.length === 0 || signature.equals(expected);
+		try {
+			const header = JSON.parse(h.toString("utf8")) as JupyterHeader;
+			const content = JSON.parse(c.toString("utf8")) as Record<string, unknown>;
+			const metadata = JSON.parse(m.toString("utf8")) as Record<string, unknown>;
+			const parent = JSON.parse(p.toString("utf8")) as Record<string, unknown>;
+			return { msg_id: header.msg_id, msg_type: header.msg_type, header, parent, metadata, content, signatureOk };
+		} catch {
+			return null;
+		}
+	}
+}
+
+export function executeRequest(code: string, silent: boolean): Record<string, unknown> {
+	return {
+		code,
+		silent,
+		store_history: !silent,
+		user_expressions: {},
+		allow_stdin: false,
+		stop_on_error: true,
+	};
+}
+
+/** A payload the kernel publishes back to us with a private MIME key. */
+export const SNAPSHOT_MIME = "application/vnd.pi-repl.snapshot+json";
+export const RESTORE_MIME = "application/vnd.pi-repl.restore+json";
+export const NAMES_MIME = "application/vnd.pi-repl.names+json";
+
+/** Read a private-MIME payload out of an execute_result/display_data content. */
+export function readPayload(content: Record<string, unknown>, mime: string): string | null {
+	const data = content.data;
+	if (data && typeof data === "object") {
+		const value = (data as Record<string, unknown>)[mime];
+		if (typeof value === "string") return value;
+	}
+	return null;
+}

package/src/engine/zmtp.ts

@@ -0,0 +1,251 @@
+// --- ZMTP 3.0 wire protocol, by hand (bun can't load libzmq's bindings). ---
+// DEALER for shell/control, SUB for iopub; greeting 0xff..0x7f + READY each side.
+
+import { connect, type Socket } from "node:net";
+
+const GREETING_SIGNATURE = Buffer.from([0xff, 0, 0, 0, 0, 0, 0, 0, 0x01, 0x7f]);
+const NULL_MECHANISM = Buffer.concat([Buffer.from("NULL"), Buffer.alloc(16)]);
+
+/** The client (non-server) half of the 64-byte ZMTP 3.0 greeting. */
+function buildGreeting(): Buffer {
+	return Buffer.concat([
+		GREETING_SIGNATURE,
+		Buffer.from([3, 0]), // version 3.0
+		NULL_MECHANISM,
+		Buffer.from([0]), // as-server: we are the connecting socket
+		Buffer.alloc(31), // filler
+	]);
+}
+
+const FRAME_MORE = 0x01;
+const FRAME_LONG = 0x02;
+const GREETING_LENGTH = 64;
+
+/** Serialize one ZMTP frame: flags byte, short/8-byte length, body. */
+export function encodeFrame(body: Uint8Array, more: boolean): Buffer {
+	const flags = more ? FRAME_MORE : 0;
+	if (body.length <= 255) {
+		const out = Buffer.allocUnsafe(2 + body.length);
+		out[0] = flags;
+		out[1] = body.length;
+		Buffer.from(body).copy(out, 2);
+		return out;
+	}
+	const out = Buffer.allocUnsafe(9 + body.length);
+	out[0] = flags | FRAME_LONG;
+	out.writeUInt32BE(0, 1); // length is 64-bit; we never exceed 2^32
+	out.writeUInt32BE(body.length, 5);
+	Buffer.from(body).copy(out, 9);
+	return out;
+}
+/** Incremental parser: `current` persists across feed() and accumulation is once-per-frame (avoid O(n²)). */
+export class ZmtpFrameParser {
+	private chunks: Buffer[] = [];
+	private total = 0;
+	private current: Buffer[] = []; // frames of the in-progress message
+
+	/** @returns one or more complete messages consumed from `chunk`. */
+	feed(chunk: Uint8Array): Buffer[][] {
+		if (chunk.length > 0) {
+			this.chunks.push(Buffer.from(chunk));
+			this.total += chunk.length;
+		}
+		const messages: Buffer[][] = [];
+		for (;;) {
+			if (this.total < 1) break;
+			const flags = this.peekBytes(1)[0];
+			const long = (flags & FRAME_LONG) !== 0;
+			const headerLen = long ? 9 : 2;
+			if (this.total < headerLen) break;
+			const header = this.peekBytes(headerLen);
+			const length = long ? header.readUInt32BE(5) : header[1];
+			if (this.total < headerLen + length) break;
+			const frame = this.take(headerLen + length);
+			// `take` returns a subarray (or a fresh concat for multi-chunk frames); never mutated, so no copy
+			this.current.push(frame.subarray(headerLen));
+			if ((flags & FRAME_MORE) === 0) {
+				messages.push(this.current);
+				this.current = [];
+			}
+		}
+		return messages;
+	}
+
+	/** The first `n` bytes across the chunk list, without consuming them. */
+	private peekBytes(n: number): Buffer {
+		if (this.chunks[0].length >= n) return this.chunks[0].subarray(0, n);
+		const parts: Buffer[] = [];
+		let need = n;
+		for (const c of this.chunks) {
+			const t = Math.min(c.length, need);
+			parts.push(c.subarray(0, t));
+			need -= t;
+			if (need === 0) break;
+		}
+		return Buffer.concat(parts);
+	}
+
+	/** Consume `n` bytes from the front of the chunk list. */
+	private take(n: number): Buffer {
+		const first = this.chunks[0];
+		if (first.length >= n) {
+			const out = first.subarray(0, n);
+			if (first.length === n) this.chunks.shift();
+			else this.chunks[0] = first.subarray(n);
+			this.total -= n;
+			return out;
+		}
+		const parts: Buffer[] = [];
+		let need = n;
+		for (const c of this.chunks) {
+			const t = Math.min(c.length, need);
+			parts.push(c.subarray(0, t));
+			need -= t;
+			if (need === 0) break;
+		}
+		let left = n;
+		while (left > 0) {
+			const c = this.chunks[0];
+			if (c.length <= left) {
+				this.chunks.shift();
+				left -= c.length;
+			} else {
+				this.chunks[0] = c.subarray(left);
+				left = 0;
+			}
+		}
+		this.total -= n;
+		return Buffer.concat(parts);
+	}
+}
+
+/** Socket-type string carried in the READY metadata (ZMTP "Socket-Type"). */
+export type ZmtpSocketType = "DEALER" | "SUB";
+
+interface ReadReady {
+	resolve(): void;
+	reject(error: Error): void;
+}
+
+/** One ZMTP client connection: TCP socket + greeting/READY handshake → complete multipart messages. */
+export class ZmtpSocket {
+	private socket?: Socket;
+	private parser = new ZmtpFrameParser();
+	private readyResolve?: ReadReady;
+	private closed = false;
+	onMessage?: (frames: Buffer[]) => void;
+	onClose?: () => void;
+
+	private constructor(socket: Socket) {
+		this.socket = socket;
+	}
+
+	/** Connect to `host:port` and complete the ZMTP handshake for `socketType`. */
+	static connect(opts: { host: string; port: number; socketType: ZmtpSocketType }): Promise<ZmtpSocket> {
+		const socket = connect({ host: opts.host, port: opts.port });
+		const z = new ZmtpSocket(socket);
+		// --- the peer's 64-byte greeting is not frame-formatted; collect it before the parser sees bytes ---
+		let greeting = Buffer.alloc(0);
+
+		socket.on("data", (chunk) => {
+			if (greeting.length < GREETING_LENGTH) {
+				const take = Math.min(chunk.length, GREETING_LENGTH - greeting.length);
+				greeting = Buffer.concat([greeting, chunk.subarray(0, take)]);
+				chunk = chunk.subarray(take);
+				if (greeting.length === GREETING_LENGTH) {
+					const sig = greeting.subarray(0, GREETING_SIGNATURE.length);
+					if (!sig.equals(GREETING_SIGNATURE)) {
+						z.failHandshake(
+							new Error(`ZMTP peer at ${opts.host}:${opts.port} sent an unexpected signature (${sig.toString("hex")})`),
+						);
+						return;
+					}
+					// --- greeting done: announce our socket type, then await the peer's ---
+					z.send([buildReadyMetadata(opts.socketType)]);
+				}
+			}
+			if (greeting.length === GREETING_LENGTH) {
+				for (const message of z.parser.feed(chunk)) {
+					const ready = z.readyResolve;
+					if (ready) {
+						// --- the first frame after the greeting is the peer's READY ---
+						z.readyResolve = undefined;
+						ready.resolve();
+						continue;
+					}
+					z.deliver(message);
+				}
+			}
+		});
+		socket.on("error", (error) => {
+			if (z.readyResolve) {
+				z.failHandshake(new Error(`ZMTP connection to ${opts.host}:${opts.port} failed: ${error.message}`));
+			}
+			// --- node always follows an error with 'close', which handles teardown ---
+		});
+		socket.on("close", () => {
+			if (z.closed) return;
+			z.closed = true;
+			if (z.readyResolve) {
+				z.failHandshake(new Error(`ZMTP connection to ${opts.host}:${opts.port} closed during handshake`));
+				return;
+			}
+			z.onClose?.();
+		});
+
+		return new Promise<ZmtpSocket>((resolve, reject) => {
+			z.readyResolve = { resolve: () => resolve(z), reject };
+			socket.on("connect", () => {
+				// --- full greeting in one write; the peer may split its reply ---
+				socket.write(buildGreeting());
+			});
+		});
+	}
+
+	private failHandshake(error: Error): void {
+		const ready = this.readyResolve;
+		if (!ready) return;
+		this.readyResolve = undefined;
+		ready.reject(error);
+		this.close();
+	}
+
+	private deliver(message: Buffer[]): void {
+		this.onMessage?.(message);
+	}
+
+	/** Send a multipart message (DEALER) or a single subscription frame (SUB). */
+	send(frames: Uint8Array[]): void {
+		for (let i = 0; i < frames.length; i++) {
+			this.socket?.write(encodeFrame(frames[i], i < frames.length - 1));
+		}
+	}
+
+	/** SUB only: subscribe to a topic prefix (empty = all traffic). */
+	subscribe(topic: Uint8Array): void {
+		this.send([Buffer.concat([Buffer.from([0x01]), topic])]);
+	}
+
+	close(): void {
+		this.closed = true;
+		this.socket?.destroy();
+	}
+
+	get isClosed(): boolean {
+		return this.closed;
+	}
+}
+
+/** The READY metadata frame: `\x05READY` + Socket-Type + Identity properties. */
+function buildReadyMetadata(socketType: ZmtpSocketType): Buffer {
+	const type = Buffer.from(socketType);
+	const body = Buffer.concat([
+		Buffer.from("\x05READY"),
+		Buffer.from("\x0bSocket-Type"),
+		Buffer.from([0, 0, 0, type.length]),
+		type,
+		Buffer.from("\x08Identity"),
+		Buffer.from([0, 0, 0, 0]), // empty identity: the routing id lives in ZMTP, not Jupyter
+	]);
+	return body;
+}

package/src/extension/helpers.ts

@@ -0,0 +1,46 @@
+/** Loads helpers from the ONE fixed dir; `helper_description` surfaces verbatim (no signature parsing). */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const DEFAULT_HELPERS_DIR = join(homedir(), ".pi", "agent", "pi-repl", "helpers");
+
+interface HelperEntry {
+	name: string;
+	description: string; // full helper_description body, "" if absent
+}
+
+/** Extract `helper_description = """..."""` (or `'''`) verbatim; no signature parsing. */
+function parseDescription(source: string): string {
+	const m = source.match(/helper_description\s*=\s*("""|''')([\s\S]*?)\1/);
+	return m ? m[2].trim() : "";
+}
+
+/** Load {name → entry} for each non-underscore *.py in the helpers dir. */
+function loadHelperEntries(dir?: string): HelperEntry[] {
+	const d = dir ?? DEFAULT_HELPERS_DIR;
+	if (!existsSync(d)) return [];
+	const entries: HelperEntry[] = [];
+	for (const file of readdirSync(d).sort()) {
+		if (!file.endsWith(".py")) continue;
+		const name = file.slice(0, -3);
+		if (!/^[A-Za-z_]\w*$/.test(name)) continue;
+		// --- underscore-prefixed files are neither loaded nor advertised ---
+		if (name.startsWith("_")) continue;
+		try {
+			const source = readFileSync(join(d, file), "utf8");
+			entries.push({ name, description: parseDescription(source) });
+		} catch {}
+	}
+	return entries;
+}
+
+/** The prompt-facing list, one bullet per loaded file (verbatim description, or an introspection pointer). */
+export function buildHelpersMap(dir?: string): string[] {
+	return loadHelperEntries(dir).map((t) =>
+		t.description
+			? `- ${t.description.replace(/\n/g, "\n  ")}`
+			: `- ${t.name} (no description — inspect it with print(${t.name}.__doc__))`,
+	);
+}

package/src/extension/preview/candidates.ts

@@ -0,0 +1,159 @@
+// --- candidates: the five detectors that name a cell's intent, plus generic scoring ---
+
+import { descriptor } from "./descriptor.js";
+import { maskSpan, scanTemplate, substituteVars } from "./scan.js";
+import { previewShellCommand, previewShellCommandScored, SHELL_SETUP_WORDS, shellWords } from "./shell.js";
+import { BACKTICK, type Candidate } from "./types.js";
+
+const SHELL_OPEN_PATTERN = new RegExp(`Bun\\s*\\.\\s*\\$\\s*(?:\\([^)]*\\)\\s*)?${BACKTICK}`, "g");
+
+export function shellCandidates(
+	source: string,
+	vars: ReadonlyMap<string, string>,
+): { candidates: Candidate[]; masked: string } {
+	const candidates: Candidate[] = [];
+	let masked = source;
+	SHELL_OPEN_PATTERN.lastIndex = 0;
+	let match = SHELL_OPEN_PATTERN.exec(masked);
+	while (match) {
+		const span = scanTemplate(masked, match.index + match[0].length - 1);
+		const command = previewShellCommandScored(substituteVars(span.body, vars));
+		// --- the command's own strength breaks ties; setup-only drops lower ---
+		if (command.text) {
+			const setupOnly = SHELL_SETUP_WORDS.has(shellWords(command.text)[0] ?? "");
+			const score = setupOnly ? 72 : 90 + Math.min(command.strength, 200) / 25;
+			candidates.push({ kind: "shell", text: command.text, score });
+		}
+		masked = maskSpan(masked, span);
+		SHELL_OPEN_PATTERN.lastIndex = span.end;
+		match = SHELL_OPEN_PATTERN.exec(masked);
+	}
+	return { candidates, masked };
+}
+
+const FILE_EFFECT_PATTERN =
+	/(?:Bun\.write|\b(?:fs|fsp|promises)\.(?:writeFileSync|writeFile|appendFileSync|appendFile|mkdirSync|mkdir|rmSync|rmdirSync|unlinkSync|unlink|renameSync|rename|copyFileSync|copyFile|cpSync|cp)|\b(?:writeFileSync|writeFile|appendFileSync|mkdirSync|rmSync|unlinkSync|renameSync|copyFileSync))\s*\(\s*([^,)\n]+)/g;
+
+const FILE_EFFECT_VERBS: ReadonlyArray<[string, string]> = [
+	["Bun.write", "write"],
+	["writeFileSync", "write"],
+	["writeFile", "write"],
+	["appendFileSync", "append"],
+	["appendFile", "append"],
+	["mkdirSync", "mkdir"],
+	["mkdir", "mkdir"],
+	["rmdirSync", "delete"],
+	["rmSync", "delete"],
+	["rm", "delete"],
+	["unlinkSync", "delete"],
+	["unlink", "delete"],
+	["renameSync", "rename"],
+	["rename", "rename"],
+	["copyFileSync", "copy"],
+	["copyFile", "copy"],
+	["cpSync", "copy"],
+	["cp", "copy"],
+];
+
+// --- resolve a quoted literal, a known const, or an interpolated template into a plain string ---
+function resolveArgText(arg: string, vars: ReadonlyMap<string, string>): string | undefined {
+	const trimmed = arg.trim();
+	const literalPattern = new RegExp(`^["'${BACKTICK}]([^"'${BACKTICK}]*)["'${BACKTICK}]$`);
+	const literal = trimmed.match(literalPattern);
+	if (literal?.[1]) return literal[1];
+	if (/^[A-Za-z_$][\w$]*$/.test(trimmed)) return vars.get(trimmed);
+	if (trimmed.startsWith(BACKTICK)) return substituteVars(trimmed.slice(1, -1), vars);
+	return undefined;
+}
+
+const FILE_READ_PATTERN = /Bun\.file\s*\(\s*([^,)\n]+?)\s*\)\s*\.\s*(?:text|json|arrayBuffer|bytes|stream)\s*\(/g;
+
+export function fileCandidates(source: string, vars: ReadonlyMap<string, string>): Candidate[] {
+	const candidates: Candidate[] = [];
+	for (const match of source.matchAll(FILE_EFFECT_PATTERN)) {
+		const call = match[0];
+		const verb = FILE_EFFECT_VERBS.find(([name]) => call.includes(name))?.[1];
+		if (!verb) continue;
+		const path = resolveArgText(match[1] ?? "", vars);
+		if (path) candidates.push({ kind: "ts", text: descriptor(`${verb} ${path}`), score: 95 });
+	}
+	for (const match of source.matchAll(FILE_READ_PATTERN)) {
+		const path = resolveArgText(match[1] ?? "", vars);
+		if (path) candidates.push({ kind: "ts", text: descriptor(`read ${path}`), score: 70 });
+	}
+	for (const match of source.matchAll(/\bfetch\s*\(\s*([^,)\n]+)/g)) {
+		const url = resolveArgText(match[1] ?? "", vars);
+		if (url) candidates.push({ kind: "ts", text: descriptor(`fetch ${url}`), score: 75 });
+	}
+	return candidates;
+}
+
+// --- per-tool: which arg names the target, the verb shown, and its scoring band ---
+const BRIDGED_TOOLS: Record<string, { arg: string; verb: string; score: number }> = {
+	read: { arg: "path", verb: "read", score: 70 },
+	bash: { arg: "command", verb: "", score: 88 },
+	edit: { arg: "path", verb: "edit", score: 95 },
+	write: { arg: "path", verb: "write", score: 95 },
+	grep: { arg: "pattern", verb: "grep", score: 68 },
+	find: { arg: "pattern", verb: "find", score: 68 },
+	ls: { arg: "path", verb: "ls", score: 68 },
+};
+
+export function bridgedToolCandidates(source: string, vars: ReadonlyMap<string, string>): Candidate[] {
+	const candidates: Candidate[] = [];
+	for (const match of source.matchAll(/\btools\.(\w+)\s*\(\s*\{([^}]*)\}/g)) {
+		const spec = BRIDGED_TOOLS[match[1] ?? ""];
+		if (!spec) continue;
+		const props = match[2] ?? "";
+		const argMatch = props.match(new RegExp(`${spec.arg}\\s*:\\s*([^,}]+)`));
+		const target = argMatch ? resolveArgText(argMatch[1] ?? "", vars) : undefined;
+		if (!target) continue;
+		// --- a bridged bash call is a command like any other ---
+		const text = spec.verb ? `${spec.verb} ${target}` : previewShellCommand(target) || target;
+		candidates.push({ kind: "ts", text: descriptor(text), score: spec.score });
+	}
+	return candidates;
+}
+
+const SKIP_LINE_PATTERN = /^(?:$|\/\/|\/\*|\*|import\s|export\s+(?:type\s|\{)|[})\];,]+$)/;
+const DEFINITION_PATTERN = /^(?:export\s+)?(?:async\s+)?(?:function\s|class\s|interface\s|type\s+\w+\s*=)/;
+const ARROW_DEFINITION_PATTERN = /^(?:const|let)\s+[A-Za-z_$][\w$]*\s*=\s*(?:async\s*)?\(?[^)=]*\)?\s*=>/;
+const CONTROL_PATTERN = /^(?:if|for|while|switch|try|do)\b/;
+const CALL_STATEMENT_PATTERN = /^(?:await\s+)?[A-Za-z_$][\w$.]*\s*\(/;
+const ASSIGNMENT_CALL_PATTERN = /^(?:const|let|var)\s+[^=]{1,60}=\s*(?:await\s+)?(?:new\s+)?[A-Za-z_$][\w$.]*\s*\(/;
+const LOW_SIGNAL_CALL_PATTERN =
+	/^(?:await\s+)?(?:console\.\w+|String|Number|Boolean|JSON\.stringify|JSON\.parse|structuredClone)\s*\(/;
+const LOW_SIGNAL_ASSIGNMENT_PATTERN =
+	/=\s*(?:await\s+)?(?:JSON\.parse|JSON\.stringify|String|Number|Boolean|Object\.keys|Object\.entries)\s*\(/;
+
+function consoleInnerCall(line: string): string | undefined {
+	const inner = line.match(/^console\.\w+\(\s*(.+)\)\s*;?\s*$/)?.[1]?.trim();
+	return inner && CALL_STATEMENT_PATTERN.test(inner) && !LOW_SIGNAL_CALL_PATTERN.test(inner) ? inner : undefined;
+}
+
+function genericLineScore(line: string): number {
+	if (SKIP_LINE_PATTERN.test(line)) return -1;
+	if (LOW_SIGNAL_ASSIGNMENT_PATTERN.test(line)) return 25;
+	if (consoleInnerCall(line)) return 55;
+	if (LOW_SIGNAL_CALL_PATTERN.test(line)) return 15;
+	if (DEFINITION_PATTERN.test(line) || ARROW_DEFINITION_PATTERN.test(line)) return 50;
+	if (CONTROL_PATTERN.test(line)) return 20;
+	if (/^(?:return|throw)\b/.test(line)) return 45;
+	if (ASSIGNMENT_CALL_PATTERN.test(line)) return 60;
+	if (CALL_STATEMENT_PATTERN.test(line)) return 65;
+	if (/^(?:const|let|var)\s/.test(line)) return 22;
+	return 30;
+}
+
+export function genericCandidates(masked: string): Candidate[] {
+	const candidates: Candidate[] = [];
+	for (const [index, rawLine] of masked.split("\n").entries()) {
+		const line = rawLine.trim();
+		const score = genericLineScore(line);
+		if (score < 0) continue;
+		const text = consoleInnerCall(line) ?? line;
+		// --- later lines win ties: cells read as setup-then-act, and the act is the story ---
+		candidates.push({ kind: "ts", text: descriptor(text), score: score + Math.min(index, 90) / 100 });
+	}
+	return candidates;
+}

package/src/extension/preview/descriptor.ts

@@ -0,0 +1,28 @@
+// --- descriptor: collapse the raw line into one readable, safe, width-capped string ---
+const DESCRIPTOR_MAX_WIDTH = 64;
+
+function collapseWhitespace(text: string): string {
+	return text.replace(/\s+/g, " ").trim();
+}
+
+function truncateDescriptor(text: string): string {
+	if (text.length <= DESCRIPTOR_MAX_WIDTH) return text;
+	return `${text.slice(0, DESCRIPTOR_MAX_WIDTH - 1).trimEnd()}…`;
+}
+
+// --- strip blobs, secrets, and sk- keys before a line reaches the header ---
+function redactNoise(text: string): string {
+	return text
+		.replace(/[A-Za-z0-9+/]{80,}={0,2}/g, "<blob>")
+		.replace(/\b((?=\w*(?:token|key|secret|password))[A-Za-z_]\w*)\s*[=:]\s*(["'])[^"']*\2/gi, "$1=<redacted>")
+		.replace(
+			/\b((?=\w*(?:token|key|secret|password))[A-Za-z_]\w*)\s*[=:]\s*(?!<redacted>)(?!["'])\S+/gi,
+			"$1=<redacted>",
+		)
+		.replace(/(["'])sk-[^"']+\1/g, "$1<redacted>$1")
+		.replace(/(["']).{160,}\1/g, "$1…$1");
+}
+
+export function descriptor(text: string): string {
+	return truncateDescriptor(collapseWhitespace(redactNoise(text)));
+}

package/src/extension/preview/index.ts

@@ -0,0 +1,31 @@
+// --- preview entry: score the whole cell for its one truthful line ---
+
+import { bridgedToolCandidates, fileCandidates, genericCandidates, shellCandidates } from "./candidates.js";
+import { descriptor } from "./descriptor.js";
+import { stringConsts } from "./scan.js";
+import { previewShellCommand } from "./shell.js";
+import type { CellPreview } from "./types.js";
+
+export type { CellPreview };
+export { descriptor, previewShellCommand };
+
+export function previewCell(code: string): CellPreview {
+	const source = code.trimEnd();
+	if (!source) return { kind: "ts", text: "" };
+	const vars = stringConsts(source);
+
+	// --- scan order: shell masks shell-looking syntax, then file/tool/generic ---
+	const shell = shellCandidates(source, vars);
+	const candidates = [
+		...shell.candidates,
+		...fileCandidates(shell.masked, vars),
+		...bridgedToolCandidates(shell.masked, vars),
+		...genericCandidates(shell.masked),
+	];
+
+	let best: { kind: CellPreview["kind"]; text: string; score: number } | undefined;
+	for (const candidate of candidates) {
+		if (candidate.text && (!best || candidate.score > best.score)) best = candidate;
+	}
+	return best ?? { kind: "ts", text: "" };
+}