pi-repl-py 0.1.1 → 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

@@ -5,7 +5,7 @@ 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");
+const SHELL_OPEN_PATTERN = new RegExp(`Bun\\s*\\.\\s*\\$\\s*(?:\\([^)]*\\)\\s*)?${BACKTICK}`, "g");
 
 export function shellCandidates(
 	source: string,
@@ -31,52 +31,6 @@ export function shellCandidates(
 	return { candidates, masked };
 }
 
-const STRING_ARG_PATTERN = /^\s*(?:"([^"]*)"|'([^']*)')/;
-
-export function agentCandidates(
-	source: string,
-	vars: ReadonlyMap<string, string>,
-): { candidates: Candidate[]; masked: string } {
-	const tasks: string[] = [];
-	let masked = source;
-	const pattern = /rlm\s*\.\s*run\s*\(/g;
-	let match = pattern.exec(masked);
-	while (match) {
-		const argsStart = match.index + match[0].length;
-		let task: string | undefined;
-		const rest = masked.slice(argsStart);
-		const literal = rest.match(STRING_ARG_PATTERN);
-		if (literal) {
-			task = literal[1] ?? literal[2];
-		} else if (rest.trimStart().startsWith(BACKTICK)) {
-			const tickIndex = argsStart + rest.indexOf(BACKTICK);
-			const span = scanTemplate(masked, tickIndex);
-			task = substituteVars(span.body, vars);
-			masked = maskSpan(masked, span);
-		} else {
-			const identifier = rest.match(/^\s*([A-Za-z_$][\w$]*)/)?.[1];
-			task = identifier ? (vars.get(identifier) ?? identifier) : undefined;
-		}
-		// --- a chosen child name is identity; lead with it ---
-		const name = masked.slice(argsStart).match(/name\s*:\s*(?:"([^"]*)"|'([^']*)')/);
-		const label = name?.[1] ?? name?.[2];
-		tasks.push(label && task ? label + ": " + task : (label ?? task ?? "subagent"));
-		pattern.lastIndex = argsStart;
-		match = pattern.exec(masked);
-	}
-	const candidates: Candidate[] =
-		tasks.length === 0
-			? []
-			: [
-					{
-						kind: "agent",
-						text: descriptor(tasks.length === 1 ? (tasks[0] ?? "") : tasks[0] + " (+" + (tasks.length - 1) + " more)"),
-						score: 100,
-					},
-				];
-	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;
 
@@ -104,7 +58,7 @@ const FILE_EFFECT_VERBS: ReadonlyArray<[string, string]> = [
 // --- 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 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);
@@ -121,15 +75,15 @@ export function fileCandidates(source: string, vars: ReadonlyMap<string, string>
 		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 });
+		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 });
+		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 });
+		if (url) candidates.push({ kind: "ts", text: descriptor(`fetch ${url}`), score: 75 });
 	}
 	return candidates;
 }
@@ -151,11 +105,11 @@ export function bridgedToolCandidates(source: string, vars: ReadonlyMap<string,
 		const spec = BRIDGED_TOOLS[match[1] ?? ""];
 		if (!spec) continue;
 		const props = match[2] ?? "";
-		const argMatch = props.match(new RegExp(spec.arg + "\\s*:\\s*([^,}]+)"));
+		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;
+		const text = spec.verb ? `${spec.verb} ${target}` : previewShellCommand(target) || target;
 		candidates.push({ kind: "ts", text: descriptor(text), score: spec.score });
 	}
 	return candidates;

package/src/extension/preview/descriptor.ts

@@ -1,5 +1,5 @@
 // --- descriptor: collapse the raw line into one readable, safe, width-capped string ---
-export const DESCRIPTOR_MAX_WIDTH = 64;
+const DESCRIPTOR_MAX_WIDTH = 64;
 
 function collapseWhitespace(text: string): string {
 	return text.replace(/\s+/g, " ").trim();
@@ -7,7 +7,7 @@ function collapseWhitespace(text: string): string {
 
 function truncateDescriptor(text: string): string {
 	if (text.length <= DESCRIPTOR_MAX_WIDTH) return text;
-	return text.slice(0, DESCRIPTOR_MAX_WIDTH - 1).trimEnd() + "…";
+	return `${text.slice(0, DESCRIPTOR_MAX_WIDTH - 1).trimEnd()}…`;
 }
 
 // --- strip blobs, secrets, and sk- keys before a line reaches the header ---

package/src/extension/preview/index.ts

@@ -1,12 +1,6 @@
 // --- preview entry: score the whole cell for its one truthful line ---
 
-import {
-	agentCandidates,
-	bridgedToolCandidates,
-	fileCandidates,
-	genericCandidates,
-	shellCandidates,
-} from "./candidates.js";
+import { bridgedToolCandidates, fileCandidates, genericCandidates, shellCandidates } from "./candidates.js";
 import { descriptor } from "./descriptor.js";
 import { stringConsts } from "./scan.js";
 import { previewShellCommand } from "./shell.js";
@@ -20,11 +14,9 @@ export function previewCell(code: string): CellPreview {
 	if (!source) return { kind: "ts", text: "" };
 	const vars = stringConsts(source);
 
-	// --- scan order matters: agent masks shell-looking syntax before the shell scan ---
-	const agent = agentCandidates(source, vars);
-	const shell = shellCandidates(agent.masked, vars);
+	// --- scan order: shell masks shell-looking syntax, then file/tool/generic ---
+	const shell = shellCandidates(source, vars);
 	const candidates = [
-		...agent.candidates,
 		...shell.candidates,
 		...fileCandidates(shell.masked, vars),
 		...bridgedToolCandidates(shell.masked, vars),

package/src/extension/preview/shell.ts

@@ -24,7 +24,7 @@ function simplifyRunnerCommand(line: string): string | undefined {
 	if (words[0] === "npm" || words[0] === "pnpm") {
 		const runIndex = words.indexOf("run");
 		if (runIndex >= 0 && words[runIndex + 1]) {
-			return (words[0] + " " + words.slice(runIndex + 1).join(" ")).trim();
+			return `${words[0]} ${words.slice(runIndex + 1).join(" ")}`.trim();
 		}
 	}
 	if (line.includes("node_modules/.bin/")) {
@@ -36,7 +36,7 @@ function simplifyRunnerCommand(line: string): string | undefined {
 function simplifyMutationCommand(line: string): string | undefined {
 	const words = shellWords(line);
 	if (words.length === 0) return undefined;
-	if (words[0] === "cat" && words[1] === ">" && words[2]) return "write " + pathTail(words[2]);
+	if (words[0] === "cat" && words[1] === ">" && words[2]) return `write ${pathTail(words[2])}`;
 	if (words[0] === "tee" && words.at(-1)) {
 		return (words.includes("-a") ? "append " : "write ") + pathTail(words.at(-1) ?? "");
 	}
@@ -64,7 +64,7 @@ export const SHELL_SETUP_WORDS = new Set([
 	"sync",
 ]);
 
-export const SHELL_ACTION_WORDS = new Set([
+const SHELL_ACTION_WORDS = new Set([
 	"rm",
 	"mv",
 	"cp",
@@ -151,6 +151,6 @@ export function previewShellCommandScored(command: string): { text: string; stre
 	// --- trailing redirections are plumbing, not intent ---
 	const cleaned = best.text.replace(/(?:\s*(?:2>&1|[12]?>\s*\/dev\/null|&>\s*\/dev\/null))+\s*$/, "");
 	// --- a stripped cd prefix still matters when it names a non-default dir ---
-	const text = cwdSuffix && !cleaned.includes(cwdSuffix) ? cleaned + " (" + cwdSuffix + ")" : cleaned;
+	const text = cwdSuffix && !cleaned.includes(cwdSuffix) ? `${cleaned} (${cwdSuffix})` : cleaned;
 	return { text: descriptor(text), strength: best.score };
 }

package/src/extension/preview/types.ts

@@ -1,5 +1,5 @@
 // --- shared preview types; tiny module so every consumer imports only the shape it needs ---
-export type CellPreviewKind = "shell" | "agent" | "ts";
+type CellPreviewKind = "shell" | "ts";
 
 export interface CellPreview {
 	kind: CellPreviewKind;