From 9b4e2fa8a8d7f1e7803018cd31f4bacc3e039958 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 00:55:22 -0400 Subject: [PATCH] docs: document session tool bridges --- .../sessions/compaction/branch-summarization.ts | 5 +++++ src/agents/sessions/compaction/compaction.ts | 9 +++++++++ src/agents/sessions/tools/bash-operations.ts | 3 +++ src/agents/sessions/tools/index.ts | 14 ++++++++++++++ src/agents/sessions/tools/private-temp-file.ts | 4 ++++ 5 files changed, 35 insertions(+) diff --git a/src/agents/sessions/compaction/branch-summarization.ts b/src/agents/sessions/compaction/branch-summarization.ts index 23182d93e538..227f317fbdad 100644 --- a/src/agents/sessions/compaction/branch-summarization.ts +++ b/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, diff --git a/src/agents/sessions/compaction/compaction.ts b/src/agents/sessions/compaction/compaction.ts index 78621f8fa4ff..3554ce0c8441 100644 --- a/src/agents/sessions/compaction/compaction.ts +++ b/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(result: Result): T { if (result.ok) { return result.value; @@ -48,6 +54,7 @@ function unwrapCompactionResult(result: Result): 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, diff --git a/src/agents/sessions/tools/bash-operations.ts b/src/agents/sessions/tools/bash-operations.ts index 120785f32bb4..66dd21393936 100644 --- a/src/agents/sessions/tools/bash-operations.ts +++ b/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, diff --git a/src/agents/sessions/tools/index.ts b/src/agents/sessions/tools/index.ts index b23fb6f18911..4c05446afaf8 100644 --- a/src/agents/sessions/tools/index.ts +++ b/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 { return { read: createReadTool(cwd, options?.read), diff --git a/src/agents/sessions/tools/private-temp-file.ts b/src/agents/sessions/tools/private-temp-file.ts index ed2de5bd850b..fc2bec256698 100644 --- a/src/agents/sessions/tools/private-temp-file.ts +++ b/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;