pi-supernova 0.8.2 → 0.9.0

package/src/shared/image.js

@@ -0,0 +1,78 @@
+import {createHash} from "node:crypto";
+import childProcess from "node:child_process";
+import {fileURLToPath} from "node:url";
+import {assertModelImageMime,decodeImageData,errorMessage} from "./decode.js";
+import {assertPng} from "./png.js";
+
+const MAX_BYTES = 20 * 1024 * 1024;
+// Cache only successful content digests, never image bytes or file paths. A file
+// changed in place cannot reuse validation of its old contents.
+const verified = new Set();
+const workerPath = fileURLToPath(new URL("./image-worker.js",import.meta.url));
+let tail = Promise.resolve();
+
+function matchesSignature(bytes, mime) {
+  if (mime === "image/png") return bytes.subarray(0,8).equals(Buffer.from([137,80,78,71,13,10,26,10]));
+  if (mime === "image/jpeg") return bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255;
+  if (mime === "image/gif") return ["GIF87a","GIF89a"].includes(bytes.toString("ascii",0,6));
+  return bytes.toString("ascii",0,4) === "RIFF" && bytes.toString("ascii",8,12) === "WEBP";
+}
+
+function invalid(mime, label, reason) {
+  return new Error("invalid " + mime + (label ? " " + label : "") + ": " + reason + "; re-encode the image; limit is 32 MP across all frames; no image attached");
+}
+
+function decodePixels(bytes, mime, signal) {
+  signal?.throwIfAborted();
+  return new Promise((resolve,reject)=>{
+    // BUN_BE_BUN lets a compiled OMP executable run its normal Bun runtime,
+    // whose module resolver can load native dependencies from this package.
+    const child = childProcess.spawn(process.execPath,[workerPath,mime],{
+      env:{...process.env,BUN_BE_BUN:"1"},stdio:["pipe","ignore","pipe"],windowsHide:true,
+    });
+    let stderr = "", timedOut = false;
+    const abort = ()=>child.kill("SIGKILL");
+    const timer = setTimeout(()=>{timedOut=true;abort();},5000);
+    const finish = error=>{
+      clearTimeout(timer);
+      signal?.removeEventListener("abort",abort);
+      if (error) reject(error); else resolve();
+    };
+    child.stderr.on("data",chunk=>{stderr += chunk.toString().slice(0,Math.max(0,2048-stderr.length));});
+    child.stdin.on("error",()=>{}); // Early decoder exit may close stdin first.
+    child.once("error",finish);
+    child.once("close",code=>{
+      if (signal?.aborted) finish(signal.reason ?? new Error("aborted"));
+      else if (timedOut) finish(new Error("image decoding exceeded 5000 ms"));
+      else finish(code === 0 ? undefined : new Error(stderr.trim() || "image decoder exited before validation"));
+    });
+    signal?.addEventListener("abort",abort,{once:true});
+    if (signal?.aborted) abort();
+    child.stdin.end(bytes);
+  });
+}
+
+export async function validateImageBytes(bytes, mime, label = "", signal) {
+  signal?.throwIfAborted();
+  assertModelImageMime(mime);
+  if (bytes.length > MAX_BYTES) throw invalid(mime,label,"encoded image exceeds 20 MiB");
+  if (!matchesSignature(bytes,mime)) throw invalid(mime,label,"signature does not match declared format");
+  const key = mime + ":" + createHash("sha256").update(bytes).digest("hex");
+  const work = tail.then(async()=>{
+    signal?.throwIfAborted();
+    if (verified.has(key)) return;
+    if (mime === "image/png") assertPng(bytes,label);
+    try { await decodePixels(bytes,mime,signal); }
+    catch (error) { signal?.throwIfAborted(); throw invalid(mime,label,errorMessage(error)); }
+    verified.add(key);
+    if (verified.size > 16) verified.delete(verified.values().next().value);
+  });
+  // Serialize native raster allocations, not normal reads/guests. Failed or
+  // cancelled validation must never poison the next image's queue slot.
+  tail = work.catch(()=>{});
+  await work;
+}
+
+export async function validateReturnedImages(images, signal) {
+  for (const image of images ?? []) await validateImageBytes(decodeImageData(image.data),image.mimeType,"",signal);
+}

package/src/shared/png.js

@@ -0,0 +1,57 @@
+import * as zlib from "node:zlib";
+import {isFunction} from "./decode.js";
+// Fast container preflight before full decoding. Older Node/Bun versions use the
+// portable CRC fallback instead of requiring node:zlib.crc32.
+const signature = Buffer.from([137,80,78,71,13,10,26,10]);
+const crcTable = Uint32Array.from({length:256}, (_, value) => {
+  for (let bit = 0; bit < 8; bit++) value = (value >>> 1) ^ ((value & 1) ? 0xedb88320 : 0);
+  return value >>> 0;
+});
+
+function crc32(bytes) {
+  if (isFunction(zlib.crc32)) return zlib.crc32(bytes);
+  let crc = 0xffffffff;
+  for (const byte of bytes) crc = (crc >>> 8) ^ crcTable[(crc ^ byte) & 255];
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function invalid(reason, label) {
+  throw new Error("invalid PNG" + (label ? " " + label : "") + ": " + reason + "; re-encode the image as PNG before reading/returning it; no image attached");
+}
+
+function chunkAt(bytes, offset, label) {
+  if (bytes.length - offset < 12) invalid("truncated chunk", label);
+  const length = bytes.readUInt32BE(offset);
+  const type = bytes.toString("ascii",offset+4,offset+8);
+  if (!/^[A-Za-z]{4}$/.test(type)) invalid("invalid chunk type", label);
+  const end = offset + 8 + length;
+  if (end + 4 > bytes.length) invalid("truncated " + type + " chunk", label);
+  if (crc32(bytes.subarray(offset+4,end)) !== bytes.readUInt32BE(end)) invalid(type + " checksum mismatch", label);
+  return {type,length,end:end+4};
+}
+
+function checkHeader(bytes, chunk, offset, label) {
+  if (offset !== 8) {
+    if (chunk.type === "IHDR") invalid("duplicate IHDR", label);
+    return;
+  }
+  if (chunk.type !== "IHDR" || chunk.length !== 13) invalid("missing or invalid IHDR", label);
+  if (!bytes.readUInt32BE(offset+8) || !bytes.readUInt32BE(offset+12)) invalid("empty dimensions", label);
+}
+
+/** Reject corrupt attachments before a read can cross bash or a result can commit. */
+export function assertPng(bytes, label = "") {
+  if (!bytes.subarray(0,8).equals(signature)) invalid("signature mismatch", label);
+  let offset = 8, imageData = false;
+  while (offset < bytes.length) {
+    const chunk = chunkAt(bytes,offset,label);
+    checkHeader(bytes,chunk,offset,label);
+    if (chunk.type === "IDAT") imageData = true;
+    if (chunk.type === "IEND") {
+      if (chunk.length || !imageData || chunk.end !== bytes.length) invalid("invalid IEND or missing IDAT", label);
+      return;
+    }
+    offset = chunk.end;
+  }
+  invalid("missing IEND", label);
+}

package/src/shared/result.js

@@ -0,0 +1,77 @@
+import {isString,isObject} from './decode.js';
+
+export function textResult(text, details) {
+  return {
+    content: [{ type: "text", text: String(text ?? "") }],
+    details: details || {},
+  };
+}
+
+export function resultDiff(response) {
+  let details = response?.details;
+
+  if (isString(details)) {
+    try {
+      details = JSON.parse(details);
+    } catch {
+      return undefined;
+    }
+  }
+
+  return isObject(details) ? details.diff : undefined;
+}
+
+// Only native adapters can attach this host-local marker. It never crosses RPC;
+// the bridge sends a typed-value flag instead of asking the guest to guess JSON.
+export const READ_VALUE = Symbol("native read value");
+export const READ_BYTES = Symbol("native read bytes");
+export const READ_PREVIEW = Symbol("native read preview");
+export const MAX_READ_VALUE_BYTES = 64 * 1024 * 1024;
+
+function retainedReadValue(value) {
+  return isString(value) || isObject(value) || Array.isArray(value);
+}
+
+function containerBytes(value, pending, seen) {
+  if (seen.has(value)) return 8;
+  seen.add(value);
+  let bytes = 32;
+  const array = Array.isArray(value);
+  const keys = array ? value.keys() : Object.keys(value);
+  for (const key of keys) {
+    bytes += array ? 8 : 24 + 2 * key.length;
+    if (retainedReadValue(value[key])) pending.push(value[key]);
+  }
+  return bytes;
+}
+
+/** Conservative storage estimate, bounded while walking and aware of aliases. */
+export function readValueBytes(value, limit = Infinity, seen = new WeakSet()) {
+  const pending = [value];
+  let bytes = 0;
+  while (pending.length) {
+    const item = pending.pop();
+    if (isString(item)) bytes += 2*item.length;
+    else if (isObject(item) || Array.isArray(item)) bytes += containerBytes(item,pending,seen);
+    else bytes += 8;
+    if (bytes > limit) throw new Error("read value exceeds " + limit + " bytes of remaining storage budget; select fewer fields or smaller slices");
+  }
+  return bytes;
+}
+
+export function readResult(value, details = {}, preview = isString(value) ? value : "", bytes = readValueBytes(value), render) {
+  let content;
+  // Native consumers retain their text-content API. The bridge/trace use the
+  // typed value/preview, so ordinary RPCs never serialize this second copy.
+  return {get content() {
+    const text = () => render ? render() : isString(value) && !details.json ? value : JSON.stringify(value);
+    return content ??= [{type:"text",text:text()}];
+  }, details, [READ_VALUE]:value, [READ_BYTES]:bytes, [READ_PREVIEW]:preview};
+}
+
+export function asReadResult(raw) {
+  if (Object.hasOwn(raw, READ_VALUE)) return raw;
+  const image = raw.content?.find(part => part.type === "image");
+  const value = image ?? raw.content?.filter(part => part.type === "text").map(part => part.text).join("\n") ?? "";
+  return { ...raw, [READ_VALUE]: value, [READ_BYTES]: readValueBytes(value) };
+}

package/src/shared/syntax-context.js

@@ -20,12 +20,70 @@ export function errorContext(source, error) {
 export function parsePosition(message, source) {
   const located = /\(line (\d+) column (\d+)\)/.exec(String(message));
 
-  if (located) return { line: Number(located[1]), column: Number(located[2]) };
+  if (located) return { line: Number(located[1]), column: Number(located[2]) - 1 };
   const offsetMatch = /at position (\d+)/.exec(String(message));
 
   if (!offsetMatch) return null;
-  const before = String(source).slice(0, Number(offsetMatch[1]));
-  const lines = before.split("\n");
+  return offsetPosition(source, Number(offsetMatch[1]));
+}
+
+function offsetPosition(source, offset) {
+  const lines = String(source).slice(0, offset).split("\n");
 
   return { line: lines.length, column: lines.at(-1).length };
 }
+
+// Diagnostic-only JSON grammar: recover a failing token when the engine omits
+// offsets. JSON.parse remains the authority; cap extra work at 65,536 characters.
+// eslint-disable-next-line no-control-regex -- RFC 8259 excludes unescaped control characters from strings.
+const JSON_TOKEN = /("(?:[^"\\\u0000-\u001f]|\\(?:["\\/bfnrt]|u[\da-fA-F]{4}))*")|(-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)|(true|false|null)|[{}[\]:,]/y;
+const JSON_NEXT = {
+  end: { eof: [] },
+  value: { string: [], number: [], literal: [], "{": ["object"], "[": ["array"] },
+  array: { "]": [] },
+  arrayNext: { "]": [], ",": ["arrayNext", "value"] },
+  object: { "}": [] },
+  key: { string: ["colon"] },
+  colon: { ":": ["objectNext", "value"] },
+  objectNext: { "}": [], ",": ["key"] },
+};
+
+function jsonTokenAt(source, start) {
+  while (start < source.length && " \t\r\n".includes(source[start])) start++;
+  JSON_TOKEN.lastIndex = start;
+  const match = JSON_TOKEN.exec(source);
+
+  if (!match) return { start, end: start, kind: start === source.length ? "eof" : "invalid" };
+  const kind = ["string", "number", "literal"][match.slice(1).findIndex(Boolean)] ?? match[0];
+
+  return { start, end: JSON_TOKEN.lastIndex, kind };
+}
+
+function invalidJsonOffset(source) {
+  if (source.length > 64 * 1024) return null;
+  const stack = ["end", "value"];
+  let offset = 0;
+
+  while (stack.length) {
+    const token = jsonTokenAt(source, offset);
+    let state = stack.pop();
+    if (state === "array" && token.kind !== "]") { stack.push("arrayNext"); state = "value"; }
+    if (state === "object" && token.kind !== "}") state = "key";
+    const next = JSON_NEXT[state][token.kind];
+    if (!next) return token.start;
+    stack.push(...next);
+    offset = token.end;
+  }
+
+  return null;
+}
+
+export function jsonErrorContext(message, source) {
+  const native = parsePosition(message, source);
+  if (native) return sourceContext(source, native.line, native.column);
+  const offset = invalidJsonOffset(source);
+  if (offset === null) return "";
+  const { line, column } = offsetPosition(source, offset);
+
+  return " (near line " + line + " column " + (column + 1) + ")" + sourceContext(source, line, column);
+}

package/src/ui/host-render.js

@@ -0,0 +1,104 @@
+import {isObject,isFunction} from '../shared/decode.js';
+
+function isTheme(value) {
+	return isObject(value) && isFunction(value.fg);
+}
+
+/**
+ * Dual-host renderCall args:
+ *   Pi:  (args, theme, context)
+ *   OMP: (args, options/renderState, theme)
+ */
+export function normalizeCallRenderArgs(a, b, c) {
+	if (isTheme(b)) {
+		const context = isObject(c) ? c : {};
+
+		if (!isObject(context.state)) context.state = {};
+
+		return { args: a, theme: b, context, host: "pi" };
+	}
+
+	if (isTheme(c)) {
+		const options = isObject(b) ? b : {};
+
+		if (!isObject(options.state)) options.state = {};
+
+		const context = {
+			...options,
+			state: options.state,
+			expanded: options.expanded,
+			isPartial: options.isPartial,
+			executionStarted: options.executionStarted,
+			argsComplete: options.argsComplete,
+			lastComponent: options.lastComponent,
+			invalidate: options.invalidate,
+		};
+
+		return { args: a, theme: c, context, host: "omp", options };
+	}
+
+	throw new Error("supernova renderCall: theme missing (expected Pi or OMP signature)");
+}
+
+/**
+ * Dual-host renderResult args:
+ *   Pi:  (result, {expanded,isPartial}, theme, context)
+ *   OMP: (result, {expanded,isPartial}, theme, args)  (4th is args, not context)
+ *
+ * Call shapes share the first three positions, so host is inferred from the
+ * fourth argument's context-versus-args shape.
+ */
+function contextFrom(opts, ctxOrArgs) {
+	if (isObject(ctxOrArgs) && !isTheme(ctxOrArgs)) {
+		if ("lastComponent" in ctxOrArgs || "state" in ctxOrArgs || "invalidate" in ctxOrArgs) return ctxOrArgs;
+	}
+
+	return { state: opts.state, lastComponent: opts.lastComponent };
+}
+
+function isRenderContext(value) {
+	return "lastComponent" in value || "invalidate" in value;
+}
+
+function isToolArgs(value) {
+	return "code" in value || "file" in value || "programs" in value || "timeoutMs" in value;
+}
+
+function detectResultHost(options, ctxOrArgs) {
+  if (isTheme(options) || !isObject(ctxOrArgs) || isRenderContext(ctxOrArgs)) return "pi";
+  return isToolArgs(ctxOrArgs) ? "omp" : "pi";
+}
+
+function ensureState(context) {
+	if (!isObject(context.state)) context.state = {};
+
+	return context;
+}
+
+function resultArgs(ctxOrArgs, context) {
+	return ctxOrArgs?.code || ctxOrArgs?.file || ctxOrArgs?.programs ? ctxOrArgs : context.args;
+}
+
+function piResultArgs(result, options, theme, ctxOrArgs) {
+  const opts = isObject(options) ? options : {};
+  const context = ensureState(contextFrom(opts, ctxOrArgs));
+  return resultRenderModel(result, theme, context, opts, opts, detectResultHost(options, ctxOrArgs), resultArgs(ctxOrArgs, context));
+}
+
+function resultRenderModel(result, theme, context, flags, options, host, args) {
+  return { result, theme, context, options, host, args, expanded: !!flags.expanded, isPartial: !!flags.isPartial };
+}
+
+function oddballResultArgs(result, theme, themeOrCtx) {
+  const context = ensureState(isObject(themeOrCtx) ? themeOrCtx : {});
+  return resultRenderModel(result, theme, context, context, {}, "pi", context.args);
+}
+
+function normalizeResultRenderArgs(result, options, themeOrCtx, ctxOrArgs) {
+	if (isTheme(themeOrCtx)) return piResultArgs(result, options, themeOrCtx, ctxOrArgs);
+
+	if (isTheme(options)) return oddballResultArgs(result, options, themeOrCtx);
+
+	throw new Error("supernova renderResult: theme missing (expected Pi or OMP signature)");
+}
+export {normalizeResultRenderArgs};

package/src/ui/progress.js

@@ -0,0 +1,51 @@
+import {isFunction} from '../shared/decode.js';
+
+const PROGRESS_FRAME_MS = 80;
+
+/**
+ * Live trace updates for the card. The first update is immediate (seeds the result slot);
+ * later ones are coalesced to one host re-render per frame so a tight loop of nova.calls
+ * is not throttled by the TUI. A throwing host callback must never break the run.
+ */
+export function progressEmitter(onUpdate) {
+  if (!isFunction(onUpdate)) return Object.assign(() => {}, { flush() {} });
+  let pending = null;
+  let timer = null;
+  let lastSent = -Infinity;
+
+  const send = () => {
+    timer = null;
+
+    if (pending === null) return;
+    // Snapshot only at emission, not on every tool event. Completed records must
+    // not mutate a previously emitted frame while Pi is still consuming it.
+    const trace = pending.map(record => ({ ...record }));
+    pending = null;
+    lastSent = performance.now();
+
+    try {
+      onUpdate({ content: [{ type: "text", text: "" }], details: { trace, running: true } });
+    } catch {}
+  };
+
+  const emit = (trace) => {
+    pending = trace;
+
+    if (timer !== null) return;
+    const wait = PROGRESS_FRAME_MS - (performance.now() - lastSent);
+
+    if (wait <= 0) send();
+    else {
+      timer = setTimeout(send, wait);
+      timer.unref?.();
+    }
+  };
+
+  emit.flush = () => {
+    if (timer !== null) clearTimeout(timer);
+    pending = null;
+    timer = null;
+  };
+
+  return emit;
+}