pi-supernova 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.0.1] - 2026-09-03
+
+### Added
+
+- Initial `pi-supernova` CodeMode for Pi and OMP: progressive `nova.search` / `nova.describe` / `nova.call`, result bottleneck, and Amdahl Auto `callMany` / `parallel`.
+
+### Fixed
+
+- TUI no longer crashes with `Rendered line exceeds terminal width (92 > 91)` on long ENOENT/diff lines.
+- Long paths wrap on `/` (filename kept) instead of end-truncating as `packages/pi-supern…`.
+- Call/result cards use a muted violet / grey-blue self-framed chrome (not the stock green tool panel or raw JSON args dump).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AdityaVG13
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# pi-supernova
+
+[![npm](https://img.shields.io/npm/v/pi-supernova.svg)](https://www.npmjs.com/package/pi-supernova)
+[![license](https://img.shields.io/npm/l/pi-supernova.svg)](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/LICENSE)
+[![node](https://img.shields.io/node/v/pi-supernova.svg)](https://nodejs.org)
+[![pi-package](https://img.shields.io/badge/pi--package-extension-7aa2f7)](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md)
+
+**CodeMode for [Pi](https://pi.dev) and [OMP](https://omp.sh).** One tool, one guest program: progressive discovery, a hard result bottleneck, and Amdahl-aware parallel waves.
+
+```bash
+pi install npm:pi-supernova
+omp install npm:pi-supernova
+```
+
+Load **before** other tool-owning packages so `registerTool` capture works. Restart the host after install.
+
+---
+
+## Why
+
+| | Stock multi-tool prompt | **pi-supernova** |
+|--|-------------------------|------------------|
+| Schema tax | Every tool in context | Thin catalog + on-demand `describe` |
+| Multi-step | Model stitches turns | One in-process program |
+| Parallel reads | Ad hoc | `callMany` Auto / `parallel()` |
+| Hosts | Separate packages | Same tarball for Pi **and** OMP |
+
+Guest code is an in-process `AsyncFunction` (same trust class as host `bash`) — not an OS/VM sandbox. Tool calls still go through `nova.call`.
+
+---
+
+## Quick example
+
+```js
+async () => {
+  const hits = await nova.search("read file contents");
+  await nova.describe("read");
+
+  const a = await nova.call("read", { path: "src/index.ts" });
+  const wave = await nova.callMany([
+    { name: "read", args: { path: "a.ts" } },
+    { name: "read", args: { path: "b.ts" } },
+  ]);
+
+  return { preview: a.value.slice(0, 200), mode: wave.mode, n: wave.length };
+}
+```
+
+Globals: `nova` / `tools`, `parallel`, `pipeline`, `console`, plus shorthand `read` / `write` / `edit` / `bash` / …
+
+Terminal card (muted violet / grey-blue — not a raw JSON args dump):
+
+```text
+  nova · 84ms
+    ▤ read  packages/pi-supernova/host-bridge.js
+    ✎ edit  packages/pi-supernova/diff.js
+```
+
+---
+
+## API
+
+| API | Role |
+|-----|------|
+| `nova.search(query, limit?)` | Thin catalog hits |
+| `nova.describe(name)` | Parameter summary on demand |
+| `nova.call(name, args)` | Host tool or native adapter |
+| `nova.callMany([{name,args}])` | Auto parallel wave — iterable array with `.mode` / `.results` |
+| `parallel(thunks)` / `pipeline(items, …stages)` | Raw `Promise.all` helpers |
+| `nova.speculate(fn)` | Counterfactual branch (rollback / commit) |
+
+---
+
+## Configuration
+
+Optional `~/.pi/agent/supernova.json` or `~/.omp/agent/supernova.json`  
+(or `PI_SUPERNOVA_CONFIG` / `PI_CONFIG_DIR` / `OMP_CONFIG_DIR`):
+
+```json
+{
+  "timeoutMs": 60000,
+  "maxCodeChars": 48000,
+  "maxBridgeCalls": 256,
+  "maxCallResultChars": 65536,
+  "maxReturnChars": 200000,
+  "maxSearchResults": 12,
+  "spillDir": null
+}
+```
+
+Defaults also set `excludeTools` (includes `supernova` and DCE helpers). An empty `"excludeTools": []` **replaces** those defaults — omit the key unless you mean that.
+
+Slash: `/supernova` — catalog size + captured executors.
+
+---
+
+## Install variants
+
+```bash
+# Path / dogfood
+pi install /path/to/pi-stack/packages/pi-supernova
+omp install /path/to/pi-stack/packages/pi-supernova
+
+# Monorepo clone
+git clone https://github.com/AdityaVG13/pi-stack.git
+pi install ./pi-stack/packages/pi-supernova
+omp install ./pi-stack/packages/pi-supernova
+```
+
+Pair with DCE last if you use it: `omp install npm:pi-deferred-context-engine`.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `no executor for tool "…"` | Install supernova **first**; restart; `/supernova` |
+| `Rendered line exceeds terminal width` | ≥0.0.1 and restart so `render.js` reloads |
+| `callMany` / not iterable | ≥0.0.1 — return is an array with `.mode` / `.results` |
+| Extension missing on OMP | `omp install npm:pi-supernova` (needs `"omp".extensions`) |
+
+---
+
+## Limitations
+
+- Guest JS is **unsandboxed**. Adapter path jails are not a boundary against `import("node:fs")`.
+- `bash` / mutating tools flush speculative writes (transaction barrier); error rollback cannot undo that.
+- First public cut (`0.0.1`) — APIs and TUI will iterate.
+
+## License
+
+MIT · [AdityaVG13/pi-stack](https://github.com/AdityaVG13/pi-stack/tree/main/packages/pi-supernova)

package/bottleneck.js

@@ -0,0 +1,132 @@
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { isString, isObject } from "./decode.js";
+
+export function truncateChars(text, maxChars, label = "value") {
+  const normalized = isString(text) ? text : String(text ?? "");
+  const numericLimit = Number(maxChars);
+  const limit = Number.isFinite(numericLimit) ? Math.max(0, Math.floor(numericLimit)) : numericLimit === Infinity ? normalized.length : 0;
+  if (normalized.length <= limit) return { text: normalized, truncated: false };
+  if (limit <= 100) {
+    return {
+      text: normalized.slice(0, limit),
+      truncated: true,
+      originalChars: normalized.length,
+    };
+  }
+  const head = Math.floor(limit * 0.7);
+  let tail = Math.max(0, limit - head);
+  let marker = "";
+  let previousTail = -1;
+  while (tail !== previousTail) {
+    previousTail = tail;
+    const omitted = normalized.length - head - tail;
+    marker = `\n…[${label} truncated ${omitted} chars]…\n`;
+    tail = Math.max(0, limit - head - marker.length);
+  }
+  return {
+    text: normalized.slice(0, head) + marker + (tail > 0 ? normalized.slice(-tail) : ""),
+    truncated: true,
+    originalChars: normalized.length,
+  };
+}
+
+export function serializeBounded(value, maxChars, label = "value") {
+  let serialized;
+  try {
+    serialized = isString(value) ? value : JSON.stringify(value, null, 2);
+  } catch {
+    serialized = String(value);
+  }
+  if (serialized === undefined) serialized = "null";
+  return truncateChars(serialized, maxChars, label);
+}
+
+function extractContentText(content) {
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part) => part && isObject(part) && part.type === "text" && isString(part.text))
+    .map((part) => part.text)
+    .join("\n");
+}
+
+function extractRawString(raw, maxChars) {
+  if (raw == null) return "";
+  if (isString(raw)) return raw;
+  if (!isObject(raw)) return String(raw);
+  if (Array.isArray(raw.content)) return extractContentText(raw.content);
+  if (isString(raw.text)) return raw.text;
+  return serializeBounded(raw, maxChars, "host-result").text;
+}
+
+function summarizeDetails(details, maxChars) {
+  return serializeBounded(details, maxChars, "details").text;
+}
+
+function maybeSpill(cappedText, fullText, config) {
+  if (fullText.length <= (config.maxCallResultChars ?? 65536)) return null;
+  if (!isString(config.spillDir) || config.spillDir.length === 0) return null;
+  try {
+    const dir = config.spillDir;
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const filePath = path.join(dir, `${Date.now()}-${randomUUID().slice(0, 8)}.txt`);
+    fs.writeFileSync(filePath, fullText, { encoding: "utf8", mode: 0o600 });
+    return { pointer: filePath };
+  } catch {
+    return null;
+  }
+}
+
+export function packageHostResult(raw, config) {
+  const maxChars = config.maxCallResultChars ?? 65536;
+  const isError = isObject(raw) && raw.isError === true;
+  const details = isObject(raw) ? raw.details : undefined;
+  const upstreamTruncated = isObject(details) && details.outputTruncated === true;
+  const text = extractRawString(raw, maxChars);
+  const summarizedDetails = details === undefined ? undefined : summarizeDetails(details, 2000);
+
+  const capped = truncateChars(text, maxChars, "host-result");
+  if (!capped.truncated) {
+    return {
+      ok: !isError,
+      value: capped.text,
+      truncated: upstreamTruncated,
+      details: summarizedDetails,
+    };
+  }
+
+  const spill = maybeSpill(capped.text, text, config);
+  const value = spill?.pointer
+    ? `${capped.text}\n\n[full output spilled to ${spill.pointer}]`
+    : capped.text;
+
+  return {
+    ok: !isError,
+    value,
+    truncated: true,
+    originalChars: capped.originalChars,
+    spill: spill?.pointer,
+    details: summarizedDetails,
+  };
+}
+
+export function packageFinalReturn(value, logs, config) {
+  const maxReturn = config.maxReturnChars ?? 200000;
+  const serialized = serializeBounded(value, maxReturn, "return");
+  const logLines = Array.isArray(logs) ? logs : [];
+  const maxLogLines = config.maxLogLines ?? 100;
+  const maxLogLineChars = config.maxLogLineChars ?? 4096;
+  const clippedLogs = logLines.slice(0, maxLogLines).map((line) => {
+    const s = isString(line) ? line : String(line);
+    return s.length > maxLogLineChars ? s.slice(0, maxLogLineChars) + "…" : s;
+  });
+  return {
+    returnValue: serialized.truncated ? serialized.text : value,
+    returnText: serialized.text,
+    returnTruncated: serialized.truncated,
+    logs: clippedLogs,
+    logTruncated: logLines.length > maxLogLines,
+  };
+}

package/catalog.js

@@ -0,0 +1,113 @@
+
+import { isString, isObject } from "./decode.js";
+
+function normalizeTool(tool) {
+  if (!tool || !isObject(tool)) return null;
+  const name = isString(tool.name) ? tool.name : "";
+  if (!name) return null;
+  const description = isString(tool.description) ? tool.description : "";
+  return {
+    name,
+    nameLower: name.toLowerCase(),
+    description,
+    descLower: description.toLowerCase(),
+    parameters: tool.parameters,
+    sourcePath:
+      tool.sourceInfo && isString(tool.sourceInfo.path)
+        ? tool.sourceInfo.path
+        : isString(tool.extensionPath)
+          ? tool.extensionPath
+          : isString(tool.sourcePath)
+            ? tool.sourcePath
+            : undefined,
+  };
+}
+
+export function buildCatalog(tools, excludeNames = []) {
+  const exclude = new Set(excludeNames);
+  const rows = [];
+  for (const tool of tools || []) {
+    const row = normalizeTool(tool);
+    if (!row || exclude.has(row.name)) continue;
+    rows.push(row);
+  }
+  rows.sort((a, b) => a.name.localeCompare(b.name));
+  return rows;
+}
+
+function tokenize(query) {
+  return String(query || "")
+    .toLowerCase()
+    .split(/[^a-z0-9_]+/g)
+    .filter((t) => t.length > 1);
+}
+
+function scoreRow(row, tokens) {
+  if (tokens.length === 0) return 1;
+  const name = row.nameLower || row.name.toLowerCase();
+  const desc = row.descLower || row.description.toLowerCase();
+  let score = 0;
+  for (const token of tokens) {
+    if (name === token) score += 10;
+    else if (name.includes(token)) score += 5;
+    else if (desc.includes(token)) score += 2;
+  }
+  return score;
+}
+
+export function searchCatalog(catalog, query, limit = 12) {
+  const tokens = tokenize(query);
+  const scored = [];
+  for (const row of catalog) {
+    const score = scoreRow(row, tokens);
+    if (score <= 0 && tokens.length > 0) continue;
+    scored.push({
+      name: row.name,
+      description: row.description.slice(0, 160),
+      score,
+      callable: true,
+    });
+  }
+  scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+  return scored.slice(0, Math.max(1, limit)).map(({ score: _s, ...hit }) => hit);
+}
+
+function schemaSummary(parameters) {
+  if (!parameters || !isObject(parameters)) return { type: "unknown" };
+  const props = parameters.properties;
+  if (!props || !isObject(props)) {
+    return {
+      type: parameters.type || "object",
+      note: "schema present (no enumerable properties)",
+    };
+  }
+  const required = new Set(Array.isArray(parameters.required) ? parameters.required : []);
+  const fields = {};
+  for (const [key, schema] of Object.entries(props)) {
+    const s = schema && isObject(schema) ? schema : {};
+    fields[key] = {
+      type: s.type || (Array.isArray(s.anyOf) ? "union" : "unknown"),
+      required: required.has(key),
+      description: isString(s.description) ? s.description.slice(0, 120) : undefined,
+    };
+  }
+  return { type: "object", fields };
+}
+
+export function describeTool(catalog, name) {
+  const row = catalog.find((t) => t.name === name);
+  if (!row) {
+    return { ok: false, error: `unknown tool: ${name}` };
+  }
+  if (!row._described) {
+    row._described = {
+      ok: true,
+      name: row.name,
+      description: row.description,
+      parameters: schemaSummary(row.parameters),
+      sourcePath: row.sourcePath,
+      signature: `await nova.call(${JSON.stringify(row.name)}, args)`,
+    };
+  }
+  return row._described;
+}

package/config.default.json

@@ -0,0 +1,14 @@
+{
+  "timeoutMs": 60000,
+  "maxCodeChars": 48000,
+  "maxBridgeCalls": 256,
+  "maxCallResultChars": 65536,
+  "maxReturnChars": 200000,
+  "maxLogLines": 100,
+  "maxLogLineChars": 4096,
+  "maxSearchResults": 12,
+  "spillDir": null,
+  "excludeTools": ["supernova", "search_tools", "promote_tools", "demote_tools", "list_capabilities"],
+  "mutatingTools": ["write", "edit", "bash", "apply_patch", "replace_in_file"],
+  "mutatingPrefixes": ["mcp_"]
+}

package/config.js

@@ -0,0 +1,75 @@
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createRequire } from "node:module";
+import { isString, isObject } from "./decode.js";
+
+const require = createRequire(import.meta.url);
+const DEFAULTS = require("./config.default.json");
+
+const KNOWN_KEYS = new Set(Object.keys(DEFAULTS));
+const NONNEGATIVE_INTEGER_KEYS = new Set(["maxLogLines"]);
+const POSITIVE_INTEGER_KEYS = new Set([
+  "timeoutMs",
+  "maxCodeChars",
+  "maxBridgeCalls",
+  "maxCallResultChars",
+  "maxReturnChars",
+  "maxLogLineChars",
+  "maxSearchResults",
+]);
+
+export function packageDefaults() {
+  return structuredClone(DEFAULTS);
+}
+
+function userConfigPath() {
+  if (process.env.PI_SUPERNOVA_CONFIG) return process.env.PI_SUPERNOVA_CONFIG;
+  for (const key of ["PI_CONFIG_DIR", "OMP_CONFIG_DIR"]) {
+    const root = process.env[key];
+    if (!root || !isString(root)) continue;
+    return path.join(path.resolve(root), "agent", "supernova.json");
+  }
+  const install = import.meta.dirname ?? path.dirname(new URL(import.meta.url).pathname);
+  const norm = String(install).replace(/\\/g, "/").toLowerCase();
+  const home = os.homedir();
+  if (norm.includes("/.omp/")) return path.join(home, ".omp", "agent", "supernova.json");
+  return path.join(home, ".pi", "agent", "supernova.json");
+}
+
+function readJson(filePath) {
+  try {
+    const text = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(text);
+  } catch (err) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) return null;
+    throw err;
+  }
+}
+
+export function mergeConfig(base, overlay) {
+  if (!overlay || !isObject(overlay) || Array.isArray(overlay)) return base;
+  const out = { ...base };
+  for (const [key, value] of Object.entries(overlay)) {
+    if (!KNOWN_KEYS.has(key)) continue;
+    if (POSITIVE_INTEGER_KEYS.has(key)) {
+      if (Number.isInteger(value) && value > 0) out[key] = value;
+    } else if (NONNEGATIVE_INTEGER_KEYS.has(key)) {
+      if (Number.isInteger(value) && value >= 0) out[key] = value;
+    } else if (Array.isArray(base[key])) {
+      if (Array.isArray(value) && value.every(isString)) out[key] = value.slice();
+    } else if (key === "spillDir") {
+      if (value === null || (isString(value) && value.length > 0)) out[key] = value;
+    }
+  }
+  return out;
+}
+
+export function loadConfig() {
+  const userPath = userConfigPath();
+  const user = readJson(userPath);
+  return mergeConfig(packageDefaults(), user ?? null);
+}
+
+export { userConfigPath, KNOWN_KEYS };

package/decode.js

@@ -0,0 +1,16 @@
+
+const toStr = Object.prototype.toString;
+
+export const isString = (v) => toStr.call(v) === "[object String]";
+export const isObject = (v) => toStr.call(v) === "[object Object]";
+export const isFunction = (v) => toStr.call(v) === "[object Function]" || v instanceof Function;
+export const isNumber = (v) => toStr.call(v) === "[object Number]" && Number.isFinite(v);
+export const isRecord = (v) => v !== null && isObject(v);
+
+export function parseString(v, fallback = "") {
+  return isString(v) ? v : fallback;
+}
+
+export function parseNonEmptyString(v) {
+  return isString(v) && v.trim().length > 0 ? v.trim() : null;
+}

package/diff.js

@@ -0,0 +1,107 @@
+
+import { isString } from "./decode.js";
+
+export function buildEditDiff(filePath, originalText, oldText, newText) {
+  const fileLines = isString(originalText) ? originalText.split("\n") : [];
+  const idx = isString(originalText) ? originalText.indexOf(oldText) : -1;
+
+  const startLine = idx >= 0 ? originalText.slice(0, idx).split("\n").length : 1;
+  const oldLines = oldText.split("\n");
+  const newLines = newText.split("\n");
+
+  const lines = [];
+  if (startLine > 1 && fileLines.length >= startLine - 1) {
+    lines.push({ type: "context", lineNum: startLine - 1, text: fileLines[startLine - 2] });
+  }
+
+  for (let i = 0; i < oldLines.length; i++) {
+    lines.push({ type: "remove", lineNum: startLine + i, text: oldLines[i] });
+  }
+  for (let i = 0; i < newLines.length; i++) {
+    lines.push({ type: "add", lineNum: startLine + i, text: newLines[i] });
+  }
+
+  const afterLine = startLine + oldLines.length;
+  if (fileLines.length >= afterLine) {
+    lines.push({ type: "context", lineNum: afterLine, text: fileLines[afterLine - 1] });
+  }
+
+  return {
+    path: filePath,
+    op: "edit",
+    added: newLines.length,
+    removed: oldLines.length,
+    lines,
+  };
+}
+
+export function buildPatchDiff(filePath, patchText) {
+  const patchLines = isString(patchText) ? patchText.replace(/\r\n/g, "\n").split("\n") : [];
+  const lines = [];
+  let added = 0;
+  let removed = 0;
+  let currentLineNum = 1;
+  let inHunk = false;
+
+  for (const pLine of patchLines) {
+    const headerMatch = /^@@\s+-(\d+)/.exec(pLine);
+    if (headerMatch) {
+      currentLineNum = parseInt(headerMatch[1], 10);
+      inHunk = true;
+      continue;
+    }
+    if (!inHunk || pLine.startsWith("\\")) continue;
+    if (pLine.startsWith("-")) {
+      removed += 1;
+      lines.push({ type: "remove", lineNum: currentLineNum, text: pLine.slice(1) });
+      currentLineNum += 1;
+    } else if (pLine.startsWith("+")) {
+      added += 1;
+      lines.push({ type: "add", lineNum: currentLineNum, text: pLine.slice(1) });
+    } else if (pLine.startsWith(" ")) {
+      lines.push({ type: "context", lineNum: currentLineNum, text: pLine.slice(1) });
+      currentLineNum += 1;
+    }
+  }
+
+  return {
+    path: filePath,
+    op: "apply_patch",
+    added,
+    removed,
+    lines,
+  };
+}
+
+export function buildWriteDiff(filePath, previousText, newText) {
+  const newLines = isString(newText) ? newText.split("\n") : [];
+  const oldLines = isString(previousText) ? previousText.split("\n") : [];
+
+  if (oldLines.length === 0 || (oldLines.length === 1 && oldLines[0] === "")) {
+    const sampleCount = Math.min(newLines.length, 6);
+    const lines = [];
+    for (let i = 0; i < sampleCount; i++) {
+      lines.push({ type: "add", lineNum: i + 1, text: newLines[i] });
+    }
+    return {
+      path: filePath,
+      op: "write",
+      added: newLines.length,
+      removed: 0,
+      lines,
+    };
+  }
+
+  const sampleCount = Math.min(newLines.length, 6);
+  const lines = [];
+  for (let i = 0; i < sampleCount; i++) {
+    lines.push({ type: "add", lineNum: i + 1, text: newLines[i] });
+  }
+  return {
+    path: filePath,
+    op: "write",
+    added: newLines.length,
+    removed: oldLines.length,
+    lines,
+  };
+}