From bb1f3e8eafbb00408b4527acf0352dd52a5dfcba Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 00:26:52 -0400
Subject: [PATCH] docs: document session tool render helpers

---
 src/agents/sessions/tools/limits.ts       |  9 +++++++++
 src/agents/sessions/tools/render-utils.ts | 14 ++++++++++++++
 src/agents/sessions/tools/truncate.ts     |  6 ++++++
 3 files changed, 29 insertions(+)

diff --git a/src/agents/sessions/tools/limits.ts b/src/agents/sessions/tools/limits.ts
index 42c6eda0b450..0bac1608cb4e 100644
--- a/src/agents/sessions/tools/limits.ts
+++ b/src/agents/sessions/tools/limits.ts
@@ -1,3 +1,10 @@
+/**
+ * Byte-limit helpers for session tool stderr/stdout tails.
+ *
+ * Tail storage is byte-bounded but decoded as UTF-8, so truncation avoids
+ * splitting multi-byte characters in display output.
+ */
+/** Normalizes optional positive numeric limits to a finite integer. */
 export function normalizePositiveLimit(value: number | undefined, fallback: number): number {
   if (value === undefined || !Number.isFinite(value)) {
     return fallback;
@@ -5,6 +12,7 @@ export function normalizePositiveLimit(value: number | undefined, fallback: numb
   return Math.max(1, Math.floor(value));
 }
 
+/** Default stderr tail retained for long-running session tools. */
 export const SESSION_TOOL_STDERR_TAIL_BYTES = 64 * 1024;
 
 function decodeUtf8TextTail(buffer: Buffer, maxBytes: number): string {
@@ -25,6 +33,7 @@ function decodeUtf8TextTail(buffer: Buffer, maxBytes: number): string {
   return kept.toReversed().join("");
 }
 
+/** Appends a chunk while retaining only the UTF-8-safe tail within maxBytes. */
 export function appendBoundedTextTail(
   current: string,
   chunk: Buffer | string,
diff --git a/src/agents/sessions/tools/render-utils.ts b/src/agents/sessions/tools/render-utils.ts
index f90173aee988..e0b31e30bf53 100644
--- a/src/agents/sessions/tools/render-utils.ts
+++ b/src/agents/sessions/tools/render-utils.ts
@@ -5,6 +5,13 @@ import type { Theme } from "../../modes/interactive/theme/theme.js";
 import { sanitizeBinaryOutput } from "../../shell-utils.js";
 import { stripAnsi } from "../../utils/ansi.js";
 
+/**
+ * Rendering helpers for session tool output in the TUI.
+ *
+ * These helpers normalize paths/text/image fallbacks before tool results are
+ * styled or truncated by higher-level renderers.
+ */
+/** Shortens paths under the current home directory for display. */
 export function shortenPath(path: unknown): string {
   if (typeof path !== "string") {
     return "";
@@ -16,6 +23,7 @@ export function shortenPath(path: unknown): string {
   return path;
 }
 
+/** Returns a display string for string/nullish values, or null for unsupported values. */
 export function str(value: unknown): string | null {
   if (typeof value === "string") {
     return value;
@@ -26,14 +34,17 @@ export function str(value: unknown): string | null {
   return null;
 }
 
+/** Replaces tabs with stable spaces so terminal layout does not shift by tab stop. */
 export function replaceTabs(text: string): string {
   return text.replace(/\t/g, "   ");
 }
 
+/** Normalizes raw terminal output before display. */
 export function normalizeDisplayText(text: string): string {
   return text.replace(/\r/g, "");
 }
 
+/** Extracts text output and image placeholders from a tool result. */
 export function getTextOutput(
   result:
     | { content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> }
@@ -53,6 +64,7 @@ export function getTextOutput(
 
   const caps = getCapabilities();
   if (imageBlocks.length > 0 && (!caps.images || !showImages)) {
+    // When inline images are unavailable, preserve visible evidence that media was returned.
     const imageIndicators = imageBlocks
       .map((img) => {
         const mimeType = img.mimeType ?? "image/unknown";
@@ -69,11 +81,13 @@ export function getTextOutput(
   return output;
 }
 
+/** Minimal shape shared by renderers that carry typed tool details. */
 export type ToolRenderResultLike<TDetails> = {
   content: (TextContent | ImageContent)[];
   details: TDetails;
 };
 
+/** Formats the invalid-argument marker with the active theme. */
 export function invalidArgText(theme: Pick<Theme, "fg">): string {
   return theme.fg("error", "[invalid arg]");
 }
diff --git a/src/agents/sessions/tools/truncate.ts b/src/agents/sessions/tools/truncate.ts
index fba875838306..c0678cc083de 100644
--- a/src/agents/sessions/tools/truncate.ts
+++ b/src/agents/sessions/tools/truncate.ts
@@ -1,3 +1,9 @@
+/**
+ * Session tool truncation facade.
+ *
+ * Re-exports the shared harness truncation utilities so session tools and agent
+ * harness rendering use one byte/line truncation contract.
+ */
 export {
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,