docs: document session tools

steipete · steipete · commit 600a57e60f1e · 2026-06-04T10:03:05.000-04:00
diff --git a/src/agents/sessions/tools/bash.ts b/src/agents/sessions/tools/bash.ts
@@ -1,3 +1,8 @@
+/**
+ * Built-in bash session tool.
+ *
+ * Executes local shell commands with streaming output accumulation and TUI renderers.
+ */
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { Container, Text, truncateToWidth } from "@earendil-works/pi-tui";
diff --git a/src/agents/sessions/tools/edit.ts b/src/agents/sessions/tools/edit.ts
@@ -1,3 +1,8 @@
+/**
+ * Built-in edit session tool.
+ *
+ * Applies exact targeted replacements with queued file mutation, diff previews, and TUI renderers.
+ */
 import { constants } from "node:fs";
 import {
   access as fsAccess,
diff --git a/src/agents/sessions/tools/file-mutation-queue.ts b/src/agents/sessions/tools/file-mutation-queue.ts
@@ -1,3 +1,8 @@
+/**
+ * Per-file mutation queue.
+ *
+ * Serializes edits/writes targeting the same real file while allowing independent files to mutate in parallel.
+ */
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 
diff --git a/src/agents/sessions/tools/find.ts b/src/agents/sessions/tools/find.ts
@@ -1,3 +1,8 @@
+/**
+ * Built-in find session tool.
+ *
+ * Searches files by glob through fd/local operations and returns bounded, renderable results.
+ */
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import path from "node:path";
diff --git a/src/agents/sessions/tools/grep.ts b/src/agents/sessions/tools/grep.ts
@@ -1,3 +1,8 @@
+/**
+ * Built-in grep session tool.
+ *
+ * Searches files with ripgrep/local operations, optional context, and bounded output rendering.
+ */
 import { spawn } from "node:child_process";
 import { readFileSync, statSync } from "node:fs";
 import path from "node:path";
diff --git a/src/agents/sessions/tools/index.ts b/src/agents/sessions/tools/index.ts
@@ -1,3 +1,8 @@
+/**
+ * Session tool public barrel.
+ *
+ * Re-exports built-in tool factories, operation interfaces, contracts, and shared truncation helpers.
+ */
 export {
   type BashSpawnContext,
   type BashSpawnHook,
diff --git a/src/agents/sessions/tools/ls.ts b/src/agents/sessions/tools/ls.ts
@@ -1,3 +1,8 @@
+/**
+ * Built-in ls session tool.
+ *
+ * Lists directory entries through local or injected operations with bounded output rendering.
+ */
 import { existsSync, readdirSync, statSync } from "node:fs";
 import nodePath from "node:path";
 import { Text } from "@earendil-works/pi-tui";
diff --git a/src/agents/sessions/tools/output-accumulator.ts b/src/agents/sessions/tools/output-accumulator.ts
@@ -1,11 +1,16 @@
+/**
+ * Streaming output accumulator for tool execution.
+ *
+ * Keeps bounded display tails in memory while spilling full output to private temp files when needed.
+ */
 import type { WriteStream } from "node:fs";
+import { createPrivateTempWriteStream } from "./private-temp-file.js";
 import {
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
   type TruncationResult,
   truncateTail,
 } from "./truncate.js";
-import { createPrivateTempWriteStream } from "./private-temp-file.js";
 
 export interface OutputAccumulatorOptions {
   maxLines?: number;
diff --git a/src/agents/sessions/tools/path-utils.ts b/src/agents/sessions/tools/path-utils.ts
@@ -1,3 +1,8 @@
+/**
+ * Session tool path normalization helpers.
+ *
+ * Expands user/file URL inputs and resolves read/write paths against the active cwd with macOS filename variants.
+ */
 import { accessSync, constants } from "node:fs";
 import * as os from "node:os";
 import { isAbsolute, resolve as resolvePath } from "node:path";
diff --git a/src/agents/sessions/tools/private-temp-file.ts b/src/agents/sessions/tools/private-temp-file.ts
@@ -1,11 +1,13 @@
+/**
+ * Private temporary file helper for tool output spillover.
+ *
+ * Creates owner-only log files without reusing predictable names.
+ */
 import { randomBytes } from "node:crypto";
 import { createWriteStream, type WriteStream } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-/**
- * Creates private temporary log files for tool output spillover.
- */
 /** Opens a unique write stream with owner-only permissions. */
 export function createPrivateTempWriteStream(prefix: string): {
   path: string;
diff --git a/src/agents/sessions/tools/read.ts b/src/agents/sessions/tools/read.ts
@@ -1,3 +1,8 @@
+/**
+ * Built-in read session tool.
+ *
+ * Reads text and image files through local or injected operations with highlighting, resizing, and bounded output.
+ */
 import { constants } from "node:fs";
 import { access as fsAccess, readFile as fsReadFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, relative, resolve as resolvePath, sep } from "node:path";
diff --git a/src/agents/sessions/tools/render-utils.ts b/src/agents/sessions/tools/render-utils.ts
@@ -1,16 +1,15 @@
+/**
+ * Rendering helpers for session tool output in the TUI.
+ *
+ * Normalizes paths/text/image fallbacks before tool results are styled or truncated.
+ */
 import * as os from "node:os";
 import { getCapabilities, getImageDimensions, imageFallback } from "@earendil-works/pi-tui";
 import type { ImageContent, TextContent } from "../../../llm/types.js";
 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") {
diff --git a/src/agents/sessions/tools/tool-contracts.ts b/src/agents/sessions/tools/tool-contracts.ts
@@ -1,3 +1,8 @@
+/**
+ * Shared built-in session tool input/detail contracts.
+ *
+ * Keeps tool factories, renderers, and callers aligned on typed payload and metadata shapes.
+ */
 import type { Edit } from "./edit-diff.js";
 import type { TruncationResult } from "./truncate.js";
 
diff --git a/src/agents/sessions/tools/tool-definition-wrapper.ts b/src/agents/sessions/tools/tool-definition-wrapper.ts
@@ -1,3 +1,8 @@
+/**
+ * Tool definition/AgentTool adapters.
+ *
+ * Bridges extension-style ToolDefinition objects and core runtime AgentTool objects.
+ */
 import type { TSchema } from "typebox";
 import type { AgentTool } from "../../runtime/index.js";
 import type { ExtensionContext, ToolDefinition } from "../extensions/types.js";
diff --git a/src/agents/sessions/tools/write.ts b/src/agents/sessions/tools/write.ts
@@ -1,3 +1,8 @@
+/**
+ * Built-in write session tool.
+ *
+ * Writes files through queued local or injected operations with readback/idempotency metadata.
+ */
 import {
   mkdir as fsMkdir,
   readFile as fsReadFile,
