docs: document session helper metadata

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();

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 {

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,

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)" },

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: {