pi-supernova 0.5.0 → 0.7.0

package/src/fs/workspace.js

@@ -16,6 +16,9 @@ const realNearest = new Map();
 const PATH_CACHE_MAX = 2048;
 
 export function clearPathCache() {
+  cachedCwd = null;
+  cachedResolvedCwd = null;
+  realRoots.clear();
   realNearest.clear();
 }
 
@@ -64,14 +67,7 @@ export function isTestPath(filePath) {
   return segments.some((s) => TEST_SEGMENTS.has(s)) || /\.(test|spec)\./.test(base);
 }
 
-/** Reject scheme:// and scheme:/ paths. A single-letter drive (C:/) stays a filesystem path. */
-export function assertFilesystemPath(inputPath, opName, allowSessionRead = false) {
-  if (inputPath == null || !isString(inputPath) || !inputPath.trim()) {
-    throw new Error(`${opName} requires path`);
-  }
-
-  const trimmed = inputPath.trim();
-
+function rejectUriPath(trimmed, opName, allowSessionRead) {
   if (/^(?:agent|artifact):\/\//i.test(trimmed)) {
     if (allowSessionRead) return trimmed;
     throw new Error(`${opName} requires a filesystem path; session resource URIs are read-only`);
@@ -79,19 +75,27 @@ export function assertFilesystemPath(inputPath, opName, allowSessionRead = false
 
   const uri = /^([a-zA-Z][a-zA-Z0-9+.-]*):(.*)$/.exec(trimmed);
 
-  if (uri) {
-    const scheme = uri[1];
-    const rest = uri[2];
-    const windowsDrive = scheme.length === 1 && (rest.startsWith("/") || rest.startsWith("\\"));
+  if (!uri) return trimmed;
+  const scheme = uri[1];
+  const rest = uri[2];
+  const windowsDrive = scheme.length === 1 && (rest.startsWith("/") || rest.startsWith("\\"));
 
-    if (!windowsDrive && (rest.startsWith("//") || rest.startsWith("/"))) {
-      throw new Error(`${opName} does not accept ${scheme}: URI paths; use a workspace filesystem path`);
-    }
+  if (!windowsDrive && (rest.startsWith("//") || rest.startsWith("/"))) {
+    throw new Error(`${opName} does not accept ${scheme}: URI paths; use a workspace filesystem path`);
   }
 
   return trimmed;
 }
 
+/** Reject scheme:// and scheme:/ paths. A single-letter drive (C:/) stays a filesystem path. */
+export function assertFilesystemPath(inputPath, opName, allowSessionRead = false) {
+  if (inputPath == null || !isString(inputPath) || !inputPath.trim()) {
+    throw new Error(`${opName} requires path`);
+  }
+
+  return rejectUriPath(inputPath.trim(), opName, allowSessionRead);
+}
+
 export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = false, fresh = false) {
   const trimmed = assertFilesystemPath(inputPath, opName);
   const resolvedCwd = getResolvedCwd(cwd);
@@ -123,101 +127,114 @@ export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = f
   return target;
 }
 
+function commandTimeoutMs(options) {
+  const requestedTimeout = Number(options.timeoutMs === undefined ? 60_000 : options.timeoutMs);
+
+  if (!Number.isFinite(requestedTimeout) || requestedTimeout <= 0) throw new Error("command timeoutMs must be a positive finite number");
+
+  return Math.max(1, Math.min(2_147_483_647, Math.floor(requestedTimeout)));
+}
+
+function spawnCommand(argv, options, cwd) {
+  return spawn(argv[0], argv.slice(1), {
+    cwd, env: options.env ?? process.env, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32",
+  });
+}
+
+function signalProcessTree(child, signal) {
+  if (!child.pid) return;
+
+  if (process.platform === "win32") {
+    const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], { stdio: "ignore" });
+    killer.on("error", () => child.kill(signal));
+  } else {
+    try { process.kill(-child.pid, signal); } catch (err) { if (err.code !== "ESRCH") child.kill(signal); }
+  }
+}
+
+function failCommand(state, error) {
+  if (state.settled) return;
+  state.settled = true;
+  state.cleanup();
+  // Keep bounded diagnostic output when a command times out or is cancelled.
+  error.stdout = state.stdout;
+  error.stderr = state.stderr;
+  error.outputTruncated = state.outputTruncated;
+  const output = [state.stdout, state.stderr].filter(Boolean).join("\n").trimEnd();
+
+  if (output) error.message += "\n" + output;
+
+  if (state.outputTruncated) error.message += "\n[output truncated]";
+  state.reject(error);
+}
+
+function terminateCommand(state, error) {
+  if (state.settled || state.terminationError) return;
+  state.terminationError = error;
+  signalProcessTree(state.child, "SIGTERM");
+  // Keep ownership after the direct child exits: descendants may ignore SIGTERM.
+  state.escalation = setTimeout(() => { signalProcessTree(state.child, "SIGKILL"); failCommand(state, error); }, 150);
+}
+
+function appendCommandOutput(state, current, chunk) {
+  const remaining = Math.max(0, state.maxOutputChars - state.stdout.length - state.stderr.length);
+
+  if (chunk.length > remaining) state.outputTruncated = true;
+
+  return remaining ? current + chunk.slice(0, remaining) : current;
+}
+
+function onCommandClose(state, code, signal) {
+  if (state.settled) return;
+
+  if (state.terminationError) {
+    // A closed pipe alone says nothing about descendants. Only ESRCH proves
+    // the owned POSIX group is gone; otherwise retain the escalation timer.
+    if (process.platform !== "win32" && state.child.pid) {
+      try { process.kill(-state.child.pid, 0); }
+      catch (error) { if (error.code === "ESRCH") failCommand(state, state.terminationError); }
+    }
+
+    return;
+  }
+
+  state.settled = true;
+  state.cleanup();
+  state.resolve({ stdout: state.stdout, stderr: state.stderr, exitCode: code ?? (128 + (constants.signals[signal] ?? 1)), signal, outputTruncated: state.outputTruncated });
+}
+
+function attachCommandIO(state, options, argv, timeoutMs) {
+  const { child } = state;
+  const onAbort = () => terminateCommand(state, new Error("aborted"));
+  state.cleanup = () => {
+    clearTimeout(state.timer);
+    clearTimeout(state.escalation);
+    options.signal?.removeEventListener("abort", onAbort);
+  };
+  state.timer = setTimeout(() => terminateCommand(state, new Error("command timed out after " + timeoutMs + "ms: " + (options.commandLabel ?? argv.join(" ")))), timeoutMs);
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", chunk => { state.stdout = appendCommandOutput(state, state.stdout, chunk); });
+  child.stderr.on("data", chunk => { state.stderr = appendCommandOutput(state, state.stderr, chunk); });
+  child.on("error", error => failCommand(state, error));
+  child.on("close", (code, signal) => onCommandClose(state, code, signal));
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+
+  if (options.signal?.aborted) onAbort();
+}
+
 export async function runCommand(argv, options = {}) {
   options.signal?.throwIfAborted();
   const cwd = options.cwd || process.cwd();
-  const timeoutMs = options.timeoutMs ?? 60_000;
+  const timeoutMs = commandTimeoutMs(options);
   const maxOutputChars = options.maxOutputChars ?? 2 * 1024 * 1024;
 
   return new Promise((resolve, reject) => {
-    const child = spawn(argv[0], argv.slice(1), {
-      cwd, env: options.env ?? process.env, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32",
-    });
-
-    let stdout = "";
-    let stderr = "";
-    let settled = false;
-    let outputTruncated = false;
-    let terminationError;
-    let escalation;
-
-    const cleanup = () => {
-      clearTimeout(timer);
-      clearTimeout(escalation);
-      options.signal?.removeEventListener("abort", onAbort);
-    };
-
-    const fail = error => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      // Keep bounded diagnostic output when a command times out or is cancelled.
-      error.stdout = stdout;
-      error.stderr = stderr;
-      error.outputTruncated = outputTruncated;
-      const output = [stdout, stderr].filter(Boolean).join("\n").trimEnd();
-
-      if (output) error.message += "\n" + output;
-
-      if (outputTruncated) error.message += "\n[output truncated]";
-      reject(error);
-    };
-
-    const signalTree = signal => {
-      if (!child.pid) return;
-
-      if (process.platform === "win32") {
-        const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], { stdio: "ignore" });
-        killer.on("error", () => child.kill(signal));
-      } else {
-        try { process.kill(-child.pid, signal); } catch (err) { if (err.code !== "ESRCH") child.kill(signal); }
-      }
-    };
-
-    const terminate = error => {
-      if (settled || terminationError) return;
-      terminationError = error;
-      signalTree("SIGTERM");
-      // Keep ownership after the direct child exits: descendants may ignore SIGTERM.
-      escalation = setTimeout(() => { signalTree("SIGKILL"); fail(error); }, 150);
-    };
-
-    const onAbort = () => terminate(new Error("aborted"));
-    const timer = setTimeout(() => terminate(new Error("command timed out after " + timeoutMs + "ms: " + (options.commandLabel ?? argv.join(" ")))), timeoutMs);
-
-    const append = (current, chunk) => {
-      const remaining = Math.max(0, maxOutputChars - stdout.length - stderr.length);
-
-      if (chunk.length > remaining) outputTruncated = true;
-
-      return remaining ? current + chunk.slice(0, remaining) : current;
-    };
-
-    child.stdout.setEncoding("utf8");
-    child.stderr.setEncoding("utf8");
-    child.stdout.on("data", chunk => { stdout = append(stdout, chunk); });
-    child.stderr.on("data", chunk => { stderr = append(stderr, chunk); });
-    child.on("error", fail);
-    child.on("close", (code, signal) => {
-      if (settled) return;
-
-      if (terminationError) {
-        // A closed pipe alone says nothing about descendants. Only ESRCH proves
-        // the owned POSIX group is gone; otherwise retain the escalation timer.
-        if (process.platform !== "win32" && child.pid) {
-          try { process.kill(-child.pid, 0); }
-          catch (error) { if (error.code === "ESRCH") fail(terminationError); }
-        }
-
-        return;
-      }
-
-      settled = true;
-      cleanup();
-      resolve({ stdout, stderr, exitCode: code ?? (128 + (constants.signals[signal] ?? 1)), signal, outputTruncated });
-    });
-    options.signal?.addEventListener("abort", onAbort, { once: true });
-
-    if (options.signal?.aborted) onAbort();
+    const child = spawnCommand(argv, options, cwd);
+    attachCommandIO({
+      child, resolve, reject, stdout: "", stderr: "", settled: false,
+      outputTruncated: false, terminationError: undefined, escalation: undefined,
+      maxOutputChars, timer: undefined, cleanup() {},
+    }, options, argv, timeoutMs);
   });
 }

package/src/output/bottleneck.js

@@ -19,7 +19,7 @@ function detailsOf(raw) {
 export function hostResultFailed(raw) {
   const details = detailsOf(raw);
 
-  return raw?.isError === true || details?.ok === false || (Number.isInteger(details?.exitCode) && details.exitCode !== 0);
+  return raw?.isError === true || raw?.ok === false || details?.ok === false || (Number.isInteger(details?.exitCode) && details.exitCode !== 0);
 }
 
 function extractRawString(raw) {
@@ -36,165 +36,269 @@ function extractRawString(raw) {
   return json(raw);
 }
 
+function fitString(input, limit) {
+  let low = 0;
+  let high = Math.min(input.length, limit);
+
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+
+    if (json(truncateChars(input, mid).text).length <= limit) low = mid;
+    else high = mid - 1;
+  }
+
+  return truncateChars(input, low).text;
+}
+
+function assignBounded(out, key, bounded) {
+  if (Array.isArray(out)) out.push(bounded);
+  else Object.defineProperty(out, key, { value: bounded, enumerable: true, configurable: true });
+}
+
+function rollbackBounded(out, key) {
+  if (Array.isArray(out)) out.pop();
+  else delete out[key];
+}
+
+function fitContainer(input, limit) {
+  const out = Array.isArray(input) ? [] : { truncated: true };
+  const entries = Object.entries(input);
+
+  if (!Array.isArray(input)) entries.sort((a, b) => json(a[1]).length - json(b[1]).length);
+
+  for (const [key, child] of entries) {
+    const used = json(out).length;
+    const overhead = Array.isArray(out) ? 1 : json(key).length + 2;
+    const available = limit - used - overhead;
+
+    if (available < 4) break;
+    assignBounded(out, key, fit(child, available));
+
+    if (json(out).length > limit) rollbackBounded(out, key);
+  }
+
+  return out;
+}
+
+function fit(input, limit) {
+  const serialized = json(input);
+
+  if (serialized.length <= limit) return input;
+
+  if (isString(input)) return fitString(input, limit);
+
+  if (!isObject(input) && !Array.isArray(input)) return null;
+
+  return fitContainer(input, limit);
+}
+
 /** Bound JSON before serialization; preserve small scalar fields such as exitCode. */
 function summarizeDetails(value, budget = 2000) {
   const encoded = json(value);
 
   if (encoded.length <= budget) return encoded;
-  const snapshot = JSON.parse(encoded);
 
-  const fit = (input, limit) => {
-    const serialized = json(input);
+  return json(fit(JSON.parse(encoded), budget));
+}
+
+function spill(fullText, config) {
+  try {
+    if (!isString(config.spillDir) || !config.spillDir) return undefined;
+    fs.mkdirSync(config.spillDir, { recursive: true, mode: 0o700 });
+    const file = path.join(config.spillDir, Date.now() + "-" + randomUUID().slice(0, 8) + ".txt");
+    fs.writeFileSync(file, fullText, { encoding: "utf8", mode: 0o600, flag: "wx" });
+
+    return file;
+  } catch {
+    return undefined;
+  }
+}
 
-    if (serialized.length <= limit) return input;
+function batchFromDetails(details) {
+  return details?.batch === true && Array.isArray(details.items) ? details.items : undefined;
+}
 
-    if (isString(input)) {
-      let low = 0;
-      let high = Math.min(input.length, limit);
+function hostImage(raw) {
+  return raw?.content?.find(part => part?.type === "image");
+}
 
-      while (low < high) {
-        const mid = Math.ceil((low + high) / 2);
+function directoryEntriesIfFit(image, details, maxChars) {
+  return image === undefined && details?.directory === true && Array.isArray(details.entries) && json(details.entries).length <= maxChars
+    ? details.entries
+    : undefined;
+}
 
-        if (json(truncateChars(input, mid).text).length <= limit) low = mid;
-        else high = mid - 1;
-      }
+function hostTruncated(capped, details) {
+  return capped.truncated || details?.outputTruncated === true;
+}
 
-      return truncateChars(input, low).text;
-    }
+function hostResultValue(image, directoryEntries, capped) {
+  return image ?? directoryEntries ?? capped.text;
+}
 
-    if (!isObject(input) && !Array.isArray(input)) return null;
-    const out = Array.isArray(input) ? [] : { truncated: true };
-    const entries = Object.entries(input);
+function attachDetails(result, details, batch) {
+  if (details !== undefined) result.details = summarizeDetails(batch ? { ...details, items: undefined } : details);
+}
 
-    if (!Array.isArray(input)) entries.sort((a, b) => json(a[1]).length - json(b[1]).length);
+function boundNonStringItem(item, share) {
+  const encoded = json(item);
 
-    for (const [key, child] of entries) {
-      const used = json(out).length;
-      const overhead = Array.isArray(out) ? 1 : json(key).length + 2;
-      const available = limit - used - overhead;
+  if (encoded.length <= share) return { value: item, used: encoded.length, truncated: false };
+  const bounded = truncateChars(encoded, share, "host-result");
 
-      if (available < 4) break;
-      const bounded = fit(child, available);
+  return { value: bounded.text, used: bounded.text.length, truncated: bounded.truncated };
+}
 
-      if (Array.isArray(out)) out.push(bounded);
-      else Object.defineProperty(out, key, { value: bounded, enumerable: true, configurable: true });
+function boundBatchItem(item, share) {
+  if (item?.type === "image") return { value: item, used: 0, truncated: false };
 
-      if (json(out).length > limit) {
-        if (Array.isArray(out)) out.pop();
-        else delete out[key];
-      }
-    }
+  if (!isString(item)) return boundNonStringItem(item, share);
+  const bounded = truncateChars(item, share, "host-result");
 
-    return out;
-  };
+  return { value: bounded.text, used: bounded.text.length, truncated: bounded.truncated };
+}
 
-  return json(fit(snapshot, budget));
+function boundItemError(error, maxChars, batchLength) {
+  return error == null ? null : truncateChars(String(error), Math.max(1, Math.floor(maxChars / batchLength)), "error").text;
 }
 
-function spill(fullText, config) {
-  if (!isString(config.spillDir) || !config.spillDir) return undefined;
-  fs.mkdirSync(config.spillDir, { recursive: true, mode: 0o700 });
-  const file = path.join(config.spillDir, Date.now() + "-" + randomUUID().slice(0, 8) + ".txt");
-  fs.writeFileSync(file, fullText, { encoding: "utf8", mode: 0o600, flag: "wx" });
+function packageBatchItems(batch, details, maxChars) {
+  const itemErrors = (details.itemErrors ?? []).map(error => boundItemError(error, maxChars, batch.length));
+  let remaining = maxChars;
+  let truncated = false;
+  const items = batch.map((item, index) => {
+    const share = details.independent === true ? maxChars : Math.floor(remaining / (batch.length - index));
+    const bounded = boundBatchItem(item, share);
+    remaining -= bounded.used;
+    truncated ||= bounded.truncated;
+
+    return bounded.value;
+  });
 
-  return file;
+  return { items, itemErrors, truncated };
+}
+
+function attachBatch(result, batch, details, maxChars) {
+  if (!batch) return false;
+  const packed = packageBatchItems(batch, details, maxChars);
+  result.itemErrors = packed.itemErrors;
+  result.items = packed.items;
+
+  return packed.truncated;
+}
+
+function originalBatchChars(batch) {
+  return batch.reduce((sum, item) => sum + (isString(item) ? item.length : json(item).length), 0);
+}
+
+function spillPayload(batch, text) {
+  return batch ? batch.map(item => isString(item) ? item : json(item)).join("\n---\n") : text;
+}
+
+function applySpillFooter(result, text, pointer, maxChars, capped) {
+  const footer = "\n[full output spilled to " + pointer + "]";
+  result.value = footer.length <= maxChars
+    ? truncateChars(text, maxChars - footer.length, "host-result").text + footer
+    : capped.text;
+}
+
+function attachSpill(result, batch, text, config, maxChars, capped) {
+  if (!config.spillDir) return;
+  const pointer = spill(spillPayload(batch, text), config);
+
+  if (!pointer) return;
+  result.spill = pointer;
+
+  if (!batch) applySpillFooter(result, text, pointer, maxChars, capped);
+}
+
+function attachTruncation(result, truncated, batch, text, config, maxChars, capped) {
+  result.truncated = truncated;
+
+  if (!truncated) return;
+  result.originalChars = batch ? originalBatchChars(batch) : text.length;
+  attachSpill(result, batch, text, config, maxChars, capped);
 }
 
 export function packageHostResult(raw, config) {
   const maxChars = config.maxCallResultChars ?? 65536;
   const details = detailsOf(raw);
-  const batch = details?.batch === true && Array.isArray(details.items) ? details.items : undefined;
+  const batch = batchFromDetails(details);
   const text = batch ? "" : extractRawString(raw);
   const capped = truncateChars(text, maxChars, "host-result");
-  let truncated = capped.truncated || details?.outputTruncated === true;
-  const image = raw?.content?.find(part => part?.type === "image");
-  const result = { ok: !hostResultFailed(raw), value: image ?? capped.text, truncated };
+  let truncated = hostTruncated(capped, details);
+  const image = hostImage(raw);
+  const directoryEntries = directoryEntriesIfFit(image, details, maxChars);
+  const result = { ok: !hostResultFailed(raw), value: hostResultValue(image, directoryEntries, capped), truncated };
+  attachDetails(result, details, batch);
+  truncated ||= attachBatch(result, batch, details, maxChars);
+  attachTruncation(result, truncated, batch, text, config, maxChars, capped);
 
-  if (details !== undefined) result.details = summarizeDetails(batch ? { ...details, items: undefined } : details);
-
-  if (batch) {
-    result.itemErrors = (details.itemErrors ?? []).map(error => error == null ? null : truncateChars(String(error), Math.max(1, Math.floor(maxChars / batch.length)), "error").text);
-    let remaining = maxChars;
-    result.items = batch.map((item, index) => {
-      if (item?.type === "image") return item;
-      const bounded = truncateChars(item, details.independent === true ? maxChars : Math.floor(remaining / (batch.length - index)), "host-result");
-      remaining -= bounded.text.length;
-      truncated ||= bounded.truncated;
-
-      return bounded.text;
-    });
-  }
-
-  result.truncated = truncated;
-
-  if (truncated) {
-    result.originalChars = batch ? batch.reduce((sum, item) => sum + String(item).length, 0) : text.length;
+  return result;
+}
 
-    if (config.spillDir) {
-      const pointer = spill(batch ? batch.join("\n---\n") : text, config);
+function collectImage(input, acc) {
+  if (!(input?.type === "image" && isString(input.data) && isString(input.mimeType) && input.mimeType.startsWith("image/"))) return null;
+  const size = Buffer.byteLength(input.data, "base64");
 
-      if (pointer) {
-        result.spill = pointer;
+  if (acc.images.length >= 16 || acc.imageBytes + size > 20 * 1024 * 1024) {
+    acc.imageOverflow = true;
 
-        if (!batch) {
-          const footer = "\n[full output spilled to " + pointer + "]";
-          result.value = footer.length <= maxChars
-            ? truncateChars(text, maxChars - footer.length, "host-result").text + footer
-            : capped.text;
-        }
-      }
-    }
+    return "[image omitted: exceeds 16 attachments or 20 MiB]";
   }
 
-  return result;
+  acc.imageBytes += size;
+  acc.images.push({ type: "image", data: input.data, mimeType: input.mimeType });
+
+  return `[image ${acc.images.length}: ${input.mimeType}]`;
 }
 
-export function packageFinalReturn(value, logs, config) {
-  const images = [];
-  let imageBytes = 0;
-  let imageOverflow = false;
+function collectImages(input, acc) {
+  const replaced = collectImage(input, acc);
 
-  const collect = input => {
-    if (input?.type === "image" && isString(input.data) && isString(input.mimeType) && input.mimeType.startsWith("image/")) {
-      const size = Buffer.byteLength(input.data, "base64");
+  if (replaced !== null) return replaced;
 
-      if (images.length >= 16 || imageBytes + size > 20 * 1024 * 1024) {
-        imageOverflow = true;
+  if (Array.isArray(input)) return input.map(child => collectImages(child, acc));
 
-        return "[image omitted: exceeds 16 attachments or 20 MiB]";
-      }
+  if (isObject(input)) return Object.fromEntries(Object.entries(input).map(([key, child]) => [key, collectImages(child, acc)]));
 
-      imageBytes += size;
-      images.push({ type: "image", data: input.data, mimeType: input.mimeType });
+  return input;
+}
 
-      return `[image ${images.length}: ${input.mimeType}]`;
-    }
+function serializeReturn(value, formatted, maxReturn, imageOverflow) {
+  if (formatted.length <= maxReturn) return { text: formatted, truncated: imageOverflow };
 
-    if (Array.isArray(input)) return input.map(collect);
+  if (Array.isArray(value) && value.length && value.every(isString)) return { text: formatBoundedStringArray(value, maxReturn), truncated: true };
 
-    if (isObject(input)) return Object.fromEntries(Object.entries(input).map(([key, child]) => [key, collect(child)]));
+  return { ...truncateChars(formatted, maxReturn, "return"), truncated: true };
+}
 
-    return input;
-  };
+function clipLogLine(line, maxLogLineChars) {
+  const result = truncateChars(line, maxLogLineChars, "log");
 
-  value = collect(value);
-  const maxReturn = config.maxReturnChars ?? 32000;
-  const formatted = formatReturn(value);
-  const serialized = formatted.length <= maxReturn
-    ? { text: formatted, truncated: imageOverflow }
-    : Array.isArray(value) && value.length && value.every(isString)
-      ? { text: formatBoundedStringArray(value, maxReturn), truncated: true }
-      : { ...truncateChars(formatted, maxReturn, "return"), truncated: true };
+  return { text: result.text, truncated: result.truncated };
+}
+
+function clipLogs(logs, config) {
   const maxLines = config.maxLogLines ?? 100;
   let logTruncated = logs.length > maxLines;
-
   const clipped = logs.slice(0, maxLines).map(line => {
-    const result = truncateChars(line, config.maxLogLineChars ?? 4096, "log");
+    const result = clipLogLine(line, config.maxLogLineChars ?? 4096);
     logTruncated ||= result.truncated;
 
     return result.text;
   });
 
+  return { logs: clipped, logTruncated };
+}
+
+export function packageFinalReturn(value, logs, config) {
+  const acc = { images: [], imageBytes: 0, imageOverflow: false };
+  value = collectImages(value, acc);
+  const maxReturn = config.maxReturnChars ?? 32000;
+  const serialized = serializeReturn(value, formatReturn(value), maxReturn, acc.imageOverflow);
+  const clipped = clipLogs(logs, config);
+
   return { returnValue: serialized.truncated ? serialized.text : value, returnText: serialized.text,
-    returnTruncated: serialized.truncated, logs: clipped, logTruncated, images };
+    returnTruncated: serialized.truncated, logs: clipped.logs, logTruncated: clipped.logTruncated, images: acc.images };
 }