pi-supernova 0.1.0 → 0.3.0

package/index.js

@@ -1,10 +1,10 @@
 import { createRequire } from "node:module";
-import { isString, isFunction } from "./decode.js";
-import { buildCatalog, searchCatalog, describeTool, mergeNativeToolDefinitions } from "./catalog.js";
-import { loadConfig } from "./config.js";
-import { createHostBridge } from "./host-bridge.js";
-import { runGuestProgram, warmGuestWorker } from "./runtime.js";
-import { renderSupernovaCall, renderSupernovaResult } from "./render.js";
+import { isString, isFunction } from "./src/shared/decode.js";
+import { loadConfig } from "./src/config/config.js";
+import { createHostBridge } from "./src/bridge/host-bridge.js";
+import { truncateChars } from "./src/output/format.js";
+import { runGuestProgram, warmGuestWorker, stopWarmGuestWorker } from "./src/runtime/runtime.js";
+import { renderSupernovaCall, renderSupernovaResult } from "./src/ui/render.js";
 
 export { renderSupernovaCall, renderSupernovaResult };
 
@@ -26,37 +26,36 @@ function result(text, details) {
   return { content: [{ type: "text", text }], details };
 }
 
-const PROGRESS_FRAME_MS = 40;
+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.
  */
-function progressEmitter(onUpdate) {
+export function progressEmitter(onUpdate) {
   if (!isFunction(onUpdate)) return Object.assign(() => {}, { flush() {} });
   let pending = null;
   let timer = null;
-  const send = (trace) => {
-    try {
-      onUpdate({ content: [{ type: "text", text: "" }], details: { trace, running: true } });
-    } catch {}
-  };
-  const flush = () => {
+  let lastSent = -Infinity;
+  const send = () => {
     timer = null;
     if (pending === null) return;
-    const trace = pending;
+    // 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;
-    send(trace);
+    lastSent = performance.now();
+    try {
+      onUpdate({ content: [{ type: "text", text: "" }], details: { trace, running: true } });
+    } catch {}
   };
   const emit = (trace) => {
-    if (timer === null && pending === null) {
-      send(trace);
-      timer = setTimeout(flush, PROGRESS_FRAME_MS);
-      return;
-    }
     pending = trace;
-    if (timer === null) timer = setTimeout(flush, PROGRESS_FRAME_MS);
+    if (timer !== null) return;
+    const wait = PROGRESS_FRAME_MS - (performance.now() - lastSent);
+    if (wait <= 0) send();
+    else timer = setTimeout(send, wait);
   };
   emit.flush = () => {
     if (timer !== null) clearTimeout(timer);
@@ -66,10 +65,8 @@ function progressEmitter(onUpdate) {
   return emit;
 }
 
-function sessionStats({ programs, returnedChars, collapsedChars, collapsedRuns }) {
-  const total = returnedChars + collapsedChars;
-  const pct = total ? Math.round((collapsedChars / total) * 100) : 0;
-  return `this session: ${programs} programs · ~${Math.round(returnedChars / 4)} tokens returned · ~${Math.round(collapsedChars / 4)} already-seen tokens not re-sent (${pct}%, ${collapsedRuns} runs)`;
+function sessionStats({ programs, returnedChars }) {
+  return `this session: ${programs} programs · ${returnedChars} output characters (not token counts)`;
 }
 
 function logsBlock(outcome, tail = "") {
@@ -85,25 +82,40 @@ function successText(outcome, call) {
   const hint = outcome.undefinedReturn ? " (no return statement; add `return` to get a value)" : "";
   return `ok #${call} ${outcome.wallMs}ms${truncated}${logsBlock(outcome, "\n--- result")}\n${outcome.resultText}${hint}`;
 }
-const TOOL_DESCRIPTION = `Run one JavaScript program that composes host tools. Async body or arrow; \`return\` a small shaped value (compact literal, capped; strings raw; console.log is captured).
+const TOOL_DESCRIPTION = `Run one JavaScript program with four familiar commands: read, write, edit, bash. Use an async body or arrow. Return a small value; strings stay raw.
 
-Globals (async):
-read(path|paths, offset?, limit?) → text | text[] · read(path, {about}) → whole-file outline, only relevant bodies expanded
-write(path, text) · edit(path, oldText, newText) → post-edit lines (no re-read needed) · patch(path, unifiedDiff)
-bash(cmd, {cwd?, timeoutMs?}) → output, throws on non-zero exit · exec(cmd, argv?) quotes argv
-evidence(query, {k?}) → {spans: [{path, lines, name, text}]} top-K spans that answer a question; use before read
-snap(query, root?) → {path, line, signature, context} · surface(path) → {items: [{name, kind, line}]}
-nova.call(name, args) → {ok, value} for any host tool · nova.callMany([{name, args}]) parallel when read-only
-nova.search(query) → [{name, description}] · nova.describe(name) → parameters · nova.has(name) sync
-parallel(thunks) · pipeline(items, ...stages)
+Native commands (async):
+read(path|paths, offset?, limit?) → file text or text[]; read(directory) → directory entries
+read("symbol or question") → locate and open source in one call, without an index; selected file text stays raw
+read({query, resolve:true}) → {status,path,line,lines,text,complete,nextOffset?} for a direct resolve→edit handoff
+read(path, {about: question}) → relevant file bodies, or source selection inside a directory
+read({query, evidence:true}) → ranked evidence; read({path, outline:true}) → structural declarations
+write(path, text) → write a file
+edit(path, oldText, newText) → post-edit lines, checks, and references
+edit(async () => {...}) → filesystem checkpoint: commit on success, rollback on throw; no shell commands, nesting, or concurrent outside commands
+bash(command, {cwd?, timeoutMs?}) → bounded output; throws on non-zero exit
+bash({command, args:[...]}) → literal argv without shell expansion of arguments
 
-Already-seen lines collapse to "⋯ N lines same as #12 · path:a–b ⋯"; read(path, a, n) re-shows them.`;
+Only found selects and opens a file. Uncertain reads return ambiguous, not_found, or incomplete with no selected path. Use resolve:true for structured status checks; narrow the directory with path+about when uncertain.
+Object arguments also work: read({path, offset?, limit?, about?, outline?, evidence?, resolve?}), edit({path, edits:[{oldText,newText}]}), edit({path,patch}), write({path,content}), bash({command,timeoutMs?}).
+Independent read starts batch automatically. Mutations preserve submission order. Plain reads remain self-contained; oversized reads provide continuation offsets. Return only what the model needs. console.log is captured.`;
 
 export default function piSupernova(pi) {
-  const config = loadConfig();
+  registerCodeMode(pi);
+}
+
+// Shared entry used by both host adapters and direct engine integration.
+export function registerCodeMode(pi) {
+  // Local cache residency cannot establish what remains in the model's context.
+  const config = { ...loadConfig(), seenWindow: 0 };
   let cwd = process.cwd();
-  let catalog = [];
   let programSeq = 0;
+  let stopped = false;
+  let warmTimer;
+  function cancelWarmTimer() {
+    if (warmTimer !== undefined) clearImmediate(warmTimer);
+    warmTimer = undefined;
+  }
 
   const bridge = createHostBridge({
     pi,
@@ -112,36 +124,21 @@ export default function piSupernova(pi) {
   });
 
   function refreshCatalog(target = bridge) {
-    const tools = target.refreshTools();
-    const discoverable = mergeNativeToolDefinitions(tools, target.externalNames())
-      .filter(tool => target.isCallable(tool.name))
-      .map(tool => {
-        const schema = tool.parameters;
-        try {
-          if (isFunction(schema?.toJsonSchema)) return { ...tool, parameters: schema.toJsonSchema() };
-          if (schema && !schema.type && pi.zod?.toJSONSchema && (schema._zod || schema._def)) {
-            return { ...tool, parameters: pi.zod.toJSONSchema(schema, { io: "input" }) };
-          }
-          return tool;
-        } catch (error) {
-          return { ...tool, parameters: undefined, schemaError: error.message };
-        }
-      });
-    catalog = buildCatalog(discoverable, config.excludeTools || []);
-    return catalog;
+    // Refresh executors and permissions, not a model-facing catalogue. Guest
+    // programs cannot dispatch arbitrary tools or consume their schemas.
+    return target.refreshTools();
   }
 
-  function makeNovaApi(runBridge, runCatalog, cancel) {
+  function makeNovaApi(runBridge, cancel) {
     return {
-      search: async (query, limit) => searchCatalog(runCatalog, query, Number.isInteger(limit) ? limit : config.maxSearchResults),
-      describe: async (name) => describeTool(runCatalog, name),
       call: (name, args) => runBridge.call(name, args),
       callMany: (calls) => runBridge.callMany(calls),
-      speculateBegin: () => runBridge.beginSpeculation(),
-      speculateCommit: () => runBridge.commitSpeculation(),
-      speculateRollback: () => runBridge.rollbackSpeculation(),
-      names: () => runCatalog.map(tool => tool.name),
+      speculateBegin: () => runBridge.barrier(() => runBridge.beginSpeculation()),
+      speculateCommit: () => runBridge.barrier(() => runBridge.commitSpeculation()),
+      speculateRollback: () => runBridge.barrier(() => runBridge.rollbackSpeculation()),
+      names: () => ["read", "edit", "write", "bash"],
       batchRead: runBridge.supportsBatchRead(),
+      nativeArgv: runBridge.supportsNativeArgv?.() === true,
       cancel,
     };
   }
@@ -150,14 +147,14 @@ export default function piSupernova(pi) {
     name: "supernova",
     label: "Supernova",
     description: TOOL_DESCRIPTION,
-    promptSnippet: "Compose host tools in one JavaScript program",
+    promptSnippet: "Use read, write, edit, and bash in one program",
     promptGuidelines: [
-      "Use supernova for multi-step tool work: loops, filtering, parallel reads, read→edit chains. To understand code: evidence(question) across the repo, or read(path, {about: question}) for one file: full structure, only relevant bodies expanded. Plain read(path) only for lines you will edit. Return a compact shaped value; keep raw tool output inside the program.",
+      "Use read, write, edit, and bash inside supernova. Start with read(question), or read(directory, {about: question}) for scoped source selection. A source question already opens the selected file; do not issue a redundant read. Use read({query,resolve:true}) and check status before editing its path. Explicit about/outline/evidence reads remain available when needed. Return a compact value.",
     ],
     parameters: Type.Object({
       code: Type.String({ description: "JavaScript program: async body or arrow function." }),
       timeoutMs: Type.Optional(Type.Integer({ minimum: 1000, description: "Hard timeout in ms." })),
-    }),
+    }, { required: ["code"] }),
     // One self-owned result frame is shared by Pi and OMP; renderCall stays empty
     // so separate call/result slots cannot duplicate the lifecycle card.
     renderShell: "self",
@@ -165,6 +162,7 @@ export default function piSupernova(pi) {
     renderCall: renderSupernovaCall,
     renderResult: renderSupernovaResult,
     async execute(_id, params, signal, onUpdate, ctx) {
+      cancelWarmTimer();
       const runCwd = ctx?.cwd || cwd;
       const runController = new AbortController();
       const abortRun = () => runController.abort(signal?.reason);
@@ -182,18 +180,18 @@ export default function piSupernova(pi) {
       const started = performance.now();
       let outcome;
       try {
-        const runCatalog = refreshCatalog(runBridge);
+        refreshCatalog(runBridge);
         runBridge.beginSpeculation();
         outcome = await runGuestProgram({
           code: params?.code,
-          nova: makeNovaApi(runBridge, runCatalog, abortRun),
+          nova: makeNovaApi(runBridge, abortRun),
           config: { ...config, timeoutMs: Number.isInteger(params?.timeoutMs) ? params.timeoutMs : config.timeoutMs },
           signal: runController.signal,
           onTimeout: abortRun,
         });
         runBridge.close();
         if (outcome.ok) {
-          if (runBridge.getOverlayDepth() !== 1) throw new Error("program ended with an unfinished nova.speculate branch; await it before returning");
+          if (runBridge.getOverlayDepth() !== 1) throw new Error("program ended with an unfinished edit checkpoint; await it before returning");
           await runBridge.commitSpeculation();
         }
         else runBridge.rollbackSpeculation();
@@ -206,18 +204,36 @@ export default function piSupernova(pi) {
         runBridge.setCallListener(null);
         emitProgress.flush();
         signal?.removeEventListener("abort", abortRun);
+        // Prepare one pristine worker during the model's next decision. Never
+        // recycle a worker that has executed arbitrary guest JavaScript.
+        cancelWarmTimer();
+        if (!stopped && !runController.signal.aborted) {
+          // Deliver the result before paying for another Worker constructor.
+          warmTimer = setImmediate(() => {
+            warmTimer = undefined;
+            if (!stopped && !runController.signal.aborted) warmGuestWorker(config).catch(() => {});
+          });
+          warmTimer.unref?.();
+        }
       }
       const trace = runBridge.getTrace();
       const text = outcome.ok ? successText(outcome, call) : errorText(outcome, call);
-      return result(runBridge.ledger.dedupe(text, call), {
+      const bounded = truncateChars(text, config.maxReturnChars, "output").text;
+      const visible = runBridge.ledger.dedupe(bounded, call);
+      if (!outcome.ok) throw new Error(visible);
+      const response = result(visible, {
         ok: outcome.ok, error: outcome.error, wallMs: outcome.wallMs,
         returnTruncated: outcome.returnTruncated, logTruncated: outcome.logTruncated,
         logs: outcome.logs, result: outcome.result, trace,
       });
+      if (outcome.images?.length) response.content.push(...outcome.images);
+      return response;
     },
   });
 
+  pi.on("session_shutdown", () => { stopped = true; cancelWarmTimer(); return stopWarmGuestWorker(); });
   pi.on("session_start", (_event, ctx) => {
+    stopped = false;
     if (ctx && isString(ctx.cwd) && ctx.cwd) cwd = ctx.cwd;
     // A new session is a new model context: nothing has been seen yet.
     bridge.bindCallContext(ctx);
@@ -232,12 +248,9 @@ export default function piSupernova(pi) {
     handler: async (_args, ctx) => {
       bridge.bindCallContext(ctx);
       refreshCatalog();
-      const external = bridge.externalNames().filter(bridge.isCallable).sort();
-      const natives = Object.keys(bridge.natives).filter(name => bridge.isCallable(name) && !external.includes(name)).sort();
+      const commands = ["read", "edit", "write", "bash"].filter(bridge.isCallable);
       const lines = [
-        `pi-supernova catalog: ${catalog.length} tools`,
-        `external tools: ${external.length ? external.join(", ") : "(none)"}`,
-        `native adapters: ${natives.join(", ")}`,
+        `Supernova CodeMode: ${commands.join(", ")}`,
         `timeoutMs=${config.timeoutMs} maxCallResultChars=${config.maxCallResultChars} maxReturnChars=${config.maxReturnChars} maxBridgeCalls=${config.maxBridgeCalls} maxHeapMb=${config.maxHeapMb}`,
         sessionStats(bridge.ledger.stats),
       ];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-supernova",
-  "version": "0.1.0",
-  "description": "Dual-host CodeMode for Pi/OMP: progressive tool discovery, result bottleneck, and Amdahl Auto parallel.",
+  "version": "0.3.0",
+  "description": "One CodeMode invocation for Pi and OMP, with four guest commands, automatic read batching and source context.",
   "type": "module",
   "author": "AdityaVG13",
   "license": "MIT",
@@ -24,38 +24,15 @@
   "exports": "./index.js",
   "files": [
     "index.js",
-    "catalog.js",
-    "host-bridge.js",
-    "bottleneck.js",
-    "parallel.js",
-    "runtime.js",
-    "guest-worker.js",
-    "repo-index.js",
-    "evidence.js",
-    "fuzzy.js",
-    "outline.js",
-    "ledger.js",
-    "check.js",
-    "search.js",
-    "format.js",
-    "patch.js",
-    "vfs.js",
-    "workspace.js",
-    "config.js",
-    "config.default.json",
+    "src/",
+    "docs/",
     "README.md",
-    "LICENSE",
-    "CHANGELOG.md",
-    "snap.js",
-    "diff.js",
-    "render.js",
-    "render-measure.js",
-    "omp-frame.js",
-    "surface.js",
-    "decode.js"
+    "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs",
+    "test": "node --test tests/*/*.test.mjs",
+    "test:hosts": "node tests/hosts/verify.mjs",
+    "measure": "node tests/efficiency/measure.mjs",
     "prepublishOnly": "npm test && node ../../scripts/preflight.mjs"
   },
   "pi": {
@@ -69,9 +46,13 @@
     ]
   },
   "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
   "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
     "typebox": {
       "optional": true
     }

package/{catalog.js → src/bridge/catalog.js}

@@ -1,16 +1,18 @@
 
-import { isString, isObject } from "./decode.js";
+import { isString, isObject } from "../shared/decode.js";
 
 const NATIVE_TOOL_DEFINITIONS = [
   {
     name: "read",
-    description: "Read UTF-8 workspace files by path, or resolve a concept query to source. Supports path arrays, offset, and limit.",
+    description: "Read files or directories. Source questions locate and open source directly; resolve returns structured source/status without guessing.",
     parameters: { type: "object", properties: {
-      path: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }], description: "Workspace-relative file path, concept query, or array of paths" },
+      path: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }], description: "Workspace-relative file or directory, source question, or array of paths" },
       target: { anyOf: [{ type: "string" }, { type: "array" }], description: "File path/query or array of paths" },
       offset: { type: "number", description: "One-based starting line" },
       limit: { type: "number", description: "Maximum lines to return" },
-      about: { type: "string", description: "Question or symbol: returns the whole file as an outline with only the relevant bodies expanded" },
+      about: { type: "string", description: "Question or symbol: expand file bodies, or locate and open source inside a directory" },
+      query: { type: "string", description: "Source question; optional path scopes the search directory" },
+      resolve: { type: "boolean", description: "Return structured source/status for a direct resolve-to-edit handoff" },
     } },
   },
   {
@@ -28,7 +30,7 @@ const NATIVE_TOOL_DEFINITIONS = [
     parameters: { type: "object", properties: { path: { type: "string" }, patch: { type: "string" } }, required: ["patch"] },
   },
   {
-    name: "snap", description: "Resolve a concept query to the most relevant workspace source location.",
+    name: "snap", description: "Select source with found, ambiguous, not_found, or incomplete status. The read command uses the same engine.",
     parameters: { type: "object", properties: {
       query: { type: "string", description: "Source concept to resolve" },
       path: { type: "string", description: "Optional workspace search root; explicitly targeting a hidden directory includes its hidden files, but Git metadata is always excluded" },
@@ -161,7 +163,7 @@ export function searchCatalog(catalog, query, limit = 12) {
 
 /** Optimal string alignment distance: insert/delete/substitute/adjacent-transpose cost 1. */
 function editDistance(a, b) {
-  const rows = Array.from({ length: a.length + 1 }, (_, i) => [i, ...new Array(b.length).fill(0)]);
+  const rows = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array.from({ length: b.length }, () => 0)]);
   for (let j = 1; j <= b.length; j++) rows[0][j] = j;
   for (let i = 1; i <= a.length; i++) {
     for (let j = 1; j <= b.length; j++) {
@@ -198,7 +200,7 @@ function suggestNames(name, candidates, limit = 3) {
 export function unknownToolMessage(name, candidates) {
   const close = suggestNames(name, candidates);
   const hint = close.length ? ` Did you mean ${close.map((c) => JSON.stringify(c)).join(", ")}?` : "";
-  return `unknown tool "${name}".${hint} Use nova.search("") to list every callable tool.`;
+  return `unknown tool "${name}".${hint} Check the command name and configured tool exclusions.`;
 }
 
 export function describeTool(catalog, name) {