docs: document session tool bridges

src/agents/sessions/compaction/branch-summarization.ts

@@ -10,6 +10,9 @@ import {
 } from "../../runtime/index.js";
 import type { SessionEntry, ReadonlySessionManager } from "../session-manager.js";
 
+/**
+ * Branch-summary bridge from session managers to the shared agent-core summarizer.
+ */
 export type { BranchPreparation, BranchSummaryDetails, FileOperations };
 export { prepareBranchEntries };
 
@@ -36,6 +39,7 @@ export interface GenerateBranchSummaryOptions {
   reserveTokens?: number;
 }
 
+/** Collects entries that differ between two session branches for summarization. */
 export function collectEntriesForBranchSummary(
   session: ReadonlySessionManager,
   oldLeafId: string | null,
@@ -50,6 +54,7 @@ export function collectEntriesForBranchSummary(
   return collectEntriesForBranchSummaryFromBranches(oldBranch, targetPath);
 }
 
+/** Generates a human-readable branch summary through the shared agent-core runtime. */
 export async function generateBranchSummary(
   entries: SessionEntry[],
   options: GenerateBranchSummaryOptions,

src/agents/sessions/compaction/compaction.ts

@@ -24,6 +24,11 @@ import {
 import type { AgentMessage, StreamFn, ThinkingLevel } from "../../runtime/index.js";
 import type { SessionEntry } from "../session-manager.js";
 
+/**
+ * Session compaction compatibility bridge over the shared agent-core implementation.
+ *
+ * Local callers keep the historic throwing API while agent-core returns explicit Result objects.
+ */
 export {
   calculateContextTokens,
   DEFAULT_COMPACTION_SETTINGS,
@@ -41,6 +46,7 @@ export {
   type ContextUsageEstimate,
 };
 
+/** Converts agent-core Result values back to the legacy session compaction API shape. */
 function unwrapCompactionResult<T>(result: Result<T, Error>): T {
   if (result.ok) {
     return result.value;
@@ -48,6 +54,7 @@ function unwrapCompactionResult<T>(result: Result<T, Error>): T {
   throw result.error;
 }
 
+/** Prepares session entries for compaction using the shared agent-core planner. */
 export function prepareCompaction(
   pathEntries: SessionEntry[],
   settings: CompactionSettings,
@@ -55,6 +62,7 @@ export function prepareCompaction(
   return unwrapCompactionResult(prepareCompactionCore(pathEntries, settings));
 }
 
+/** Generates a compaction summary through the shared agent-core runtime. */
 export async function generateSummary(
   currentMessages: AgentMessage[],
   model: Model,
@@ -84,6 +92,7 @@ export async function generateSummary(
   );
 }
 
+/** Runs full compaction through agent-core and returns the compacted conversation result. */
 export async function compact(
   preparation: CompactionPreparation,
   model: Model,

src/agents/sessions/tools/bash-operations.ts

@@ -1,3 +1,6 @@
+/**
+ * Minimal shell execution interface injected into bash session tools.
+ */
 export interface BashOperations {
   exec: (
     command: string,

src/agents/sessions/tools/index.ts

@@ -80,6 +80,12 @@ import { createLsTool, createLsToolDefinition, type LsToolOptions } from "./ls.j
 import { createReadTool, createReadToolDefinition, type ReadToolOptions } from "./read.js";
 import { createWriteTool, createWriteToolDefinition, type WriteToolOptions } from "./write.js";
 
+/**
+ * Public factory barrel for the built-in coding and read-only session tools.
+ *
+ * Keep grouped creators here so callers can request stable tool sets without importing each
+ * individual implementation module.
+ */
 export type Tool = AgentTool;
 export type ToolDef = ToolDefinition;
 export type ToolName = "read" | "bash" | "edit" | "write" | "grep" | "find" | "ls";
@@ -103,6 +109,7 @@ export interface ToolsOptions {
   ls?: LsToolOptions;
 }
 
+/** Creates one tool definition by stable built-in tool name. */
 export function createToolDefinition(
   toolName: ToolName,
   cwd: string,
@@ -128,6 +135,7 @@ export function createToolDefinition(
   }
 }
 
+/** Creates one executable built-in tool by stable tool name. */
 export function createTool(toolName: ToolName, cwd: string, options?: ToolsOptions): Tool {
   switch (toolName) {
     case "read":
@@ -149,6 +157,7 @@ export function createTool(toolName: ToolName, cwd: string, options?: ToolsOptio
   }
 }
 
+/** Creates the mutable coding tool definitions used by agent coding sessions. */
 export function createCodingToolDefinitions(cwd: string, options?: ToolsOptions): ToolDef[] {
   return [
     createReadToolDefinition(cwd, options?.read),
@@ -158,6 +167,7 @@ export function createCodingToolDefinitions(cwd: string, options?: ToolsOptions)
   ];
 }
 
+/** Creates read-only discovery tool definitions for restricted sessions. */
 export function createReadOnlyToolDefinitions(cwd: string, options?: ToolsOptions): ToolDef[] {
   return [
     createReadToolDefinition(cwd, options?.read),
@@ -167,6 +177,7 @@ export function createReadOnlyToolDefinitions(cwd: string, options?: ToolsOption
   ];
 }
 
+/** Creates all built-in tool definitions keyed by tool name. */
 export function createAllToolDefinitions(
   cwd: string,
   options?: ToolsOptions,
@@ -182,6 +193,7 @@ export function createAllToolDefinitions(
   };
 }
 
+/** Creates the mutable coding tools used by local agent sessions. */
 export function createCodingTools(cwd: string, options?: ToolsOptions): Tool[] {
   return [
     createReadTool(cwd, options?.read),
@@ -191,6 +203,7 @@ export function createCodingTools(cwd: string, options?: ToolsOptions): Tool[] {
   ];
 }
 
+/** Creates read-only discovery tools for restricted sessions. */
 export function createReadOnlyTools(cwd: string, options?: ToolsOptions): Tool[] {
   return [
     createReadTool(cwd, options?.read),
@@ -200,6 +213,7 @@ export function createReadOnlyTools(cwd: string, options?: ToolsOptions): Tool[]
   ];
 }
 
+/** Creates all built-in tools keyed by tool name. */
 export function createAllTools(cwd: string, options?: ToolsOptions): Record<ToolName, Tool> {
   return {
     read: createReadTool(cwd, options?.read),

src/agents/sessions/tools/private-temp-file.ts

@@ -3,6 +3,10 @@ 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;
   stream: WriteStream;