From edd3870d53323958760274dee2ed0dbd6db68a8f Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 00:47:48 -0400
Subject: [PATCH] docs: document session helper metadata

---
 src/agents/sessions/http-dispatcher.ts |  4 ++++
 src/agents/sessions/messages.ts        |  6 ++++++
 src/agents/sessions/session-cwd.ts     | 10 ++++++++++
 src/agents/sessions/slash-commands.ts  |  4 ++++
 src/agents/sessions/source-info.ts     |  5 +++++
 5 files changed, 29 insertions(+)

diff --git a/src/agents/sessions/http-dispatcher.ts b/src/agents/sessions/http-dispatcher.ts
index de921d803a81..66aca5bd841d 100644
--- a/src/agents/sessions/http-dispatcher.ts
+++ b/src/agents/sessions/http-dispatcher.ts
@@ -1,7 +1,11 @@
 import { parseStrictNonNegativeInteger } from "../../infra/parse-finite-number.js";
 
+/**
+ * HTTP session dispatcher idle-timeout parsing shared by server and config surfaces.
+ */
 export const DEFAULT_HTTP_IDLE_TIMEOUT_MS = 300_000;
 
+/** Parses idle timeout values, using `0` for the explicit disabled sentinel. */
 export function parseHttpIdleTimeoutMs(value: unknown): number | undefined {
   if (typeof value === "string") {
     const trimmed = value.trim();
diff --git a/src/agents/sessions/messages.ts b/src/agents/sessions/messages.ts
index 1a78ff04f94f..345b190ada79 100644
--- a/src/agents/sessions/messages.ts
+++ b/src/agents/sessions/messages.ts
@@ -1,3 +1,9 @@
+/**
+ * Session message conversion bridge from the shared agent-core harness package.
+ *
+ * Keeping the re-export here gives legacy session code a stable local import path while the
+ * canonical message conversion logic lives in the shared package.
+ */
 export { convertToLlm } from "../../../packages/agent-core/src/harness/messages.js";
 
 export type {
diff --git a/src/agents/sessions/session-cwd.ts b/src/agents/sessions/session-cwd.ts
index 92ac5aba2db6..918135bb4e0b 100644
--- a/src/agents/sessions/session-cwd.ts
+++ b/src/agents/sessions/session-cwd.ts
@@ -1,5 +1,10 @@
 import { existsSync } from "node:fs";
 
+/**
+ * Detects when a resumed session points at a working directory that no longer exists.
+ *
+ * Callers use this to decide whether to stop, prompt, or continue in the current process cwd.
+ */
 export interface SessionCwdIssue {
   sessionFile?: string;
   sessionCwd: string;
@@ -11,6 +16,7 @@ interface SessionCwdSource {
   getSessionFile(): string | undefined;
 }
 
+/** Returns a cwd issue for persisted sessions whose stored cwd has disappeared. */
 export function getMissingSessionCwdIssue(
   sessionManager: SessionCwdSource,
   fallbackCwd: string,
@@ -32,15 +38,18 @@ export function getMissingSessionCwdIssue(
   };
 }
 
+/** Formats the terminal error shown when resume cannot safely use the stored cwd. */
 export function formatMissingSessionCwdError(issue: SessionCwdIssue): string {
   const sessionFile = issue.sessionFile ? `\nSession file: ${issue.sessionFile}` : "";
   return `Stored session working directory does not exist: ${issue.sessionCwd}${sessionFile}\nCurrent working directory: ${issue.fallbackCwd}`;
 }
 
+/** Formats the compact prompt used when the user can choose the fallback cwd. */
 export function formatMissingSessionCwdPrompt(issue: SessionCwdIssue): string {
   return `cwd from session file does not exist\n${issue.sessionCwd}\n\ncontinue in current cwd\n${issue.fallbackCwd}`;
 }
 
+/** Error wrapper that preserves the missing-cwd facts for UI and recovery code. */
 export class MissingSessionCwdError extends Error {
   readonly issue: SessionCwdIssue;
 
@@ -51,6 +60,7 @@ export class MissingSessionCwdError extends Error {
   }
 }
 
+/** Throws when a persisted session cwd is missing and the caller does not handle prompts. */
 export function assertSessionCwdExists(
   sessionManager: SessionCwdSource,
   fallbackCwd: string,
diff --git a/src/agents/sessions/slash-commands.ts b/src/agents/sessions/slash-commands.ts
index 4fc450bee300..9943120525aa 100644
--- a/src/agents/sessions/slash-commands.ts
+++ b/src/agents/sessions/slash-commands.ts
@@ -1,6 +1,9 @@
 import { APP_NAME } from "../config.js";
 import type { SourceInfo } from "./source-info.js";
 
+/**
+ * Slash command metadata surfaced by built-ins, prompt packs, skills, and extensions.
+ */
 export type SlashCommandSource = "extension" | "prompt" | "skill";
 
 export interface SlashCommandInfo {
@@ -15,6 +18,7 @@ export interface BuiltinSlashCommand {
   description: string;
 }
 
+/** Built-in TUI slash commands that exist even when no prompt/skill packages are loaded. */
 export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
   { name: "settings", description: "Open settings menu" },
   { name: "model", description: "Select model (opens selector UI)" },
diff --git a/src/agents/sessions/source-info.ts b/src/agents/sessions/source-info.ts
index 3f0a310abeff..d6cbc3ffa80e 100644
--- a/src/agents/sessions/source-info.ts
+++ b/src/agents/sessions/source-info.ts
@@ -1,5 +1,8 @@
 import type { PathMetadata } from "./package-manager.js";
 
+/**
+ * Source metadata attached to prompts, skills, and extension-provided session assets.
+ */
 export type SourceScope = "user" | "project" | "temporary";
 export type SourceOrigin = "package" | "top-level";
 
@@ -11,6 +14,7 @@ export interface SourceInfo {
   baseDir?: string;
 }
 
+/** Converts package-manager path metadata into the session source-info shape. */
 export function createSourceInfo(path: string, metadata: PathMetadata): SourceInfo {
   return {
     path,
@@ -21,6 +25,7 @@ export function createSourceInfo(path: string, metadata: PathMetadata): SourceIn
   };
 }
 
+/** Builds source metadata for generated or synthetic session entries. */
 export function createSyntheticSourceInfo(
   path: string,
   options: {