pi-repl-py 0.7.1 → 0.8.0

package/src/extension/prompt.ts

@@ -1,26 +1,21 @@
+import { DEFAULT_MAX_OUTPUT_CHARS } from "../engine/index.js";
+
 export const executeToolDescription =
-	"Execute Python in a Jupyter notebook. Your workspace is a notebook where every cell runs in a " +
-	"shared Python environment: variables, functions, imports, classes, and data defined in one cell " +
-	"stay available and reuseable for later cells for the life of the notebook. " +
-	"Output is truncated to 45K with an explicit marker";
+	"Execute Python in a Jupyter notebook. Your workspace is one persistent live session: every " +
+	"cell runs in the same namespace, so variables, functions, classes, imports, and data defined " +
+	`in one cell stay available to every later cell. Output is truncated to ${DEFAULT_MAX_OUTPUT_CHARS} chars with an explicit marker`;
 
 export const executePromptSnippet = "Execute Python in a Jupyter notebook (read, write, run, search, and more)";
 
-export function buildPromptGuidelines(preloaded: string[]): string[] {
+export function buildPromptGuidelines(): string[] {
 	return [
 		"Write idiomatic Python.",
-		"Find, Filter, Fetch, Sample and Narrow down the output in Python, always print the exact (slice, snippet, Excerpt) you need. Be precise.",
-		"Make surgical changes over rewrites or whole-file dumps: read the exact lines first, anchor them, then replace, verify and read the file back before trusting it.",
-		"REUSE existing variables, functions, imports, classes, and data from prior cells/namespaces rather than recomputing or reconstructing states that already exist in the notebook.",
-		"If output begins with <repl_engine_reset>, the runtime rebuilt and the kernel was restored from a snapshot; reverify surviving states before building on them.",
-		...(preloaded.length
-			? [
-					[
-						"Preloaded helpers, use them as any loaded function or variable:",
-						...preloaded.map((line) => `  - ${line.replace(/\n/g, "\n    ")}`),
-					].join("\n"),
-				]
-			: []),
+		"REPL-driven development: the live session's namespace is the single source of truth; reuse and extend existing objects rather than recreating or recomputing them.",
+		"Exploratory data analysis: look before acting (head, shape, slice, sample); print the minimal view that answers the question.",
+		"Quit thinking and look: read the exact lines/values before changing anything.",
+		"Minimal diff: change one thing at a time; if you didn't verify it, it ain't fixed.",
+		"Idempotent cells: safe to re-run.",
+		"If output begins with <repl_engine_reset>, the runtime rebuilt from a snapshot; trust but verify surviving state.",
 		"Be concise.",
 	];
 }

package/src/extension/session-engine.ts

@@ -1,6 +1,6 @@
 // Lifecycle: boot, session binding, reset announcements. Recovery is a background quiet-gap job; the notice lands on the first cell after the restore.
 
-import type { HelperLoadResult, RestoreResult } from "../engine/index.js";
+import { DEFAULT_BOOT_TIMEOUT_MS, type HelperLoadResult, type RestoreResult } from "../engine/index.js";
 
 /** Show enough names to orient, then count the rest (a revive can carry hundreds). */
 function summarizeNames(names: readonly string[], limit: number): string {
@@ -34,8 +34,6 @@ export interface EngineLifecycleDeps<E extends RevivableEngine> {
 /** startup: announce when the conversation has a saved past; cell: a mid-session rebuild announces immediately. */
 export type AcquireOrigin = "startup" | "cell";
 
-const DEFAULT_BOOT_TIMEOUT_MS = 90_000;
-
 function revivedNoticeBody(origin: AcquireOrigin): string {
 	const resumed = origin === "startup";
 	return resumed

package/src/engine/session.ts

@@ -1,146 +0,0 @@
-// --- Jupyter over ZMTP: [<IDS|MSG>] sig h p m c; sig = hex(HMAC-SHA256(key, h||p||m||c)); ids are empty for client channels ---
-
-import { createHmac, randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
-
-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;
-}
-
-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));
-}
-
-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");
-	}
-
-	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];
-	}
-
-	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> {
-	// --- store_history off: IPython's In/Out pins every result and can't be reclaimed from cells (62MB → 400+MB); the display hook still publishes results ---
-	return {
-		code,
-		silent,
-		store_history: false,
-		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";
-
-/** Route-gate: drop malformed and unsigned traffic — anything that fails the kernel's HMAC is not the kernel. */
-export function isTrustedMessage(msg: ParsedMessage | null): msg is ParsedMessage {
-	return msg !== null && msg.signatureOk;
-}
-
-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

@@ -1,239 +0,0 @@
-// --- ZMTP 3.0 by hand (bun can't load libzmq's bindings); DEALER shell/control, SUB 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)]);
-
-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;
-
-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
-
-	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;
-	}
-
-	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);
-	}
-
-	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);
-	}
-}
-
-export type ZmtpSocketType = "DEALER" | "SUB";
-
-interface ReadReady {
-	resolve(): void;
-	reject(error: Error): void;
-}
-
-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;
-	}
-
-	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;
-					}
-					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(frames: Uint8Array[]): void {
-		for (let i = 0; i < frames.length; i++) {
-			this.socket?.write(encodeFrame(frames[i], i < frames.length - 1));
-		}
-	}
-
-	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/tool-meta.ts

@@ -1,8 +0,0 @@
-import { buildPromptGuidelines, executePromptSnippet, executeToolDescription } from "./prompt.js";
-
-export const EXECUTE_DESCRIPTION = executeToolDescription;
-export const EXECUTE_PROMPT_SNIPPET = executePromptSnippet;
-
-export function buildExecutePromptGuidelines(): string[] {
-	return buildPromptGuidelines([]);
-}