Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

feat(core): truncated tool output keeps a tail window next to the head (#432)

Yaowei Zheng85bf42bc4c3c
diff --git a/changelog/unreleased/2026-08-23-tool-output-tail-window.md b/changelog/unreleased/2026-08-23-tool-output-tail-window.md
new file mode 100644
index 00000000..0bfd9444
--- /dev/null
+++ b/changelog/unreleased/2026-08-23-tool-output-tail-window.md
@@ -0,0 +1,60 @@
+# Truncated tool output keeps a tail window next to the head
+
+- **Date:** 2026-08-23
+- **Type:** feature
+- **Scope:** `core`, `docs`
+- **PR:** [#432](https://github.com/Prism-Shadow/penguin-harness/pull/432)
+
+[中文版](2026-08-23-tool-output-tail-window.zh.md)
+
+Tool output that exceeds `maxOutputLength` used to keep the first `maxOutputLength`
+characters and drop everything after them. For command output — the common way to exceed
+the budget — the most informative part is usually the end: the test verdict, the error,
+the last lines before exit. The model saw a head full of passing noise and had to read
+the recovery file to learn how the run ended.
+
+The budget now splits in half. The head window streams live exactly as before; text past
+it is withheld into a fixed-capacity rolling tail. At finalization, output that stayed
+within the budget is flushed verbatim — a complete result whose later part simply arrives
+at completion — while over-budget output ends as head, a counting marker, and the last
+tail window:
+
+```
+<first half of the budget>
+[output truncated: kept first 8000 and last 8000 of 913482 chars]
+<last half of the budget>
+[output archived: <session scratchpad>/truncated-tool-output/exec_command-<hash>.log]
+```
+
+The marker's total is new signal: the model can judge from `C` whether opening the
+recovery file is worth a call at all. The 50/50 split mirrors the archive file's own
+head/tail rule and is a single constant.
+
+## Unchanged
+
+- The streaming invariant holds: streamed deltas still concatenate to exactly the complete
+ `tool_call_output`, truncation included. The marker, tail, terminal note (e.g. exit
+ code), and archive note are all emitted as compensating deltas at finalization.
+- The recovery archive is untouched: same trigger, same 8 MiB − 1 per-call bound, same
+ file format, same lifecycle with the Session scratchpad.
+- `maxOutputLength <= 0` still disables the budget entirely, and standalone SDK embedders
+ without a Session scratchpad keep truncation-only behavior — now with the tail window.
+
+## Details
+
+- Both cuts are UTF-16 surrogate-safe: the head window never closes on a pairable high
+ surrogate (the character is withheld and reunites with its low half in the flush), and a
+ tail window never starts with a severed low surrogate. Visible output no longer shows a
+ replacement character at the cut.
+- Output that ends past the head window but within the budget now reaches the stream at
+ finalization rather than live. Only that band's delivery timing changes; its content is
+ complete and unmarked.
+- The truncation marker moved from the appended notes into the content, between the two
+ windows, and its wording changed from `exceeded N chars` to
+ `kept first H and last T of C chars`. Frontends render tool output as plain text, so no
+ renderer changes are needed; old Traces keep the old marker and render as before.
+- A compatibility tool that returns one complete message gets the same windows applied to
+ that message.
+
+Design: the head/tail contract and the recovery archive are recorded in the design specs
+([penguin-harness-design #54](https://github.com/Prism-Shadow/penguin-harness-design/pull/54)).
diff --git a/changelog/unreleased/2026-08-23-tool-output-tail-window.zh.md b/changelog/unreleased/2026-08-23-tool-output-tail-window.zh.md
new file mode 100644
index 00000000..4ac3af5b
--- /dev/null
+++ b/changelog/unreleased/2026-08-23-tool-output-tail-window.zh.md
@@ -0,0 +1,36 @@
+# 截断的工具输出在头部之外保留尾窗
+
+- **Date:** 2026-08-23
+- **Type:** feature
+- **Scope:** `core`, `docs`
+- **PR:** [#432](https://github.com/Prism-Shadow/penguin-harness/pull/432)
+
+[English](2026-08-23-tool-output-tail-window.md)
+
+工具输出超过 `maxOutputLength` 时,此前只保留前 `maxOutputLength` 个字符、丢弃其后一切。而超预算最常见的命令类输出,最有信息量的部分恰恰在末尾:测试判定、报错、退出前的最后几行。模型看到的是一整段顺利运行的开头噪音,想知道这次运行怎么收场,只能再去读 recovery 文件。
+
+现在预算对半开。头窗照常实时流式转发;超出头窗的文本暂扣进定容滚动尾缓冲。收尾时,未超预算的输出原样补出——结果完整,只是后半段在收尾时到达;超预算的输出则收敛为头窗、带计数的标记与最后一个尾窗:
+
+```
+<预算的前一半>
+[output truncated: kept first 8000 and last 8000 of 913482 chars]
+<预算的后一半>
+[output archived: <session scratchpad>/truncated-tool-output/exec_command-<hash>.log]
+```
+
+标记里的总量是新增的信号:模型据 `C` 即可判断值不值得再花一次调用去读 recovery 文件。对半分镜像 recovery 文件自身的头尾窗规则,单一常量、后续可调。
+
+## 不变的部分
+
+- 流式不变量保持:流式增量拼接仍严格等于完整 `tool_call_output`,截断亦不例外。标记、尾窗、终止注记(如退出码)与归档注记都在收尾时以补偿增量补出。
+- Recovery 归档完全不动:同样的触发条件、同样的单调用 8 MiB − 1 上限、同样的文件格式、同样随 Session scratchpad 的生命周期。
+- `maxOutputLength <= 0` 仍表示完全关闭预算;未配置 Session scratchpad 的独立 SDK 嵌入仍是纯截断行为——只是同样获得尾窗。
+
+## 细节
+
+- 两处切口对 UTF-16 代理对安全:头窗不会终止在可配对的高位代理上(该字符转入暂扣,冲刷时与低位重聚),尾窗也不会以被切断的低位代理开头。可见输出不再在切口处出现替换字符。
+- 结束于头窗之后、预算之内的输出,从实时到达改为收尾时到达。只有这一区间的送达时机变化,内容完整且不带标记。
+- 截断标记从追加注记移入正文、位于两窗之间,措辞由 `exceeded N chars` 改为 `kept first H and last T of C chars`。前端把工具输出当纯文本渲染,无需任何渲染层改动;旧 Trace 保留旧标记、照常渲染。
+- 只返回一条完整消息的兼容工具,对该消息套用同样的双窗。
+
+设计:头尾双窗契约与 recovery 归档已入设计规格([penguin-harness-design #54](https://github.com/Prism-Shadow/penguin-harness-design/pull/54))。
diff --git a/packages/core/src/environment/environment.ts b/packages/core/src/environment/environment.ts
index 3ec6adf3..b34e132d 100644
--- a/packages/core/src/environment/environment.ts
+++ b/packages/core/src/environment/environment.ts
@@ -12,12 +12,14 @@
* The **framing and finalization** of the tool stream is handled uniformly by Environment:
* - Entering execution immediately emits `start`; the tool only needs to yield output deltas
* (its own start/stop are ignored);
- * - Output is truncated online **front-to-back** by maxOutputLength (head is kept, forwarding
- * stops once exceeded); the truncation marker, the tool's self-reported end marker
- * (`ToolResult.note`, e.g. exit code — appended outside the truncation, never lost even when
- * long output is truncated), and timeout/interruption/error markers are all emitted as part
- * of the stream — **the content produced by concatenating streamed chunks matches the full
- * message exactly**;
+ * - Output is bounded online by maxOutputLength as **head and tail windows**: the budget splits
+ * in half, the head window streams live, and text past it is withheld into a fixed-capacity
+ * rolling tail flushed at finalization — verbatim when the total stayed within budget, or as
+ * a truncation marker carrying kept/total counts followed by the last tail window when it did
+ * not. The marker, the tool's self-reported end marker (`ToolResult.note`, e.g. exit code —
+ * appended outside the budget, never lost even when long output is truncated), and
+ * timeout/interruption/error markers are all emitted as part of the stream — **the content
+ * produced by concatenating streamed chunks matches the full message exactly**;
* - Nested session messages carrying an origin marker (e.g. forwarded from run_subagent) pass
* through unchanged, taking no part in this tool's output or finalization;
* - Argument parsing failures, unknown tool names, tool throws, and other exceptions all
@@ -88,6 +90,46 @@ function noteSuffix(base: string, note: string): string {
return base ? `\n${note}` : note;
}
+/** UTF-16 surrogate probes for budget cuts: the visible windows must not end or start mid-pair. */
+function isHighSurrogate(code: number): boolean {
+ return code >= 0xd800 && code <= 0xdbff;
+}
+
+function isLowSurrogate(code: number): boolean {
+ return code >= 0xdc00 && code <= 0xdfff;
+}
+
+/** The truncation marker placed between the kept head and tail windows; the total lets the model judge whether the recovery file is worth reading. */
+function truncationMarker(headLen: number, tailLen: number, totalLen: number): string {
+ return `[output truncated: kept first ${headLen} and last ${tailLen} of ${totalLen} chars]`;
+}
+
+/** Joins visible windows around the marker; empty sides drop out so a zero head budget does not lead with a blank line. */
+function joinVisibleParts(head: string, marker: string, tail: string): string {
+ return [head, marker, tail].filter((part) => part !== "").join("\n");
+}
+
+/**
+ * Bounds one complete string (the compatibility full-message basis) to the visible budget:
+ * head and tail windows around a counting marker, with surrogate pairs kept whole at both cuts.
+ */
+function boundVisible(
+ text: string,
+ headBudget: number,
+ tailBudget: number,
+): { visible: string; truncated: boolean } {
+ const cap = headBudget + tailBudget;
+ if (text.length <= cap) return { visible: text, truncated: false };
+ let head = text.slice(0, headBudget);
+ if (head !== "" && isHighSurrogate(head.charCodeAt(head.length - 1))) head = head.slice(0, -1);
+ let tail = text.slice(text.length - tailBudget);
+ if (tail !== "" && isLowSurrogate(tail.charCodeAt(0))) tail = tail.slice(1);
+ return {
+ visible: joinVisibleParts(head, truncationMarker(head.length, tail.length, text.length), tail),
+ truncated: true,
+ };
+}
+
export class Environment implements EnvironmentInterface {
private readonly workspaceDir: string;
private readonly toolConfig: ToolConfig;
@@ -346,18 +388,31 @@ export class Environment implements EnvironmentInterface {
: null;
timer?.unref?.();
- // Consume the tool stream: content deltas are forwarded after online front-truncation;
- // nested messages pass through; manual iteration to capture the generator's return value.
- let streamed = ""; // Content forwarded so far (<= maxOutputLength)
- let contentLen = 0; // Total length of content produced by the tool (including truncated/discarded parts)
+ // Consume the tool stream: the head window is forwarded live, text past it is withheld into
+ // a bounded rolling tail; nested messages pass through; manual iteration to capture the
+ // generator's return value.
+ // maxOutputLength <= 0 disables the budget entirely (same semantics as timeoutMs).
+ const truncationEnabled = maxOutputLength > 0;
+ const headBudget = truncationEnabled
+ ? Math.floor(maxOutputLength / 2)
+ : Number.POSITIVE_INFINITY;
+ const tailBudget = truncationEnabled ? maxOutputLength - headBudget : 0;
+ // Tail window plus slack: one char for the head's surrogate retraction and one more so a
+ // run that ends exactly on the budget boundary never evicts — a within-budget run must
+ // flush its withheld text verbatim.
+ const withheldCapacity = tailBudget + 2;
+ let streamed = ""; // Head window forwarded so far (<= headBudget)
+ let headClosed = false; // Once true, nothing more streams live; all further text is withheld
+ let withheld = ""; // Rolling buffer of text past the head window (<= withheldCapacity)
+ let contentLen = 0; // Total length of content produced by the tool (including evicted parts)
let toolOutput: string | null = null; // Fallback: content basis when the tool produces a full message itself
let selfReported: StopReason | undefined; // Tool's self-reported stop reason (return value takes priority over the full message)
let selfNote: string | null = null; // Tool's self-reported end marker (e.g. exit code), appended outside truncation
let selfImages: string[] | undefined; // Tool's self-reported images (data URL), carried via a single streamed delta and the full message
let thrown: unknown = null;
- // Created lazily on the first over-limit text delta when this Environment has a Session
- // scratchpad. It captures the tool's complete text before Environment drops the overflow,
- // but does not alter the model/frontend stream.
+ // Created lazily on the first delta that takes the total past the budget when this
+ // Environment has a Session scratchpad. It captures the tool's complete text before the
+ // rolling tail evicts the middle, but does not alter the model/frontend stream.
let archiveCapture: TruncatedToolOutputCapture | null = null;
const gen = tool.execute(args, {
workspaceDir: this.workspaceDir,
@@ -392,29 +447,60 @@ export class Environment implements EnvironmentInterface {
// Only takes delta content; start/stop are ignored (framing is uniformly handled by Environment).
if (p.event_type !== "delta" || !p.output) continue;
contentLen += p.output.length;
- const exceedsVisibleLimit = maxOutputLength > 0 && contentLen > maxOutputLength;
- if (exceedsVisibleLimit && this.truncatedToolOutputArchive) {
+ if (
+ truncationEnabled &&
+ contentLen > maxOutputLength &&
+ this.truncatedToolOutputArchive
+ ) {
if (!archiveCapture) {
archiveCapture = this.truncatedToolOutputArchive.startCapture();
- // `streamed` is the exact prefix already accepted before this delta. Appending it
- // once, then every complete current/future delta, reconstructs the pre-truncation
- // tool text without changing what is forwarded.
+ // `streamed` then `withheld` is exactly the tool text accepted before this delta:
+ // forwarding stops for good once the head window closes, so the two segments are
+ // contiguous. Appending them once, then every complete current/future delta,
+ // reconstructs the pre-truncation tool text without changing what is forwarded.
archiveCapture.append(streamed);
+ archiveCapture.append(withheld);
}
archiveCapture.append(p.output);
}
- // maxOutputLength <= 0 means truncation is disabled (same semantics as timeoutMs).
- const room =
- maxOutputLength > 0 ? maxOutputLength - streamed.length : Number.POSITIVE_INFINITY;
- if (room > 0) {
- const chunk = p.output.length > room ? p.output.slice(0, room) : p.output;
- streamed += chunk;
- // Rebuild the delta: tool_call_id is uniformly enforced by Environment, never trusting the tool's own value.
- yield partialToolCallOutput({
- eventType: "delta",
- output: chunk,
- toolCallId,
- });
+ let rest = p.output;
+ if (!headClosed) {
+ const room = headBudget - streamed.length;
+ if (rest.length < room) {
+ streamed += rest;
+ // Rebuild the delta: tool_call_id is uniformly enforced by Environment, never trusting the tool's own value.
+ yield partialToolCallOutput({
+ eventType: "delta",
+ output: rest,
+ toolCallId,
+ });
+ rest = "";
+ } else {
+ headClosed = true;
+ let chunk = rest.slice(0, room);
+ // The closed head must not end on a pairable high surrogate: its low half would
+ // otherwise sit across the marker or in the dropped middle. Withholding it keeps
+ // the pair whole — the finalization flush reunites the two halves whenever the
+ // boundary region survives.
+ if (chunk !== "" && isHighSurrogate(chunk.charCodeAt(chunk.length - 1))) {
+ chunk = chunk.slice(0, -1);
+ }
+ if (chunk !== "") {
+ streamed += chunk;
+ yield partialToolCallOutput({
+ eventType: "delta",
+ output: chunk,
+ toolCallId,
+ });
+ }
+ rest = rest.slice(chunk.length);
+ }
+ }
+ if (rest !== "") {
+ withheld += rest;
+ if (withheld.length > withheldCapacity) {
+ withheld = withheld.slice(withheld.length - withheldCapacity);
+ }
}
} else if (p.type === "tool_call_output") {
// Fallback: if the tool still produces a full message, use it as the basis for content and stop reason (not needed under the new contract).
@@ -450,15 +536,28 @@ export class Environment implements EnvironmentInterface {
}
// Uniform finalization. Content basis = the tool's self-produced full message (fallback
- // path) or the already-forwarded delta; after front-truncating to the cap, the truncation
- // marker and interruption/timeout/error markers are appended in turn, all made up via
- // streamed deltas — streamed concatenation == the full message.
- const contentBase = toolOutput ?? streamed;
- const capped =
- maxOutputLength > 0 && contentBase.length > maxOutputLength
- ? contentBase.slice(0, maxOutputLength)
- : contentBase;
- const truncated = capped.length < contentBase.length || contentLen > streamed.length;
+ // path) or the forwarded head plus the withheld tail. A within-budget run flushes the
+ // withheld text verbatim; an over-budget run keeps the head and tail windows around a
+ // counting marker. Markers and notes are then appended in turn, all made up via streamed
+ // deltas — streamed concatenation == the full message.
+ let visible: string;
+ let truncated: boolean;
+ if (toolOutput !== null) {
+ ({ visible, truncated } = boundVisible(toolOutput, headBudget, tailBudget));
+ } else if (!truncationEnabled || contentLen <= maxOutputLength) {
+ // The rolling buffer never evicts within budget, so this is the complete tool text.
+ visible = streamed + withheld;
+ truncated = false;
+ } else {
+ let tail = withheld.slice(withheld.length - tailBudget);
+ if (tail !== "" && isLowSurrogate(tail.charCodeAt(0))) tail = tail.slice(1);
+ visible = joinVisibleParts(
+ streamed,
+ truncationMarker(streamed.length, tail.length, contentLen),
+ tail,
+ );
+ truncated = true;
+ }
// Freeze the tool's terminal facts before auxiliary archive I/O. A user abort arriving
// while the file is being written must not reclassify an already-finished tool.
const aborted =
@@ -479,7 +578,6 @@ export class Environment implements EnvironmentInterface {
let stopReason: StopReason;
const notes: string[] = [];
if (truncated) {
- notes.push(`[output truncated: exceeded ${maxOutputLength} chars]`);
if (archiveResult?.status === "saved") {
const archivePath = modelVisiblePath(archiveResult.path);
if (archiveResult.archiveTruncated) {
@@ -494,9 +592,9 @@ export class Environment implements EnvironmentInterface {
notes.push(`[output archive failed: ${archiveResult.code}]`);
}
}
- // The tool's self-reported end marker (e.g. exit code): appended outside the truncation —
- // if treated as a content delta it would get cut off once long output hits the cap, and the
- // model would misread a command that failed after printing lots of output as successful.
+ // The tool's self-reported end marker (e.g. exit code): appended outside the budget — as a
+ // content delta it could be evicted from the tail window by trailing output, and the model
+ // would misread a command that failed after printing lots of output as successful.
if (selfNote) {
notes.push(selfNote);
}
@@ -515,20 +613,16 @@ export class Environment implements EnvironmentInterface {
// The tool's reply must never be empty: an empty tool_result leaves the model unable to
// tell "silent success" apart from "call failed", and some Providers outright reject empty
// content blocks.
- if (capped === "" && notes.length === 0) {
+ if (visible === "" && notes.length === 0) {
notes.push(TOOL_EMPTY_NOTE);
}
const noteText = notes.join("\n");
- const fullOutput = noteText ? appendNote(capped, noteText) : capped;
-
- // Compensating content delta: if nothing was streamed, emit the whole thing at once; on the
- // fallback path, emit the portion of the full message beyond the already-streamed prefix
- // (if the tool is internally inconsistent, the full message wins — no further reconciliation).
- let compensation = "";
- if (streamed === "") compensation = capped;
- else if (toolOutput !== null && capped.startsWith(streamed)) {
- compensation = capped.slice(streamed.length);
- }
+ const fullOutput = noteText ? appendNote(visible, noteText) : visible;
+
+ // Compensating content delta: everything in the visible content beyond the already-forwarded
+ // head — the withheld flush, the marker plus the tail window, or a fallback full message (if
+ // the tool is internally inconsistent, the full message wins — no further reconciliation).
+ const compensation = visible.startsWith(streamed) ? visible.slice(streamed.length) : "";
if (compensation) {
yield partialToolCallOutput({
eventType: "delta",
@@ -539,7 +633,7 @@ export class Environment implements EnvironmentInterface {
if (noteText) {
yield partialToolCallOutput({
eventType: "delta",
- output: noteSuffix(capped, noteText),
+ output: noteSuffix(visible, noteText),
toolCallId,
});
}
diff --git a/packages/core/test/environment.test.ts b/packages/core/test/environment.test.ts
index a92764f0..3e845b61 100644
--- a/packages/core/test/environment.test.ts
+++ b/packages/core/test/environment.test.ts
@@ -257,7 +257,7 @@ describe("Environment.executeTool — edit file", () => {
});
describe("Environment.executeTool — maxOutputLength truncation", () => {
- it("keeps standalone Environment's legacy truncation behavior without archive config", async () => {
+ it("keeps standalone Environment truncation-only (head and tail windows, no archive) without scratchpad config", async () => {
const env = new Environment({
workspaceDir: tmp,
toolConfig: makeToolConfig(execTool({ maxOutputLength: 5 })),
@@ -272,11 +272,12 @@ describe("Environment.executeTool — maxOutputLength truncation", () => {
}),
);
const output = (messages[messages.length - 1]!.payload as { output: string }).output;
- expect(output).toContain("[output truncated: exceeded 5 chars]");
+ // Budget 5 splits into a 2-char head and a 3-char tail around the counting marker.
+ expect(output).toBe("ab\n[output truncated: kept first 2 and last 3 of 26 chars]\nxyz");
expect(output).not.toContain("[output archived:");
});
- it("truncates front-to-back, archives the received output, and keeps stream == complete", async () => {
+ it("keeps head and tail windows, archives the received output, and keeps stream == complete", async () => {
const maxOutputLength = 50;
const env = new Environment({
workspaceDir: tmp,
@@ -297,15 +298,20 @@ describe("Environment.executeTool — maxOutputLength truncation", () => {
const last = messages[messages.length - 1]!;
expect((last.payload as { type?: string }).type).toBe("tool_call_output");
const output = (last.payload as { output: string }).output;
- // Truncates front-to-back: the head is kept, and the truncation marker is appended at the
- // tail (the marker does not count toward the limit).
+ // The budget splits into head and tail windows around a marker carrying kept and total
+ // counts (the marker and notes do not count toward the limit).
expect(output.startsWith("1\n2\n3\n")).toBe(true);
- const marker = `[output truncated: exceeded ${maxOutputLength} chars]`;
- expect(output).toContain(marker);
- expect(output.indexOf(marker)).toBe(maxOutputLength + 1);
+ const marker = output.match(/\[output truncated: kept first 25 and last 25 of (\d+) chars\]/);
+ expect(marker).not.toBeNull();
+ expect(output.indexOf(marker![0])).toBe(26); // right after the 25-char head + newline
+ // The tail window surfaces the end of the run without reading the archive.
+ expect(output).toContain("100000");
const savedPath = recoveryPath(output);
expect(savedPath).toBeDefined();
- expect(await readFile(savedPath!, "utf8")).toMatch(/100000\r?\n$/);
+ const archived = await readFile(savedPath!, "utf8");
+ expect(archived).toMatch(/100000\r?\n$/);
+ // The marker's total equals the full text the archive preserved (ASCII: chars == bytes).
+ expect(Number(marker![1])).toBe(archived.length);
// Even when truncated, concatenating the streamed deltas == the complete content (the
// excess part is never forwarded).
const streamed = messages
@@ -383,7 +389,12 @@ describe("Environment.executeTool — maxOutputLength truncation", () => {
stop_reason?: string;
};
expect(complete.stop_reason).toBe("completed");
- expect(complete.output.startsWith(expected.slice(0, maxOutputLength))).toBe(true);
+ expect(complete.output.startsWith(expected.slice(0, 25))).toBe(true);
+ expect(complete.output).toContain(
+ `[output truncated: kept first 25 and last 25 of ${expected.length} chars]`,
+ );
+ // The visible tail window carries the end of the output.
+ expect(complete.output).toContain("\nEND\n");
const savedPath = recoveryPath(complete.output);
expect(savedPath).toBeDefined();
if (process.platform === "win32") {
@@ -597,6 +608,8 @@ describe("Environment.executeTool — maxOutputLength truncation", () => {
);
const complete = messages[messages.length - 1]!.payload as { output: string };
expect(complete.output).toContain("head and tail kept");
+ // The visible tail window ends with the intact trailing surrogate pair.
+ expect(complete.output).toContain("-END-🐧");
const savedPath = recoveryPath(complete.output);
expect(savedPath).toBeDefined();
const archived = await readFile(savedPath!, "utf8");
@@ -647,7 +660,12 @@ describe("Environment.executeTool — maxOutputLength truncation", () => {
const savedPath = recoveryPath(complete.output);
expect(savedPath).toBeDefined();
expect(await readFile(savedPath!, "utf8")).toBe(source);
- expect(complete.output.startsWith(source.slice(0, 20))).toBe(true);
+ // The full-message basis gets the same head/tail windows as the streamed path.
+ expect(complete.output.startsWith(source.slice(0, 10))).toBe(true);
+ expect(complete.output).toContain(
+ `[output truncated: kept first 10 and last 10 of ${source.length} chars]`,
+ );
+ expect(complete.output).toContain("-END");
expect(complete.stop_reason).toBe("completed");
const streamed = messages
.filter(
@@ -664,6 +682,117 @@ describe("Environment.executeTool — maxOutputLength truncation", () => {
delete BUILTIN_TOOL_FACTORIES[NAME];
}
});
+
+ it("flushes withheld text verbatim when the total stays within budget", async () => {
+ const NAME = "__band_tool__";
+ BUILTIN_TOOL_FACTORIES[NAME] = (definition) => ({
+ name: NAME,
+ definition,
+ async *execute(_args, ctx) {
+ for (const piece of ["alpha-", "beta-", "gamma"]) {
+ yield partialToolCallOutput({
+ eventType: "delta",
+ output: piece,
+ toolCallId: ctx.toolCallId,
+ });
+ }
+ },
+ });
+ try {
+ const sessionScratchpadDir = path.join(tmp, "scratch");
+ const env = new Environment({
+ workspaceDir: tmp,
+ toolConfig: {
+ customTools: [{ name: NAME, description: "band", permission: "r", maxOutputLength: 20 }],
+ mcpServers: [],
+ },
+ sessionScratchpadDir,
+ });
+ const messages = await collect(
+ env.executeTool({
+ toolCall: toolCall({ name: NAME, arguments: "{}", toolCallId: "band" }),
+ }),
+ );
+ const complete = messages[messages.length - 1]!.payload as {
+ output: string;
+ stop_reason?: string;
+ };
+ // 16 chars: past the 10-char head window but within the 20-char budget. The part past the
+ // head arrives as a finalization flush — complete result, no marker, no archive.
+ expect(complete.output).toBe("alpha-beta-gamma");
+ expect(complete.stop_reason).toBe("completed");
+ await expect(
+ access(path.join(sessionScratchpadDir, "truncated-tool-output")),
+ ).rejects.toThrow();
+ const streamed = messages
+ .filter(
+ (m) =>
+ (m.payload as { type?: string }).type === "partial_tool_call_output" &&
+ (m.payload as { event_type?: string }).event_type === "delta",
+ )
+ .map((m) => (m.payload as { output?: string }).output ?? "")
+ .join("");
+ expect(streamed).toBe(complete.output);
+ } finally {
+ delete BUILTIN_TOOL_FACTORIES[NAME];
+ }
+ });
+
+ it("keeps surrogate pairs whole at both window cuts", async () => {
+ const NAME = "__surrogate_cut_tool__";
+ // Budget 8 → 4-char head, 4-char tail. The first delta ends exactly at the head window with
+ // a high surrogate; its low half arrives in the next delta together with the overflow.
+ const deltas = ["abc\ud83d", `\udc27${"x".repeat(20)}`];
+ BUILTIN_TOOL_FACTORIES[NAME] = (definition) => ({
+ name: NAME,
+ definition,
+ async *execute(_args, ctx) {
+ for (const piece of deltas) {
+ yield partialToolCallOutput({
+ eventType: "delta",
+ output: piece,
+ toolCallId: ctx.toolCallId,
+ });
+ }
+ },
+ });
+ try {
+ const env = new Environment({
+ workspaceDir: tmp,
+ toolConfig: {
+ customTools: [
+ { name: NAME, description: "surrogate", permission: "r", maxOutputLength: 8 },
+ ],
+ mcpServers: [],
+ },
+ sessionScratchpadDir: path.join(tmp, "scratch"),
+ });
+ const messages = await collect(
+ env.executeTool({
+ toolCall: toolCall({ name: NAME, arguments: "{}", toolCallId: "surrogate" }),
+ }),
+ );
+ const complete = messages[messages.length - 1]!.payload as { output: string };
+ // The pairable high surrogate is withheld instead of closing the head, so the visible
+ // result carries no half characters; the dropped pair stays intact in the archive.
+ expect(complete.output).toContain("[output truncated: kept first 3 and last 4 of 25 chars]");
+ expect(/[\ud800-\udfff]/.test(complete.output)).toBe(false);
+ const savedPath = recoveryPath(complete.output);
+ expect(savedPath).toBeDefined();
+ expect(await readFile(savedPath!, "utf8")).toBe("abc🐧" + "x".repeat(20));
+ const streamed = messages
+ .filter(
+ (m) =>
+ (m.payload as { type?: string }).type === "partial_tool_call_output" &&
+ (m.payload as { event_type?: string }).event_type === "delta",
+ )
+ .map((m) => (m.payload as { output?: string }).output ?? "")
+ .join("");
+ expect(streamed).toBe(complete.output);
+ } finally {
+ delete BUILTIN_TOOL_FACTORIES[NAME];
+ }
+ });
});
describe("Environment.executeTool — relaxed tool contract", () => {
diff --git a/packages/core/test/mcp-tools.test.ts b/packages/core/test/mcp-tools.test.ts
index 71801598..d4fc60f5 100644
--- a/packages/core/test/mcp-tools.test.ts
+++ b/packages/core/test/mcp-tools.test.ts
@@ -221,7 +221,9 @@ describe("MCP over stdio — per-server budgets and interruption", () => {
try {
const final = finalPayload(await runTool(env, "mcp__fx__spam", {}));
expect(final.stop_reason).toBe("completed");
- expect(final.output).toBe("x".repeat(100) + "\n[output truncated: exceeded 100 chars]");
+ expect(final.output).toBe(
+ `${"x".repeat(50)}\n[output truncated: kept first 50 and last 50 of 500 chars]\n${"x".repeat(50)}`,
+ );
} finally {
env.dispose();
}
diff --git a/packages/docs/content/tools.en.md b/packages/docs/content/tools.en.md
index 6526e648..d5eca9e1 100644
--- a/packages/docs/content/tools.en.md
+++ b/packages/docs/content/tools.en.md
@@ -30,7 +30,7 @@ interface ToolExecutionContext {
interface ToolResult {
stopReason?: StopReason; // the tool's self-reported terminal state (lowest priority, see below)
- note?: string; // terminal marker appended outside the truncation window (e.g. exit code)
+ note?: string; // terminal marker appended outside the output budget (e.g. exit code)
images?: string[]; // data-URL images, appended after the text output
}
```
@@ -38,22 +38,22 @@ interface ToolResult {
A tool only yields incremental `partial_tool_call_output` deltas; the Environment handles the close-out centrally:
- streaming framing (start / stop) and `tool_call_id` threading;
-- timeout merging, and head-kept truncation once output exceeds `maxOutputLength` (default 16000 characters);
+- timeout merging, and head+tail-window truncation once output exceeds `maxOutputLength` (default 16000 characters): the budget splits in half, the head window streams live, and the last tail window arrives at finalization after a `[output truncated: kept first H and last T of C chars]` marker — the total C tells the model whether the recovery file is worth reading; output that ends past the head window but within the budget is flushed verbatim at finalization instead, with no marker;
- stop_reason priority: user interrupt > timeout > tool throw > tool self-report;
- never-empty output (`[no output]` is substituted when a tool produced nothing);
-- `note` (e.g. the exit code) and images are appended outside the truncation window, so the terminal marker survives even when long output is cut.
+- `note` (e.g. the exit code) and images are appended outside the output budget, so the terminal marker survives even when long output is cut.
Tools and the Environment never throw into the engine: errors collapse into `tool_call_output` messages the model can read and react to. See the [OmniMessage Protocol](/omni-message) for message structure.
### Recovering oversized output
-When tool text in an Agent Session exceeds `maxOutputLength`, the model and Web/CLI still receive the same head window, truncation marker, and terminal marker, and the streaming invariant that user-visible output equals model-visible output does not change. Environment also appends a short archive status/path note outside that visible-output cap and saves a Session-owned recovery file. The file is exact within the per-call archive budget and otherwise contains bounded head/tail windows. This is the complete text **received by Environment**: a producer such as a command or subagent session may already have replaced overflow with an `[..., N chars of earlier output dropped ...]` marker in its own bounded unread buffer, and the downstream archive cannot recover text lost before that point.
+When tool text in an Agent Session exceeds `maxOutputLength`, the model and Web/CLI still receive the same head and tail windows, counting truncation marker, and terminal marker, and the streaming invariant that user-visible output equals model-visible output does not change. Environment also appends a short archive status/path note outside that visible-output cap and saves a Session-owned recovery file. The file is exact within the per-call archive budget and otherwise contains bounded head/tail windows. This is the complete text **received by Environment**: a producer such as a command or subagent session may already have replaced overflow with an `[..., N chars of earlier output dropped ...]` marker in its own bounded unread buffer, and the downstream archive cannot recover text lost before that point.
The Agent can inspect ordinary multiline archives with the existing `read_file` (`offset` / `limit`). For byte tails or very long lines, it must construct a targeted shell command such as `rg` / `tail`; no dedicated retrieval tool is added. The note carries a plain absolute path, always the last element inside the bracket. On Windows it is written with forward slashes: `exec_command` runs through (Git) Bash and Node's fs APIs accept them, so one spelling works in JSON tool arguments and shell commands alike; POSIX paths pass through unchanged, and Session paths are ordinary absolute paths (never `\\?\`-prefixed), so the separator swap is lossless. As with any path, quote it inside shell commands when it contains spaces. The same spelling rule covers every path core composes for the model — the system prompt's App Data Dir / CWD lines, `[attached image/file: …]` lines and the goal-file line (`modelVisiblePath` in the SDK).
Recovery files live under the Session's `scratchpad/<session-id>/truncated-tool-output/`, are created only after actual truncation, and use private permissions where the platform supports them. One call stores at most 8 MiB (the production byte limit is one byte lower so `read_file` remains below its 8 MiB scan cap); larger output keeps bounded head/tail windows in the file with an explicit middle-gap marker. The limit is per call only: a Session has no aggregate archive byte or file-count quota, and concurrent captures independently retain up to one call's budget. Files remain readable across Tasks, runtime disposal, and Session resume until explicit Session deletion removes the entire scratchpad; no separate archive cleanup lifecycle is added.
-Recovery files contain the unredacted tool text received by Environment. Accidentally reading credentials or other sensitive data can therefore increase local at-rest retention from the visible head window to the archive budget. Trace does not duplicate those bytes, but it records the same absolute Session path shown to the model and Web/CLI, exposing the host's data-root layout. Archive-write failure never changes the original tool's `stop_reason`; the visible note and stderr warning carry only a short error code (and stderr's tool name), not the path or raw error message.
+Recovery files contain the unredacted tool text received by Environment. Accidentally reading credentials or other sensitive data can therefore increase local at-rest retention from the visible windows to the archive budget. Trace does not duplicate those bytes, but it records the same absolute Session path shown to the model and Web/CLI, exposing the host's data-root layout. Archive-write failure never changes the original tool's `stop_reason`; the visible note and stderr warning carry only a short error code (and stderr's tool name), not the path or raw error message.
## Configuration fields
diff --git a/packages/docs/content/tools.zh.md b/packages/docs/content/tools.zh.md
index 29501d2e..e55017d4 100644
--- a/packages/docs/content/tools.zh.md
+++ b/packages/docs/content/tools.zh.md
@@ -30,7 +30,7 @@ interface ToolExecutionContext {
interface ToolResult {
stopReason?: StopReason; // 工具自报终态(优先级最低,见下)
- note?: string; // 追加在截断范围之外的终止标记(如退出码)
+ note?: string; // 追加在输出预算之外的终止标记(如退出码)
images?: string[]; // data URL 图像,附加在文本输出之后
}
```
@@ -38,22 +38,22 @@ interface ToolResult {
工具本身只需 yield 增量的 `partial_tool_call_output`,收尾由 Environment 集中处理:
- 流式分帧(start / stop)与 `tool_call_id` 贯穿;
-- 超时归并;输出超过 `maxOutputLength`(默认 16000 字符)时截断,保留开头;
+- 超时归并;输出超过 `maxOutputLength`(默认 16000 字符)时按头尾双窗截断:预算对半开,头窗照常流式转发,尾窗在收尾时随 `[output truncated: kept first H and last T of C chars]` 标记补出——总量 C 供模型判断是否值得读 recovery 文件;超出头窗但未超预算的输出则在收尾时原样补出、不加标记;
- stop_reason 按优先级归并:用户中断 > 超时 > 工具抛错 > 工具自报;
- 输出永不为空:没有任何输出时补 `[no output]`;
-- `note`(如退出码)与图像附加在截断范围之外,长输出被截断时终止标记不会丢失。
+- `note`(如退出码)与图像附加在输出预算之外,长输出被截断时终止标记不会丢失。
工具与 Environment 从不向引擎抛异常:错误一律折叠为 `tool_call_output` 消息,交给模型阅读并调整下一步。消息结构见 [OmniMessage 协议](/omni-message)。
### 过长输出恢复
-Agent Session 中的工具文本超过 `maxOutputLength` 时,模型与 Web/CLI 仍只收到相同的头部窗口、截断提示与终止标记,「用户所见 = 模型所见」的流式契约也保持不变。Environment 还会在该可见输出上限之外追加一条简短的归档状态/路径 note,并保存归该 Session 所有的 recovery 文件:单次归档预算内保存完整文本,超出预算则保存有界头尾。这里的「完整」特指 **Environment 实际收到的文本**:命令或子 Agent Session 等生产者可能已在自身的有界未读缓冲区中用 `[..., N chars of earlier output dropped ...]` 标记替换溢出内容,下游归档无法恢复在此之前已经丢失的原文。
+Agent Session 中的工具文本超过 `maxOutputLength` 时,模型与 Web/CLI 仍收到相同的头尾窗口、带计数的截断标记与终止标记,「用户所见 = 模型所见」的流式契约也保持不变。Environment 还会在该可见输出上限之外追加一条简短的归档状态/路径 note,并保存归该 Session 所有的 recovery 文件:单次归档预算内保存完整文本,超出预算则保存有界头尾。这里的「完整」特指 **Environment 实际收到的文本**:命令或子 Agent Session 等生产者可能已在自身的有界未读缓冲区中用 `[..., N chars of earlier output dropped ...]` 标记替换溢出内容,下游归档无法恢复在此之前已经丢失的原文。
普通多行归档可用现有 `read_file`(`offset` / `limit`)查看;若要读取字节级尾部或超长单行,Agent 必须自行构造定向的 `rg` / `tail` 等 Shell 命令,不新增专用读取工具。note 中的路径是普通绝对路径,恒为括号内最后一个元素。Windows 上统一写成正斜杠:`exec_command` 经 (Git) Bash 执行、Node 的 fs API 也接受正斜杠,同一拼写在 JSON 工具参数与 Shell 命令中通用;POSIX 路径原样透传,且 Session 路径都是普通绝对路径(不会带 `\\?\` 前缀),分隔符替换无损。含空格的路径在 Shell 命令中照常引用即可。同一拼写规则覆盖 core 产出给模型的全部路径——系统提示词的 App Data Dir / CWD 行、`[attached image/file: …]` 行与 Goal file 行(SDK 中的 `modelVisiblePath`)。
Recovery 文件位于该 Session 的 `scratchpad/<session-id>/truncated-tool-output/`,仅在确实发生截断时创建;平台支持时使用仅当前用户可读写的私有权限。单次调用最多保存 8 MiB(生产字节上限少 1 byte,以保持低于 `read_file` 的 8 MiB 扫描上限);更大的输出在文件中保留有界头尾并写明中间被截。该限制仅针对单次调用:一个 Session 没有归档总字节数或文件数配额,并发捕获也各自最多保留一份单调用预算。文件跨 Task、运行时释放和 Session 恢复保持可读,直到用户明确删除 Session 时由现有路径连同整个 scratchpad 一起移除;不新增单独的归档清理生命周期。
-Recovery 文件保存 Environment 收到的未经脱敏的工具文本。误读凭据或其他敏感数据会使本地静态留存量从可见头部扩大到归档预算。Trace 不重复保存这些正文,但会记录模型与 Web/CLI 看到的同一个绝对 Session 路径,因此会暴露宿主的数据根目录布局。归档写入失败不改变原工具的 `stop_reason`;双方可见的 note 与 stderr 警告只携带简短错误码(stderr 另含工具名),不携带路径或原始错误消息。
+Recovery 文件保存 Environment 收到的未经脱敏的工具文本。误读凭据或其他敏感数据会使本地静态留存量从可见窗口扩大到归档预算。Trace 不重复保存这些正文,但会记录模型与 Web/CLI 看到的同一个绝对 Session 路径,因此会暴露宿主的数据根目录布局。归档写入失败不改变原工具的 `stop_reason`;双方可见的 note 与 stderr 警告只携带简短错误码(stderr 另含工具名),不携带路径或原始错误消息。
## 配置字段