feat(coding-agent): show generated session summaries in the resume picker

packages/coding-agent/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added generated session summaries to the resume picker, so `/resume` and `atomic -r` show what a conversation was about instead of a truncated first message. Atomic writes a one-line summary once the agent goes idle, reusing the session's existing model, credentials, stream function, and retry policy with a dedicated one-line prompt and no reasoning request; the stored line has its whitespace collapsed and length clamped so a long response cannot break picker layout. Each summary is persisted as a `session_summary` session entry anchored to the last user/assistant message it describes, and the picker shows it only while that message is still the newest one — a later message, or a later branch summary, retires it and the display falls back to the session name or first message, exactly as it does when a summary has not been generated, has failed, or is still in flight. Summaries are matched by picker search, and their token usage is counted toward session usage totals and the footer. Generation is best-effort and invisible: it is skipped for very short sessions, workflow stage sessions, and `--print`/JSON modes, it never blocks or delays a turn, it is cancelled when the next prompt starts or the session shuts down, and a slow request that outlives the conversation discards its own result rather than persisting a stale summary. Set `sessionSummary.enabled` to `false` to disable it ([#1033](https://github.com/bastani-inc/atomic/issues/1033)).
+
 ## [0.9.11-alpha.10] - 2026-08-01
 
 ### Fixed

packages/coding-agent/docs/session-format.md

@@ -307,6 +307,20 @@ Session metadata (e.g., user-defined display name). Set via `/name`, `--name` /
 
 The session name is displayed in the session selector (`/resume`) instead of the first message when set.
 
+### SessionSummaryEntry
+
+A generated one-line description of the session, written automatically once the agent goes idle and shown in the session selector. Never sent to the LLM.
+
+```json
+{"type":"session_summary","id":"l2m3n4o5","parentId":"k1l2m3n4","timestamp":"2024-12-03T14:36:00.000Z","summary":"Refactored auth module token refresh and added retry tests","summarizedThroughId":"j0k1l2m3","usage":{"input":812,"output":21}}
+```
+
+- `summary`: The stored line. Whitespace is collapsed and length is clamped before writing.
+- `summarizedThroughId`: Entry ID of the last user/assistant message the summary covers. The selector shows the summary only while this is still the newest conversation message; anything newer makes it stale and the selector falls back to the session name or first message. Tool results do not count.
+- `usage`: Optional token usage from the model call, counted toward session usage totals.
+
+A `branch_summary` written after a `session_summary` also retires it, because the branch it described was abandoned.
+
 ## Tree Structure
 
 Entries form a tree:
@@ -420,6 +434,7 @@ for (const stage of stages.filter((session) => session.internal)) {
 - `appendCompaction(compactedText, firstKeptEntryId, tokensBefore, details)` - Add a durable verbatim-line compaction boundary; pass `null` when no pre-boundary message is retained
 - `appendCustomEntry(customType, data?)` - Extension state (not in context)
 - `appendSessionInfo(name)` - Set session display name
+- `appendSessionSummary(summary, summarizedThroughId, usage?)` - Store a generated resume-picker summary, anchored to the message it describes
 - `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)
 - `appendLabelChange(targetId, label)` - Set/clear label
 

packages/coding-agent/docs/sessions.md

@@ -55,6 +55,14 @@ In the picker you can:
 
 When available, Atomic uses the `trash` CLI for deletion instead of permanently removing files.
 
+### Session summaries
+
+Each row shows a short generated description of what the session was about, so you can recognize a conversation without opening it. Atomic writes one after the agent goes idle, using the model the session is already configured with, and stores it in the session file as a `session_summary` entry.
+
+A summary describes the conversation up to a specific message. Once a newer message arrives it is considered stale and the picker falls back to the session name, or to the first message — the same display you get when a summary has not been generated yet, could not be generated, or is still in flight. Summaries are also searchable along with the rest of the session text.
+
+Generation is best-effort and never blocks a turn: it is skipped for very short sessions, for workflow stage sessions, and in `--print` and JSON modes, it is cancelled when you send the next message or quit, and its failures are silent. Set `sessionSummary.enabled` to `false` to turn it off entirely.
+
 The picker opens instantly: its header, search field, and loading indicator paint on the first frame, then sessions are discovered and parsed off the terminal's UI loop. Large session directories are scanned in cooperative batches and a single very large transcript is parsed in yielding chunks, so search, navigation, and cancel stay responsive and no individual session can freeze the picker while it loads. Closing the picker cancels any in-flight scan and discards stale results, so a slow load that finishes after you leave never updates the list.
 
 ### Internal (workflow) sessions

packages/coding-agent/docs/settings.md

@@ -183,6 +183,12 @@ The model emits numbered line ranges only; Atomic reconstructs retained text mec
 | `branchSummary.reserveTokens` | number | `16384` | Tokens reserved for branch summarization |
 | `branchSummary.skipPrompt` | boolean | `false` | Skip "Summarize branch?" prompt on `/tree` navigation (defaults to no summary) |
 
+### Session Summary
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `sessionSummary.enabled` | boolean | `true` | Generate a one-line summary of each session for the `/resume` picker once the agent goes idle |
+
 ### Retry
 
 | Setting | Type | Default | Description |

packages/coding-agent/src/core/agent-session-events.ts

@@ -260,6 +260,7 @@ export async function _processAgentEvent(this: AgentSession, event: AgentEvent):
 
 		this._resolveRetry();
 		await this._checkCompaction(msg);
+		if (event.type === "agent_end") void this._maybeGenerateSessionSummary();
 	}
 }
 
@@ -472,6 +473,8 @@ export function _reconnectToAgent(this: AgentSession): void {
  */
 
 export function dispose(this: AgentSession): void {
+	// A background summary must never keep the process alive past shutdown.
+	this.abortSessionSummary();
 	// Fail closed while protected input remains queued, or flush a consumed
 	// reconciliation before invalidation can discard its recovery state.
 	prepareProtectedStreamingCustomMessagesForDisposal(this);

packages/coding-agent/src/core/agent-session-export.ts

@@ -19,7 +19,9 @@ export function getSessionStats(this: AgentSession): SessionStats {
 	let toolCalls = 0;
 	const totals = createUsageTotals();
 	for (const entry of this.sessionManager.getEntries()) {
-		if (entry.type === "branch_summary" && entry.usage) addUsageToTotals(totals, entry.usage);
+		if ((entry.type === "branch_summary" || entry.type === "session_summary") && entry.usage) {
+			addUsageToTotals(totals, entry.usage);
+		}
 		if (entry.type !== "message") continue;
 		totalMessages++;
 		const message = entry.message;

packages/coding-agent/src/core/agent-session-methods.ts

@@ -227,6 +227,8 @@ export interface AgentSessionMethodSurface extends AgentSessionQueuePauseControl
 	compact(options?: Partial<VerbatimCompactionParameters>): Promise<VerbatimCompactionResult>;
 	abortCompaction(): void;
 	abortBranchSummary(): void;
+	abortSessionSummary(): void;
+	_maybeGenerateSessionSummary(): Promise<void>;
 	_checkCompaction(assistantMessage: AssistantMessage, skipAbortedCheck?: boolean): Promise<void>;
 	_dropTrailingAutoCompactionRetryAssistantIfPresent(): void;
 	_schedulePostAutoCompactionContinuationProbe(reason: "overflow" | "threshold", willRetry: boolean): void;
@@ -324,6 +326,7 @@ export interface AgentSessionPublicSurface
 		| "autoCompactionEnabled"
 		| "isRetrying"
 		| "autoRetryEnabled"
+		| "abortSessionSummary"
 		| "isBashRunning"
 		| "hasPendingBashMessages"
 		| "extensionRunner"
@@ -438,6 +441,9 @@ export interface AgentSessionInternalSurface extends AgentSessionMethodSurface,
 	_orchestrationContext?: OrchestrationContext;
 	_extensionUIContext?: ExtensionUIContext;
 	_extensionMode: ExtensionMode;
+	_sessionSummaryAbortController: AbortController | undefined;
+	_sessionSummaryToken: number;
+	_lastSummarizedMessageId: string | undefined;
 	_extensionCommandContextActions?: ExtensionCommandContextActions;
 	_extensionShutdownHandler?: () => void;
 	_extensionErrorListener?: ExtensionErrorListener;

packages/coding-agent/src/core/agent-session-prompt.ts

@@ -45,6 +45,9 @@ export async function tryExecuteSessionSlashCommand(
 export async function prompt(this: AgentSession, text: string, options?: PromptOptions): Promise<void> {
 	const owner = resolveWorkflowStageDeliveryTarget(this);
 	if (owner !== this) return owner.prompt(text, options);
+	// A summary of the conversation up to the previous turn is about to be stale; stop paying
+	// for it. The generation itself is discarded by its own token/anchor checks either way.
+	this.abortSessionSummary();
 	const expandPromptTemplates = options?.expandPromptTemplates ?? true;
 	const preflightResult = options?.preflightResult;
 	const workflowDelivery = (options as PromptOptionsWithWorkflowDelivery | undefined)?.__workflowDelivery;

packages/coding-agent/src/core/agent-session-summary.ts

@@ -0,0 +1,82 @@
+/**
+ * Session summary generation for the resume picker.
+ *
+ * Runs once the agent goes idle, decides whether a fresh summary is worth generating, and
+ * persists the result. Generation itself lives in core/compaction/session-summarization.ts.
+ */
+
+import type { AgentSessionInternalSurface as AgentSession } from "./agent-session-methods.ts";
+import { generateSessionSummary } from "./compaction/index.ts";
+import { getLastConversationMessageId, getLatestSessionSummary } from "./session-manager-entries.ts";
+
+/** Sessions shorter than this are already legible from their first message. */
+const MIN_ENTRIES_FOR_SUMMARY = 4;
+
+export async function _maybeGenerateSessionSummary(this: AgentSession): Promise<void> {
+	// --- Bail-outs, cheapest first ------------------------------------------------------
+	if (!this.settingsManager.getSessionSummarySettings().enabled) return;
+
+	// One-shot scripted runs should not pay for a background call; the process may exit before
+	// it lands. "tui" and "rpc" are the resumable, interactive modes.
+	if (this._extensionMode === "print" || this._extensionMode === "json") return;
+
+	if (this.isStreaming || this.isCompacting) return;
+	const model = this.model;
+	if (!model) return;
+
+	// Workflow-stage sessions are excluded from /resume entirely.
+	if (this.sessionManager.getHeader()?.internal) return;
+
+	const branch = this.sessionManager.getBranch();
+	if (branch.length < MIN_ENTRIES_FOR_SUMMARY) return;
+
+	const throughId = getLastConversationMessageId(branch);
+	if (!throughId) return;
+
+	// On a resumed session the in-memory anchor starts empty, so fall back to the persisted
+	// summary. Without this the first idle after every resume regenerates a summary that is
+	// already current.
+	const lastSummarized =
+		this._lastSummarizedMessageId ?? getLatestSessionSummary(this.sessionManager.getEntries())?.summarizedThroughId;
+	if (throughId === lastSummarized) return;
+
+	// Claim the run. The token answers "is this still the current attempt, and is this state
+	// still mine to touch?" after the awaits below; the controller lives on the session so
+	// abortSessionSummary() can reach it from the prompt and shutdown paths.
+	this.abortSessionSummary();
+	const sessionSummaryToken = ++this._sessionSummaryToken;
+	this._sessionSummaryAbortController = new AbortController();
+	const signal = this._sessionSummaryAbortController.signal;
+
+	try {
+		const { apiKey, headers, baseUrl } = await this._getRequiredRequestAuth(model);
+		const result = await generateSessionSummary(branch, {
+			model,
+			apiKey,
+			headers,
+			baseUrl,
+			signal,
+			streamFn: this.agent.streamFunction,
+			retry: this.settingsManager.getRetrySettings(),
+		});
+		// Failures stay silent: nothing awaits this, and the picker falls back on its own.
+		if (result.aborted || result.error || !result.summary) return;
+
+		// A newer run, or a newer message, means this summary no longer describes the session.
+		if (this._sessionSummaryToken !== sessionSummaryToken) return;
+		if (getLastConversationMessageId(this.sessionManager.getBranch()) !== throughId) return;
+
+		this.sessionManager.appendSessionSummary(result.summary, throughId, result.usage);
+		this._lastSummarizedMessageId = throughId;
+	} finally {
+		if (this._sessionSummaryToken === sessionSummaryToken) {
+			this._sessionSummaryAbortController = undefined;
+		}
+	}
+}
+
+export function abortSessionSummary(this: AgentSession): void {
+	this._sessionSummaryAbortController?.abort();
+}
+
+export const agentSessionSummaryMethods = { _maybeGenerateSessionSummary, abortSessionSummary };

packages/coding-agent/src/core/agent-session.ts

@@ -24,6 +24,7 @@ import { agentSessionPostToolCompactionMethods } from "./agent-session-post-tool
 import { agentSessionPromptMethods } from "./agent-session-prompt.ts";
 import { agentSessionRetryMethods } from "./agent-session-retry.ts";
 import { agentSessionStateMethods } from "./agent-session-state.ts";
+import { agentSessionSummaryMethods } from "./agent-session-summary.ts";
 import { agentSessionToolHooksMethods } from "./agent-session-tool-hooks.ts";
 import { agentSessionToolRegistryMethods } from "./agent-session-tool-registry.ts";
 import { agentSessionTreeMethods } from "./agent-session-tree.ts";
@@ -104,6 +105,9 @@ class AgentSessionBase {
 	protected _pendingPostToolCompactionGuard: PendingPostToolCompactionGuard | undefined = undefined;
 	protected _terminatingToolCallIds = new Set<string>();
 	protected _branchSummaryAbortController: AbortController | undefined = undefined;
+	protected _sessionSummaryAbortController: AbortController | undefined = undefined;
+	protected _sessionSummaryToken = 0;
+	protected _lastSummarizedMessageId: string | undefined = undefined;
 	protected _retryAbortController: AbortController | undefined = undefined;
 	protected _retryAttempt = 0;
 	protected _retryPromise: Promise<void> | undefined = undefined;
@@ -218,4 +222,5 @@ Object.assign(
 	agentSessionBashMethods,
 	agentSessionTreeMethods,
 	agentSessionExportMethods,
+	agentSessionSummaryMethods,
 );

packages/coding-agent/src/core/compaction/branch-summarization.ts

@@ -189,6 +189,7 @@ function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {
 		case "custom":
 		case "label":
 		case "session_info":
+		case "session_summary":
 		case "context_compaction":
 			return undefined;
 	}

packages/coding-agent/src/core/compaction/index.ts

@@ -14,5 +14,6 @@ export * from "./planner-outcome.js";
 export * from "./range-planner.js";
 export * from "./range-planner-diagnostics.js";
 export * from "./region-trimming.js";
+export * from "./session-summarization.ts";
 export * from "./transcript-serialization.js";
 export * from "./utils.ts";