@@ -124,6 +124,8 @@ export interface ShellArgs {
124124 export interface ShellOpts {
125125 /** Maximum output lines before truncation. Default: 1000. */
126126 maxLines?: number;
127+ /** Maximum UTF-8 bytes before truncation. Default: 50_000. */
128+ maxBytes?: number;
127129 /** Abort signal to cancel the command. */
128130 signal?: AbortSignal;
129131 /** Callback for progressive output updates while the command is running. */
@@ -131,6 +133,7 @@ export interface ShellOpts {
131133 }
132134
133135 const DEFAULT_MAX_LINES = 1000;
136+const DEFAULT_MAX_BYTES = 50_000;
134137
135138 /** Format combined stdout/stderr for display in tool results. */
136139 function formatShellOutput(stdout: string, stderr: string): string {
@@ -187,6 +190,7 @@ export async function executeShell(
187190 ): Promise<ToolExecResult> {
188191 const shell = process.env.SHELL || "/bin/sh";
189192 const maxLines = opts?.maxLines ?? DEFAULT_MAX_LINES;
193+ const maxBytes = opts?.maxBytes ?? DEFAULT_MAX_BYTES;
190194
191195 try {
192196 const spawnOpts: Parameters<typeof Bun.spawn>[1] = {
@@ -200,7 +204,11 @@ export async function executeShell(
200204 let stdoutBuf = "";
201205 let stderrBuf = "";
202206 const reportUpdate = (): void => {
203- const output = formatShellOutput(stdoutBuf, stderrBuf);
207+ const output = truncateOutput(
208+ formatShellOutput(stdoutBuf, stderrBuf),
209+ maxLines,
210+ maxBytes,
211+ );
204212 if (!output) {
205213 return;
206214 }
@@ -222,6 +230,7 @@ export async function executeShell(
222230 const output = truncateOutput(
223231 formatShellOutput(stdout.trimEnd(), stderr.trimEnd()),
224232 maxLines,
233+ maxBytes,
225234 );
226235
227236 const isError = exitCode !== 0;
@@ -239,31 +248,159 @@ export async function executeShell(
239248 // Output truncation
240249 // ---------------------------------------------------------------------------
241250
251+/** Build line-limited head/tail segments and their truncation marker. */
252+function buildLineTruncation(
253+ output: string,
254+ maxLines: number,
255+): {
256+ head: string;
257+ tail: string;
258+ marker: string;
259+} | null {
260+ const lines = output.split("\n");
261+ if (lines.length <= maxLines) {
262+ return null;
263+ }
264+
265+ const headCount = Math.ceil(maxLines / 2);
266+ const tailCount = Math.floor(maxLines / 2);
267+ const omitted = lines.length - headCount - tailCount;
268+
269+ return {
270+ head: lines.slice(0, headCount).join("\n"),
271+ tail: lines.slice(lines.length - tailCount).join("\n"),
272+ marker: `\n… truncated ${omitted} lines …\n`,
273+ };
274+}
275+
276+/** Slice the largest UTF-8 prefix that fits within `maxBytes`. */
277+function sliceUtf8Prefix(input: string, maxBytes: number): string {
278+ if (maxBytes <= 0 || input === "") {
279+ return "";
280+ }
281+ let low = 0;
282+ let high = input.length;
283+ while (low < high) {
284+ const mid = Math.ceil((low + high) / 2);
285+ const candidate = input.slice(0, mid);
286+ if (Buffer.byteLength(candidate, "utf8") <= maxBytes) {
287+ low = mid;
288+ } else {
289+ high = mid - 1;
290+ }
291+ }
292+ return input.slice(0, low);
293+}
294+
295+/** Slice the largest UTF-8 suffix that fits within `maxBytes`. */
296+function sliceUtf8Suffix(input: string, maxBytes: number): string {
297+ if (maxBytes <= 0 || input === "") {
298+ return "";
299+ }
300+ let low = 0;
301+ let high = input.length;
302+ while (low < high) {
303+ const mid = Math.ceil((low + high) / 2);
304+ const candidate = input.slice(input.length - mid);
305+ if (Buffer.byteLength(candidate, "utf8") <= maxBytes) {
306+ low = mid;
307+ } else {
308+ high = mid - 1;
309+ }
310+ }
311+ return input.slice(input.length - low);
312+}
313+
314+/** Fit disjoint head/tail segments plus a marker within a UTF-8 byte budget. */
315+function fitSegmentsWithinBytes(
316+ headSource: string,
317+ tailSource: string,
318+ marker: string,
319+ maxBytes: number,
320+): string {
321+ const markerBytes = Buffer.byteLength(marker, "utf8");
322+ if (markerBytes >= maxBytes) {
323+ return sliceUtf8Prefix(headSource, maxBytes);
324+ }
325+
326+ const availableBytes = maxBytes - markerBytes;
327+ const headBudget = Math.ceil(availableBytes / 2);
328+ const tailBudget = Math.floor(availableBytes / 2);
329+
330+ let head = sliceUtf8Prefix(headSource, headBudget);
331+ let tail = sliceUtf8Suffix(tailSource, tailBudget);
332+
333+ const usedBytes =
334+ Buffer.byteLength(head, "utf8") + Buffer.byteLength(tail, "utf8");
335+ let remainingBytes = availableBytes - usedBytes;
336+
337+ if (remainingBytes > 0) {
338+ const expandedHead = sliceUtf8Prefix(
339+ headSource,
340+ headBudget + remainingBytes,
341+ );
342+ remainingBytes -=
343+ Buffer.byteLength(expandedHead, "utf8") - Buffer.byteLength(head, "utf8");
344+ head = expandedHead;
345+ }
346+
347+ if (remainingBytes > 0) {
348+ tail = sliceUtf8Suffix(tailSource, tailBudget + remainingBytes);
349+ }
350+
351+ return head + marker + tail;
352+}
353+
354+/** Truncate output by UTF-8 byte size, preserving head and tail text. */
355+function truncateOutputByBytes(output: string, maxBytes: number): string {
356+ if (Buffer.byteLength(output, "utf8") <= maxBytes) {
357+ return output;
358+ }
359+
360+ return fitSegmentsWithinBytes(
361+ output,
362+ output,
363+ "\n… truncated for size …\n",
364+ maxBytes,
365+ );
366+}
367+
242368 /**
243- * Truncate output to keep head and tail lines with a marker in between.
369+ * Truncate output to keep useful head and tail content within line and byte budgets.
244370 *
245- * If the output has fewer lines than `maxLines`, it is returned unchanged.
246- * Otherwise, keeps roughly half the budget for head lines and half for tail
247- * lines, joined by a truncation marker showing how many lines were omitted.
371+ * The line budget avoids flooding the model with very tall outputs, while the
372+ * byte budget prevents context explosions caused by a small number of very long
373+ * lines.
248374 *
249375 * @param output - The full output string.
250376 * @param maxLines - Maximum number of content lines to keep.
377+ * @param maxBytes - Maximum UTF-8 bytes to keep.
251378 * @returns The (possibly truncated) output string.
252379 */
253-export function truncateOutput(output: string, maxLines: number): string {
380+export function truncateOutput(
381+ output: string,
382+ maxLines: number,
383+ maxBytes: number,
384+): string {
254385 if (!output) return output;
255386
256- const lines = output.split("\n");
257- if (lines.length <= maxLines) return output;
258-
259- const headCount = Math.ceil(maxLines / 2);
260- const tailCount = Math.floor(maxLines / 2);
261- const omitted = lines.length - headCount - tailCount;
387+ const lineTruncation = buildLineTruncation(output, maxLines);
388+ if (!lineTruncation) {
389+ return truncateOutputByBytes(output, maxBytes);
390+ }
262391
263- const head = lines.slice(0, headCount);
264- const tail = lines.slice(lines.length - tailCount);
392+ const lineLimited =
393+ lineTruncation.head + lineTruncation.marker + lineTruncation.tail;
394+ if (Buffer.byteLength(lineLimited, "utf8") <= maxBytes) {
395+ return lineLimited;
396+ }
265397
266- return [...head, `… truncated ${omitted} lines …`, ...tail].join("\n");
398+ return fitSegmentsWithinBytes(
399+ lineTruncation.head,
400+ lineTruncation.tail,
401+ lineTruncation.marker,
402+ maxBytes,
403+ );
267404 }
268405
269406 // ---------------------------------------------------------------------------