pi-supernova 0.8.2 → 0.9.1

package/src/output/outcome.js

@@ -0,0 +1,91 @@
+import {isString} from '../shared/decode.js';
+import {truncateChars,formatBoundedStringArray,isStringArray} from './format.js';
+
+function result(text, details) {
+  return { content: [{ type: "text", text }], details };
+}
+
+function logsBlock(outcome, tail = "") {
+  if (!outcome.logs?.length && !outcome.logTruncated) return "";
+
+  return `\n--- logs${outcome.logTruncated ? " [logs truncated]" : ""}\n${outcome.logs?.join("\n") ?? ""}${tail}`;
+}
+
+function mutationText(outcome) {
+  const m = outcome.mutations;
+
+  if (!m) return "";
+  const external = m.external ? "; external calls attempted=" + m.external + ", their side effects cannot be rolled back" : "";
+  const uncertain = m.pendingCommits || m.recoveryFailed ? "; filesystem outcome uncertain: inspect disk and any recovery backups before retrying" : "";
+
+  return "\nmutations: committed=" + m.committed + " rolledBack=" + m.rolledBack + " (file versions)" + external + uncertain;
+}
+
+function mutationReceipts(trace) {
+  if (!Array.isArray(trace)) return "";
+
+  return trace
+    .filter(row => row?.ok && (row.name === "write" || row.name === "edit") && isString(row.resultText) && row.resultText)
+    .map(row => row.resultText)
+    .join("\n");
+}
+
+// Corrective hint, emitted only when a turn actually split. Independent work
+// belongs in one program: a split cannot use the single prewarmed worker and pays
+// one extra spawn per sibling. Costs nothing until it fires, so it needs no room in
+// the tool definition.
+function splitTurnHint(outcome) {
+  return outcome.overlappedTurn ? ` (${outcome.overlappedTurn} supernova calls ran at once; independent work belongs in one program)` : "";
+}
+
+function errorText(outcome, call) {
+  return `error #${call} ${outcome.wallMs}ms${outcome.returnTruncated ? " [output truncated]" : ""}${mutationText(outcome)}${splitTurnHint(outcome)}
+error: ${outcome.error}${logsBlock(outcome)}`;
+}
+
+function successText(outcome, call) {
+  const truncated = outcome.returnTruncated ? " [return truncated]" : "";
+  const hint = outcome.undefinedReturn ? " (no return statement; add `return` to get a value)" : "";
+  const m = outcome.mutations;
+  const showMutations = m && (m.committed || m.rolledBack || m.external || m.pendingCommits || m.recoveryFailed) ? mutationText(outcome) : "";
+
+  return `ok #${call} ${outcome.wallMs}ms${truncated}${showMutations}${splitTurnHint(outcome)}${logsBlock(outcome, "\n--- result")}\n${outcome.resultText}${hint}`;
+}
+
+function fitOutput(outcome, call, limit, format) {
+  let text = format(outcome, call);
+
+  if (text.length <= limit) return text;
+  outcome.returnTruncated = true;
+  const wrapper = format({ ...outcome, resultText: "", logs: [] }, call);
+  const room = Math.max(256, limit - wrapper.length);
+
+  if (isStringArray(outcome.result)) {
+    outcome.resultText = formatBoundedStringArray(outcome.result, room);
+  } else if (isString(outcome.resultText) && outcome.resultText.length > room) {
+    outcome.resultText = truncateChars(outcome.resultText, room, "output").text;
+  }
+
+  text = format(outcome, call);
+
+  return text.length <= limit ? text : truncateChars(text, limit, "output").text;
+}
+
+function attachReceipts(outcome, trace) {
+  if (outcome.ok && outcome.result === undefined) {
+    const receipts = mutationReceipts(trace);
+
+    if (receipts) {
+      outcome.resultText = receipts;
+      outcome.undefinedReturn = false;
+    }
+  }
+}
+
+function throwIfFailed(outcome, visible, response) {
+  if (outcome.ok) return response;
+  const error = new Error(visible);
+  Object.defineProperty(error,"supernovaResult",{value:response});
+  throw error;
+}
+export { result, errorText, successText, fitOutput, attachReceipts, throwIfFailed };

package/src/runtime/batch-input.js

@@ -0,0 +1,68 @@
+import {isObject,isString} from '../shared/decode.js';
+
+function assertProgramEntry(p, defaults = {}) {
+  const source = p?.code === undefined && p?.file === undefined ? defaults : p;
+  if (!objectData(p) || Object.keys(p).some(key => !["code", "file", "data"].includes(key)) || !validProgramSource(source)) {
+    throw new Error("each program requires code OR file (own or shared), with optional data; no nested batches or per-entry timeouts; no programs ran");
+  }
+}
+
+const objectData = value => isObject(value) && !Array.isArray(value);
+
+function applyBatchDefaults(parsed, mergeData) {
+  if (mergeData && !objectData(parsed.data)) throw new Error("mergeData requires top-level object data; no programs ran");
+  const source = parsed.code !== undefined ? {code:parsed.code} : parsed.file !== undefined ? {file:parsed.file} : {};
+
+  return parsed.programs.map(program => {
+    assertProgramEntry(program, source);
+    const entry = program.code === undefined && program.file === undefined ? {...source,...program} : program;
+
+    if (mergeData) {
+      if (program.data !== undefined && !objectData(program.data)) throw new Error("mergeData requires object data in every explicit entry; no programs ran");
+      // Shallow own-property overlay, including literal __proto__ keys. The
+      // runtime snapshots data again per guest; no mutable heap is shared.
+      entry.data = {...parsed.data,...program.data};
+    } else if (program.data === undefined && Object.hasOwn(parsed,"data")) entry.data = parsed.data;
+
+    return entry;
+  });
+}
+
+function parseBatchPayload(params, config) {
+  assertBatchOptions(params);
+  const defaults = Object.fromEntries(["code", "file", "data"].filter(key => params[key] !== undefined).map(key => [key, params[key]]));
+  if (defaults.code !== undefined || defaults.file !== undefined) assertProgramEntry(defaults);
+  for (const p of params.programs) assertProgramEntry(p, defaults);
+  // Validate before serialization and again after snapshotting: toJSON may change an entry.
+  return applyBatchDefaults(snapshotBatch(params, defaults, config), params.mergeData === true);
+}
+
+function batchTimeoutMs(params, config) {
+  const requestedTimeout = params.timeoutMs === undefined ? config.timeoutMs : Number(params.timeoutMs);
+
+  if (!Number.isFinite(requestedTimeout) || requestedTimeout <= 0) throw new Error("program batch timeoutMs must be a positive finite number");
+
+  return requestedTimeout;
+}
+
+function validProgramSource(source) {
+  const value = source.code ?? source.file;
+  return (source.code === undefined) !== (source.file === undefined) && isString(value) && value.trim();
+}
+
+function assertBatchOptions(params) {
+  if (!Array.isArray(params.programs) || !params.programs.length || params.programs.length > 32) throw new Error("programs requires 1..32 entries; no programs ran");
+  if (params.mergeData !== undefined && ![true, false].includes(params.mergeData)) throw new Error("mergeData must be boolean; no programs ran");
+}
+
+function snapshotBatch(params, defaults, config) {
+  const hasDefaults = Object.keys(defaults).length > 0;
+  let encoded;
+  try { encoded = JSON.stringify(hasDefaults ? {programs:params.programs,...defaults} : params.programs); }
+  catch { throw new Error("programs and defaults must be JSON-serializable; no programs ran"); }
+  if (encoded.length > (config.maxCodeChars ?? 48000)) throw new Error("programs JSON exceeds the code character budget (including shared code/file/data); no programs ran");
+  const parsed = hasDefaults ? JSON.parse(encoded) : {programs:JSON.parse(encoded)};
+  if (Object.hasOwn(defaults,"data") && !Object.hasOwn(parsed,"data")) throw new Error("data must be JSON-serializable; no programs ran");
+  return parsed;
+}
+export { parseBatchPayload, batchTimeoutMs };

package/src/runtime/guest-api.js

@@ -0,0 +1,281 @@
+import {AsyncLocalStorage} from 'node:async_hooks';
+import {isString,isObject,looksLikePath} from '../shared/decode.js';
+import {truncateChars} from '../output/format.js';
+import {gatherReadArgs,normalizeRead,decodeReadValue,assertReadPaths} from '../contract/read.js';
+import {classifyEdit} from '../contract/edit.js';
+import {normalizeBash} from '../contract/bash.js';
+
+const PER_PATH_HINT = "; use Promise.allSettled(paths.map(path => read(path))) for per-path outcomes";
+
+function unwrapValue(res) {
+  if (res?.ok === false) throw new Error(String(res.value ?? res.error ?? "host tool failed"));
+
+  if ("value" in Object(res)) return res.value;
+
+  return res;
+}
+
+function unwrapRead(res, args) {
+  const value = unwrapValue(res);
+
+  if ((args.complete === true || args.json !== undefined) && res?.truncated) throw new Error("incomplete read: complete:true or json refuses truncated host output");
+
+  return decodeReadItem(args, value, res);
+}
+
+function decodeReadItem(args, value, res) {
+  if (!res?.typed) return decodeReadValue(args, value);
+  // JSON selectors used to cross RPC as separately encoded JSON values. Keep
+  // their mutable results independent, but put the copies in the guest heap.
+  return res.cloneItems ? value.map(item => structuredClone(item)) : value;
+}
+
+/** Keep details/truncated reachable but out of the returned literal unless they carry signal. */
+function leanEnvelope(res) {
+  if (!isObject(res)) return res;
+
+  if ("details" in res) Object.defineProperty(res, "details", { value: res.details, enumerable: false, writable: true });
+
+  for (const key of Object.keys(res)) if (res[key] === undefined) delete res[key];
+
+  if (res.truncated === false) delete res.truncated;
+
+  return res;
+}
+
+function swallow(promise) {
+  promise.catch(() => {});
+
+  return promise;
+}
+
+function throwReadPathError(target, detail) {
+  throw new Error(`read failed for ${target}: ${detail}${PER_PATH_HINT}`);
+}
+
+function missingResolvedIndex(values, paths) {
+  return values.findIndex((value, index) => value?.status === "not_found" && looksLikePath(paths[index]));
+}
+
+function settleReadItem(wave, index, res) {
+  const job = wave[index];
+  if (!job) throw new Error("invalid streamed read index: " + index);
+  wave[index] = null; // Release resolver closures and their potentially large values.
+  try { job.resolve(unwrapRead(res,job.args)); }
+  catch (error) { job.reject(error); }
+}
+
+function settleInlineWave(wave,res,received) {
+  unwrapValue(res);
+  if (received || !Array.isArray(res.items) || res.items.length !== wave.length) throw new Error("invalid batch read response");
+  for (let i=0;i<wave.length;i++) {
+    const error = res.itemErrors?.[i];
+    settleReadItem(wave,i,{...res,ok:!error,value:error ?? res.items[i],items:undefined});
+  }
+}
+
+async function rpcReadWave(rpc, wave) {
+  if (wave.length === 1) {
+    const res = leanEnvelope(await rpc("call",["read",wave[0].args]));
+    settleReadItem(wave,0,res);
+    return;
+  }
+  const args = {...wave[0].args,path:wave.map(job=>job.args.path),_independent:true};
+  let received = 0, last;
+  const onItem = (index,res) => {
+    if (!Number.isInteger(index) || !wave[index] || last?.index === index) throw new Error("invalid streamed read response");
+    received++;
+    // Keep the final read pending until the host RPC/barrier itself has settled.
+    // An awaited batch must never look complete while its host call is running.
+    if (received === wave.length) last = {index,res};
+    else settleReadItem(wave,index,res);
+  };
+  const res = leanEnvelope(await rpc("call",["read",args],onItem));
+  if (res?.streamed) {
+    if (received !== wave.length || !last) throw new Error("incomplete streamed read response");
+    settleReadItem(wave,last.index,last.res);
+    return;
+  }
+  settleInlineWave(wave,res,received);
+}
+
+function rejectReadWave(wave, error) {
+  for (const job of wave) job?.reject(error);
+}
+
+function dispatchReadWaves(pending, pendingReadWaves, rpc) {
+  for (let start=0;start<pending.length;start+=64) {
+    const wave = pending.slice(start,start+64);
+    const delivery = rpcReadWave(rpc,wave).catch(error=>rejectReadWave(wave,error));
+    pendingReadWaves.add(delivery);
+    void delivery.finally(()=>pendingReadWaves.delete(delivery));
+  }
+}
+
+function enqueueCompatibleRead(readState, flushReads, args) {
+  const key = JSON.stringify({ ...args, path: undefined });
+
+  if (readState.queued.length && readState.queued[0].key !== key) flushReads();
+
+  const promise = new Promise((resolve, reject) => {
+    readState.queued.push({ args, key, resolve, reject });
+
+    if (readState.queued.length === 1) queueMicrotask(flushReads);
+  });
+
+  return swallow(promise);
+}
+
+async function readManyPaths(readOne, args, paths) {
+  assertReadPaths(paths);
+  const values = await Promise.all(paths.map(async item => {
+    try { return await readOne({...args,path:item}); }
+    catch (error) { throwReadPathError(item,error.message); }
+  }));
+  const missing = args.resolve ? missingResolvedIndex(values,paths) : -1;
+  if (missing >= 0) throwReadPathError(paths[missing],"not_found");
+  return values;
+}
+
+async function runSpeculation(fn, token, checkpointScope, drainReads, rpc) {
+  let began = false;
+
+  try {
+    await drainReads();
+    await rpc("speculateBegin", []);
+    began = true;
+    const value = await checkpointScope.run(token, fn);
+    await drainReads();
+    await rpc("speculateCommit", []);
+
+    return { ok: true, committed: true, value };
+  } catch (err) {
+    await drainReads();
+
+    if (began) await rpc("speculateRollback", []);
+
+    throw err;
+  }
+}
+
+function formatBashFailure(command, res) {
+  let exitCode;
+
+  try {
+    exitCode = JSON.parse(res.details).exitCode;
+  } catch {}
+
+  const output = String(res.value).trimEnd();
+  const suffix = Number.isInteger(exitCode) ? " (exit " + exitCode + ")" : "";
+
+  return "command failed" + suffix + ": " + truncateChars(command, 240, "command").text + (output ? "\n" + output : "");
+}
+
+function markTruncatedOutput(res, text) {
+  if (res?.truncated && isString(text) && !text.includes("truncated")) return text + "\n…[output truncated]…";
+
+  return text;
+}
+
+export function buildGuestApi(rpc, batchRead) {
+  const checkpointScope = new AsyncLocalStorage();
+  let checkpoint = null;
+
+  const assertScope = () => {
+    const token = checkpointScope.getStore();
+
+    if (token ? token !== checkpoint : checkpoint !== null) throw new Error("await the active edit checkpoint before issuing other commands; completed checkpoints cannot issue commands");
+  };
+
+  // Post calls in submission order. The host alone owns file concurrency and
+  // read/shell/checkpoint barriers; a second guest queue would serialize edits.
+  async function checkpointEdit(fn) {
+    if (checkpoint) throw new Error("edit checkpoints cannot overlap or nest; await the current checkpoint");
+    const token = {};
+    checkpoint = token;
+    try { return await runSpeculation(fn, token, checkpointScope, drainReads, rpc); }
+    finally { checkpoint = null; }
+  }
+
+  // Coalesce already-started compatible reads without rewriting JS control flow.
+  const readState = { queued: [], waves: new Set() };
+
+  function flushReads() {
+    const pending = readState.queued;
+    readState.queued = [];
+    dispatchReadWaves(pending, readState.waves, rpc);
+  }
+
+  async function drainReads() {
+    for (;;) {
+      flushReads();
+      const waves = [...readState.waves];
+
+      if (!waves.length) return;
+      await Promise.allSettled(waves);
+    }
+  }
+
+  const invoke = (name, args) => {
+    assertScope(); flushReads();
+
+    return swallow(rpc("call", [name, args]).then(leanEnvelope));
+  };
+
+  const read = async (p, a, b) => {
+    assertScope();
+    const args = normalizeRead(gatherReadArgs(p, a, b));
+    p = args.path;
+
+    if (Array.isArray(p)) {
+      const values = await readManyPaths(read, args, p);
+      for (const item of p) if (isString(item)) noteReadPath({ path: item }, values);
+
+      return values;
+    }
+
+    const readValue = !batchRead
+      ? unwrapRead(await invoke("read", args), args)
+      : await enqueueCompatibleRead(readState, flushReads, args);
+    noteReadPath(args, readValue);
+
+    return readValue;
+  };
+
+  const readFiles = new Set();
+
+  function noteReadPath(args, value) {
+    if (isString(args.path) && looksLikePath(args.path)) readFiles.add(args.path);
+    if (isObject(value) && isString(value.path) && looksLikePath(value.path)) readFiles.add(value.path);
+  }
+
+  const write = async (p, content) => {
+    const args = isObject(p) ? p : { path: p, content };
+
+    if (args.append !== true && args.replace !== true && isString(args.path) && readFiles.has(args.path)) {
+      throw new Error("file was already read this program; use edit(oldText, newText) or edit(view, ...). write({path,content,replace:true}) replaces anyway");
+    }
+
+    return unwrapValue(await invoke("write", args));
+  };
+
+  const edit = async (p, oldText, newText) => {
+    const classified = classifyEdit(p, oldText, newText);
+
+    if (classified.kind === "checkpoint") return checkpointEdit(classified.fn);
+
+    return unwrapValue(await invoke(classified.command, classified.args));
+  };
+
+  const bash = async (command, opts) => {
+    const args = normalizeBash(command, opts);
+    command = args.command;
+    const res = await invoke("bash", args);
+
+    if (res?.ok === false) throw new Error(formatBashFailure(command, res));
+
+    return markTruncatedOutput(res, unwrapValue(res));
+  };
+
+  return { read, write, edit, bash };
+}