@pellux/goodvibes-tui 0.18.4

package/src/runtime/session-maintenance.ts

@@ -0,0 +1,188 @@
+import type { ConfigManager } from '../config/manager.ts';
+import type { SessionDomainState } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/session';
+
+export type GuidanceMode = 'off' | 'minimal' | 'guided';
+export type SessionMaintenanceLevel =
+  | 'stable'
+  | 'watch'
+  | 'suggest-compact'
+  | 'compacting'
+  | 'needs-repair'
+  | 'unknown';
+
+export interface SessionMaintenanceStatus {
+  readonly level: SessionMaintenanceLevel;
+  readonly guidanceMode: GuidanceMode;
+  readonly usagePct: number;
+  readonly remainingTokens: number;
+  readonly thresholdPct: number;
+  readonly autoCompactEnabled: boolean;
+  readonly compactRecommended: boolean;
+  readonly sessionMemoryCount: number;
+  readonly compactionCount: number;
+  readonly lastCompactedAt?: number;
+  readonly summary: string;
+  readonly reasons: readonly string[];
+  readonly nextSteps: readonly string[];
+}
+
+export interface SessionMaintenanceInput {
+  readonly configManager: Pick<ConfigManager, 'get'>;
+  readonly currentTokens: number;
+  readonly contextWindow: number;
+  readonly messageCount?: number;
+  readonly sessionMemoryCount?: number;
+  readonly session?: Partial<SessionDomainState>;
+}
+
+export function getGuidanceMode(configManager: Pick<ConfigManager, 'get'>): GuidanceMode {
+  return (configManager.get('behavior.guidanceMode') as GuidanceMode | undefined) ?? 'minimal';
+}
+
+function compactStateIsActive(state: SessionDomainState['compactionState'] | undefined): boolean {
+  return state === 'checking_threshold'
+    || state === 'microcompact'
+    || state === 'collapse'
+    || state === 'autocompact'
+    || state === 'reactive_compact'
+    || state === 'boundary_commit';
+}
+
+function formatAge(ts: number | undefined): string {
+  if (!ts) return 'never';
+  const ageMs = Date.now() - ts;
+  const minutes = Math.floor(ageMs / 60_000);
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+export function evaluateSessionMaintenance(input: SessionMaintenanceInput): SessionMaintenanceStatus {
+  const guidanceMode = getGuidanceMode(input.configManager);
+  const thresholdPct = Math.max(0, Number(input.configManager.get('behavior.autoCompactThreshold') ?? 0));
+  const autoCompactEnabled = thresholdPct > 0;
+  const currentTokens = Math.max(0, input.currentTokens);
+  const contextWindow = Math.max(0, input.contextWindow);
+  const usagePct = contextWindow > 0 ? Math.min(100, Math.round((currentTokens / contextWindow) * 100)) : 0;
+  const remainingTokens = Math.max(0, contextWindow - currentTokens);
+  const sessionMemoryCount = Math.max(0, input.sessionMemoryCount ?? 0);
+  const compactionCount = Math.max(0, input.session?.lineage?.filter((entry) => entry.branchReason === 'compaction').length ?? 0);
+  const lastCompactedAt = input.session?.lastCompactedAt;
+  const messageCount = Math.max(0, input.messageCount ?? 0);
+  const warningsEnabled = Boolean(input.configManager.get('behavior.staleContextWarnings'));
+  const staleByMessageGrowth =
+    (input.session?.compactionMessageCount ?? 0) > 0
+      ? messageCount - (input.session?.compactionMessageCount ?? 0) >= 12
+      : messageCount >= 24;
+
+  if (contextWindow <= 0) {
+    return {
+      level: 'unknown',
+      guidanceMode,
+      usagePct,
+      remainingTokens,
+      thresholdPct,
+      autoCompactEnabled,
+      compactRecommended: false,
+      sessionMemoryCount,
+      compactionCount,
+      lastCompactedAt,
+      summary: 'Context window unavailable.',
+      reasons: ['Current model does not expose a known context limit yet.'],
+      nextSteps: guidanceMode === 'off' ? [] : ['/provider', '/context'],
+    };
+  }
+
+  const reasons: string[] = [];
+  const nextSteps: string[] = [];
+  let level: SessionMaintenanceLevel = 'stable';
+
+  if (input.session?.compactionState === 'failed') {
+    level = 'needs-repair';
+    reasons.push('Compaction failed and the session may need manual recovery.');
+    nextSteps.push('/compact', '/health review');
+  } else if (compactStateIsActive(input.session?.compactionState)) {
+    level = 'compacting';
+    reasons.push('Compaction is currently running.');
+  } else if ((autoCompactEnabled && usagePct >= thresholdPct) || usagePct >= 80 || remainingTokens <= 15_000) {
+    level = 'suggest-compact';
+    reasons.push(`Context pressure is high at ${usagePct}% usage.`);
+    if (remainingTokens <= 15_000) {
+      reasons.push(`Only ${remainingTokens.toLocaleString()} tokens remain before the safety buffer is exhausted.`);
+    }
+    nextSteps.push('/compact', '/panel tokens');
+  } else if ((warningsEnabled && usagePct >= Math.max(70, autoCompactEnabled ? thresholdPct - 10 : 70)) || staleByMessageGrowth) {
+    level = 'watch';
+    reasons.push(staleByMessageGrowth
+      ? `Conversation has grown ${messageCount.toLocaleString()} messages since the last maintenance checkpoint.`
+      : `Context usage is climbing toward the ${thresholdPct}% auto-compact threshold.`);
+    nextSteps.push('/panel tokens');
+    if (guidanceMode === 'guided') nextSteps.push('/context');
+  } else {
+    reasons.push('Context pressure is currently within the stable operating band.');
+  }
+
+  if (sessionMemoryCount > 0) {
+    reasons.push(`${sessionMemoryCount} pinned session memor${sessionMemoryCount === 1 ? 'y is' : 'ies are'} preserved during compaction.`);
+  }
+  if (compactionCount > 0) {
+    reasons.push(`Last compaction ran ${formatAge(lastCompactedAt)}.`);
+  }
+  if (!autoCompactEnabled) {
+    reasons.push('Auto-compaction is disabled; maintenance stays fully manual.');
+    if (guidanceMode !== 'off') nextSteps.push('/settings');
+  }
+
+  const compactRecommended = level === 'suggest-compact' || level === 'needs-repair';
+  const summary =
+    level === 'needs-repair'
+      ? 'Compaction needs operator repair.'
+      : level === 'compacting'
+        ? 'Compaction in progress.'
+        : level === 'suggest-compact'
+          ? `Compact now to recover context headroom (${usagePct}% used).`
+          : level === 'watch'
+            ? `Watch context growth (${usagePct}% used, threshold ${thresholdPct}%).`
+            : 'Session maintenance is stable.';
+
+  return {
+    level,
+    guidanceMode,
+    usagePct,
+    remainingTokens,
+    thresholdPct,
+    autoCompactEnabled,
+    compactRecommended,
+    sessionMemoryCount,
+    compactionCount,
+    lastCompactedAt,
+    summary,
+    reasons,
+    nextSteps: [...new Set(nextSteps)],
+  };
+}
+
+export function formatSessionMaintenanceLines(
+  status: SessionMaintenanceStatus,
+  detail: 'minimal' | 'guided' = 'minimal',
+): string[] {
+  const lines = [
+    `Maintenance: ${status.summary}`,
+  ];
+  if (detail === 'guided') {
+    for (const reason of status.reasons) lines.push(`  ${reason}`);
+  } else if (status.reasons[0]) {
+    lines.push(`  ${status.reasons[0]}`);
+  }
+  const nextSteps = status.nextSteps.length > 0
+    ? status.nextSteps
+    : detail === 'guided'
+      ? ['/context']
+      : [];
+  if ((detail === 'guided' || status.guidanceMode !== 'off') && nextSteps.length > 0) {
+    lines.push(`  Next: ${nextSteps.join('  |  ')}`);
+  }
+  return lines;
+}

package/src/runtime/session-persistence.ts

@@ -0,0 +1,288 @@
+import { randomBytes } from 'crypto';
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs';
+import { dirname, join } from 'path';
+
+import { SessionManager, type SessionMeta } from '../sessions/manager.ts';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import type { SessionReturnContextSummary } from './session-return-context.ts';
+import type { ConversationTitleSource } from '../core/conversation.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+export type SessionSnapshot = {
+  messages: Array<Record<string, unknown>>;
+  timestamp?: number;
+  title?: string;
+  titleSource?: ConversationTitleSource;
+  returnContext?: SessionReturnContextSummary;
+};
+
+export type RecoveryFileInfo = {
+  title: string;
+  timestamp: number;
+  sessionId: string;
+  returnContext?: SessionReturnContextSummary;
+};
+
+export type SessionPersistenceOptions = {
+  workingDirectory?: string;
+  homeDirectory?: string;
+  sessionManager?: SessionManager;
+};
+
+export type SessionPersistencePaths = {
+  readonly workingDirectory: string;
+  readonly homeDirectory: string;
+};
+
+function requireWorkingDirectory(options?: Pick<SessionPersistenceOptions, 'workingDirectory'>): string {
+  const workingDirectory = options?.workingDirectory;
+  if (!workingDirectory) {
+    throw new Error('Session persistence requires an explicit workingDirectory.');
+  }
+  return workingDirectory;
+}
+
+function requireHomeDirectory(options?: Pick<SessionPersistenceOptions, 'homeDirectory'>): string {
+  const homeDirectory = options?.homeDirectory;
+  if (!homeDirectory) {
+    throw new Error('Session persistence requires an explicit homeDirectory.');
+  }
+  return homeDirectory;
+}
+
+function resolveSessionPersistencePaths(options: SessionPersistenceOptions): SessionPersistencePaths {
+  return {
+    workingDirectory: requireWorkingDirectory(options),
+    homeDirectory: requireHomeDirectory(options),
+  };
+}
+
+function resolveSessionManager(options?: SessionPersistenceOptions): SessionManager {
+  if (options?.sessionManager) {
+    return options.sessionManager;
+  }
+  return new SessionManager(requireWorkingDirectory(options));
+}
+
+export function getUserSessionsDir(workingDirectory: string): string {
+  return join(workingDirectory, '.goodvibes', 'tui', 'sessions');
+}
+
+export function getLastSessionPointerPath(workingDirectory: string): string {
+  return join(getUserSessionsDir(workingDirectory), 'last-session.json');
+}
+
+export function getRecoveryFilePath(homeDirectory: string): string {
+  return join(homeDirectory, '.goodvibes', 'tui', 'recovery.jsonl');
+}
+
+export function generateUserSessionId(): string {
+  return randomBytes(4).toString('hex');
+}
+
+export function saveSession(
+  sessionId: string,
+  data: SessionSnapshot,
+  model: string,
+  provider: string,
+  title = '',
+  options?: SessionPersistenceOptions,
+): void {
+  try {
+    const sm = resolveSessionManager(options);
+    const meta: SessionMeta = {
+      title,
+      model,
+      provider,
+      timestamp: data.timestamp ?? Date.now(),
+      titleSource: data.titleSource,
+      returnContext: data.returnContext,
+    };
+    sm.save(sessionId, data.messages as Array<Record<string, unknown>>, meta);
+  } catch (e) {
+    logger.debug('saveSession failed', { error: summarizeError(e) });
+  }
+}
+
+export function persistConversation(
+  sessionId: string,
+  data: SessionSnapshot,
+  model: string,
+  provider: string,
+  title = '',
+  options?: SessionPersistenceOptions,
+): void {
+  saveSession(sessionId, data, model, provider, title, options);
+  writeLastSessionPointer(sessionId, options);
+}
+
+export function writeLastSessionPointer(sessionId: string, options?: SessionPersistenceOptions): void {
+  try {
+    const workingDirectory = requireWorkingDirectory(options);
+    const pointerPath = getLastSessionPointerPath(workingDirectory);
+    mkdirSync(dirname(pointerPath), { recursive: true });
+    writeFileSync(
+      pointerPath,
+      JSON.stringify({ sessionId, timestamp: new Date().toISOString() }) + '\n',
+      'utf-8',
+    );
+  } catch (e) {
+    logger.debug('writeLastSessionPointer failed', { error: summarizeError(e) });
+  }
+}
+
+export function readLastSessionPointer(options?: SessionPersistenceOptions): string | null {
+  try {
+    const workingDirectory = requireWorkingDirectory(options);
+    const pointerPath = getLastSessionPointerPath(workingDirectory);
+    if (!existsSync(pointerPath)) return null;
+    const data = JSON.parse(readFileSync(pointerPath, 'utf-8')) as { sessionId?: unknown };
+    if (typeof data.sessionId === 'string' && data.sessionId.trim()) return data.sessionId;
+  } catch (e) {
+    logger.debug('readLastSessionPointer failed', { error: summarizeError(e) });
+  }
+  return null;
+}
+
+export function loadLastConversation(options?: SessionPersistenceOptions): SessionSnapshot | null {
+  try {
+    const lastId = readLastSessionPointer(options);
+    const sm = resolveSessionManager(options);
+    if (!lastId) return null;
+
+    const { messages } = sm.load(lastId);
+    return { messages: messages as Array<Record<string, unknown>> };
+  } catch (e) {
+    logger.debug('loadLastConversation failed', { error: summarizeError(e) });
+  }
+  return null;
+}
+
+export function writeRecoveryFile(
+  snapshot: SessionSnapshot,
+  sessionId: string,
+  title = '',
+  options?: SessionPersistenceOptions,
+): void {
+  try {
+    if (!snapshot.messages.length) return;
+    const homeDirectory = requireHomeDirectory(options);
+    const recoveryFile = getRecoveryFilePath(homeDirectory);
+    const lines: string[] = [];
+    lines.push(JSON.stringify({ type: 'meta', sessionId, title, timestamp: Date.now() }));
+    if (snapshot.titleSource || snapshot.returnContext) {
+      lines[0] = JSON.stringify({
+        type: 'meta',
+        sessionId,
+        title,
+        timestamp: Date.now(),
+        titleSource: snapshot.titleSource,
+        returnContext: snapshot.returnContext,
+      });
+    }
+    for (const msg of snapshot.messages) {
+      lines.push(JSON.stringify({ type: 'message', ...msg }));
+    }
+    const tmpPath = recoveryFile + '.tmp';
+    mkdirSync(dirname(recoveryFile), { recursive: true });
+    writeFileSync(tmpPath, lines.join('\n') + '\n', 'utf-8');
+    renameSync(tmpPath, recoveryFile);
+  } catch (err) {
+    logger.debug('[Recovery] Write failed', { error: summarizeError(err) });
+  }
+}
+
+export function deleteRecoveryFile(options?: SessionPersistenceOptions): void {
+  try {
+    const homeDirectory = requireHomeDirectory(options);
+    unlinkSync(getRecoveryFilePath(homeDirectory));
+  } catch {
+    // missing file is fine
+  }
+}
+
+export function checkRecoveryFile(options?: SessionPersistenceOptions): RecoveryFileInfo | null {
+  try {
+    const { workingDirectory, homeDirectory } = resolveSessionPersistencePaths({
+      workingDirectory: requireWorkingDirectory(options),
+      homeDirectory: requireHomeDirectory(options),
+    });
+    const recoveryFile = getRecoveryFilePath(homeDirectory);
+    if (!existsSync(recoveryFile)) return null;
+    const recoveryMtime = statSync(recoveryFile).mtimeMs;
+    const pointerPath = getLastSessionPointerPath(workingDirectory);
+    if (existsSync(pointerPath)) {
+      const lastCleanMtime = statSync(pointerPath).mtimeMs;
+      if (recoveryMtime <= lastCleanMtime) return null;
+    }
+    const fd = openSync(recoveryFile, 'r');
+    const buf = Buffer.alloc(4096);
+    const bytesRead = readSync(fd, buf, 0, 4096, 0);
+    closeSync(fd);
+    const firstLine = buf.toString('utf-8', 0, bytesRead).split('\n')[0];
+    const meta = JSON.parse(firstLine) as { title?: string; timestamp?: number; sessionId?: string; returnContext?: SessionReturnContextSummary };
+    return {
+      title: meta.title ?? '',
+      timestamp: meta.timestamp ?? 0,
+      sessionId: meta.sessionId ?? '',
+      returnContext: meta.returnContext,
+    };
+  } catch (err) {
+    logger.debug('[Recovery] Check failed', { error: summarizeError(err) });
+    return null;
+  }
+}
+
+export function loadRecoveryConversation(options?: SessionPersistenceOptions): SessionSnapshot | null {
+  try {
+    const homeDirectory = requireHomeDirectory(options);
+    const recoveryFile = getRecoveryFilePath(homeDirectory);
+    const raw = readFileSync(recoveryFile, 'utf-8');
+    const lines = raw.split('\n').filter(Boolean);
+    if (lines.length < 2) return { messages: [] };
+    return {
+      title: (() => {
+        try {
+          const metaLine = JSON.parse(lines[0]) as { title?: string; titleSource?: ConversationTitleSource; returnContext?: SessionReturnContextSummary };
+          return metaLine.title;
+        } catch {
+          return undefined;
+        }
+      })(),
+      titleSource: (() => {
+        try {
+          const metaLine = JSON.parse(lines[0]) as { titleSource?: ConversationTitleSource };
+          return metaLine.titleSource;
+        } catch {
+          return undefined;
+        }
+      })(),
+      returnContext: (() => {
+        try {
+          const metaLine = JSON.parse(lines[0]) as { returnContext?: SessionReturnContextSummary };
+          return metaLine.returnContext;
+        } catch {
+          return undefined;
+        }
+      })(),
+      messages: lines.slice(1).map((line) => {
+        const { type: _type, ...rest } = JSON.parse(line) as { type: string } & Record<string, unknown>;
+        return rest;
+      }),
+    };
+  } catch (err) {
+    logger.debug('[Recovery] Load failed', { error: summarizeError(err) });
+    return null;
+  }
+}

package/src/runtime/session-return-context.ts

@@ -0,0 +1,195 @@
+import type { ConversationMessageSnapshot, ConversationTitleSource } from '../core/conversation.ts';
+import type { HelperModel } from '../config/helper-model.ts';
+import type { ConfigManager } from '../config/manager.ts';
+
+export type ReturnContextMode = 'off' | 'local' | 'assisted';
+
+export interface SessionContinuityHints {
+  readonly pendingApprovals?: number;
+  readonly activeTasks?: number;
+  readonly blockedTasks?: number;
+  readonly remoteContracts?: number;
+  readonly remoteRunners?: readonly string[];
+  readonly worktreeCount?: number;
+  readonly worktreePaths?: readonly string[];
+  readonly openPanels?: readonly string[];
+}
+
+export interface SessionReturnContextSummary {
+  readonly activityLabel: string;
+  readonly statusLabel: string;
+  readonly lastUserPrompt?: string;
+  readonly lastAssistantReply?: string;
+  readonly pendingApprovals: number;
+  readonly toolCallCount: number;
+  readonly toolResultCount: number;
+  readonly assistantTurnCount: number;
+  readonly userTurnCount: number;
+  readonly lastRole?: string;
+  readonly activeTasks?: number;
+  readonly blockedTasks?: number;
+  readonly remoteContracts?: number;
+  readonly remoteRunners?: readonly string[];
+  readonly worktreeCount?: number;
+  readonly worktreePaths?: readonly string[];
+  readonly openPanels?: readonly string[];
+  readonly lines: readonly string[];
+  readonly assistedNarrative?: string;
+}
+
+export interface PersistedSessionContext {
+  readonly titleSource?: ConversationTitleSource;
+  readonly returnContext?: SessionReturnContextSummary;
+}
+
+type ReturnContextConfig = Pick<ConfigManager, 'get'>;
+
+export function buildPersistedSessionContext(
+  messages: readonly ConversationMessageSnapshot[],
+  titleSource?: ConversationTitleSource,
+  hints?: SessionContinuityHints,
+): PersistedSessionContext {
+  return {
+    titleSource,
+    returnContext: buildLocalReturnContextSummary(messages, hints),
+  };
+}
+
+function truncate(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, Math.max(0, max - 1)).trimEnd()}…`;
+}
+
+function textContent(message: ConversationMessageSnapshot | undefined): string {
+  if (!message) return '';
+  if (typeof message.content === 'string') return message.content;
+  if (!Array.isArray(message.content)) return '';
+  return message.content
+    .filter((part): part is { type: 'text'; text: string } => part.type === 'text')
+    .map((part) => part.text)
+    .join(' ');
+}
+
+export function getReturnContextMode(configManager: ReturnContextConfig): ReturnContextMode {
+  return (configManager.get('behavior.returnContextMode') as ReturnContextMode | undefined) ?? 'off';
+}
+
+export function buildLocalReturnContextSummary(
+  messages: readonly ConversationMessageSnapshot[],
+  hints?: SessionContinuityHints,
+): SessionReturnContextSummary {
+  const userMessages = messages.filter((message) => message.role === 'user');
+  const assistantMessages = messages.filter((message) => message.role === 'assistant');
+  const toolMessages = messages.filter((message) => message.role === 'tool');
+  const pendingApprovals = hints?.pendingApprovals
+    ?? messages.filter((message) => message.role === 'system' && typeof message.content === 'string' && /approval/i.test(message.content)).length;
+  const lastUser = [...messages].reverse().find((message) => message.role === 'user');
+  const lastAssistant = [...messages].reverse().find((message) => message.role === 'assistant');
+  const lastMessage = messages[messages.length - 1];
+
+  const lastUserPrompt = truncate(textContent(lastUser), 120);
+  const lastAssistantReply = truncate(textContent(lastAssistant), 120);
+
+  let activityLabel = 'Fresh session';
+  let statusLabel = 'idle';
+  if (lastMessage?.role === 'assistant') {
+    activityLabel = 'assistant replied';
+    statusLabel = 'ready for next turn';
+  } else if (lastMessage?.role === 'tool') {
+    activityLabel = 'tool work completed';
+    statusLabel = 'awaiting assistant follow-up';
+  } else if (lastMessage?.role === 'user') {
+    activityLabel = 'user prompt queued';
+    statusLabel = 'awaiting response';
+  } else if (lastMessage?.role === 'system') {
+    activityLabel = 'system/operator update';
+    statusLabel = 'review recommended';
+  }
+
+  const lines: string[] = [];
+  lines.push(`Activity: ${activityLabel}`);
+  lines.push(`Status: ${statusLabel}`);
+  if (lastUserPrompt) lines.push(`Last prompt: ${lastUserPrompt}`);
+  if (lastAssistantReply) lines.push(`Last reply: ${lastAssistantReply}`);
+  if (pendingApprovals > 0) lines.push(`Pending approvals spotted: ${pendingApprovals}`);
+  if (toolMessages.length > 0) lines.push(`Tool results in session: ${toolMessages.length}`);
+  if ((hints?.activeTasks ?? 0) > 0 || (hints?.blockedTasks ?? 0) > 0) {
+    lines.push(`Tasks: active ${hints?.activeTasks ?? 0}, blocked ${hints?.blockedTasks ?? 0}`);
+  }
+  if ((hints?.remoteContracts ?? 0) > 0) {
+    lines.push(`Remote contracts: ${hints?.remoteContracts}`);
+  }
+  if ((hints?.remoteRunners?.length ?? 0) > 0) {
+    lines.push(`Remote runners: ${hints!.remoteRunners!.slice(0, 3).join(', ')}`);
+  }
+  if ((hints?.worktreeCount ?? 0) > 0) {
+    lines.push(`Worktrees tracked: ${hints?.worktreeCount}`);
+  }
+  if ((hints?.worktreePaths?.length ?? 0) > 0) {
+    lines.push(`Worktree paths: ${hints!.worktreePaths!.slice(0, 2).join(', ')}`);
+  }
+  if ((hints?.openPanels?.length ?? 0) > 0) {
+    lines.push(`Open panels: ${hints!.openPanels!.slice(0, 4).join(', ')}`);
+  }
+
+  return {
+    activityLabel,
+    statusLabel,
+    lastUserPrompt: lastUserPrompt || undefined,
+    lastAssistantReply: lastAssistantReply || undefined,
+    pendingApprovals,
+    toolCallCount: assistantMessages.reduce((count, message) => count + (message.toolCalls?.length ?? 0), 0),
+    toolResultCount: toolMessages.length,
+    assistantTurnCount: assistantMessages.length,
+    userTurnCount: userMessages.length,
+    lastRole: lastMessage?.role,
+    ...(typeof hints?.activeTasks === 'number' ? { activeTasks: hints.activeTasks } : {}),
+    ...(typeof hints?.blockedTasks === 'number' ? { blockedTasks: hints.blockedTasks } : {}),
+    ...(typeof hints?.remoteContracts === 'number' ? { remoteContracts: hints.remoteContracts } : {}),
+    ...(hints?.remoteRunners ? { remoteRunners: [...hints.remoteRunners] } : {}),
+    ...(typeof hints?.worktreeCount === 'number' ? { worktreeCount: hints.worktreeCount } : {}),
+    ...(hints?.worktreePaths ? { worktreePaths: [...hints.worktreePaths] } : {}),
+    ...(hints?.openPanels ? { openPanels: [...hints.openPanels] } : {}),
+    lines,
+  };
+}
+
+export async function maybeAssistReturnContextSummary(
+  configManager: ReturnContextConfig,
+  helperModel: Pick<HelperModel, 'chat'>,
+  summary: SessionReturnContextSummary,
+): Promise<SessionReturnContextSummary> {
+  if (getReturnContextMode(configManager) !== 'assisted') return summary;
+
+  const enabled = configManager.get('helper.enabled') as boolean | undefined;
+  if (!enabled) return summary;
+
+  const prompt = [
+    'You are generating a terse resume summary for a terminal coding session.',
+    'Return one sentence under 160 characters.',
+    'Focus on what the operator should look at first.',
+    '',
+    `Activity: ${summary.activityLabel}`,
+    `Status: ${summary.statusLabel}`,
+    ...(summary.lastUserPrompt ? [`Last prompt: ${summary.lastUserPrompt}`] : []),
+    ...(summary.lastAssistantReply ? [`Last reply: ${summary.lastAssistantReply}`] : []),
+    `Pending approvals: ${summary.pendingApprovals}`,
+    `Tool calls: ${summary.toolCallCount}`,
+    `Tool results: ${summary.toolResultCount}`,
+  ].join('\n');
+
+  const response = (await helperModel.chat('tool_summarize', prompt, { maxTokens: 80, helperOnly: true })).trim();
+  if (!response) return summary;
+  return {
+    ...summary,
+    assistedNarrative: truncate(response.replace(/\s+/g, ' '), 160),
+  };
+}
+
+export function formatReturnContextForDisplay(summary: SessionReturnContextSummary | undefined): string[] {
+  if (!summary) return [];
+  const lines = [...summary.lines];
+  if (summary.assistedNarrative) {
+    lines.unshift(`Assist: ${summary.assistedNarrative}`);
+  }
+  return lines;
+}