@agentuity/opencode 1.0.15 → 1.0.17

package/src/plugin/hooks/cadence.ts

@@ -2,6 +2,19 @@ import type { PluginInput } from '@opencode-ai/plugin';
 import type { CoderConfig } from '../../types';
 import type { BackgroundManager } from '../../background';
 import type { OpenCodeDBReader, SessionTreeNode } from '../../sqlite';
+import type { CompactionStats } from '../../sqlite/types';
+import {
+	getCurrentBranch,
+	buildCustomCompactionPrompt,
+	fetchAndFormatPlanningState,
+	getImageDescriptions,
+	getRecentToolCallSummaries,
+	storePreCompactionSnapshot,
+	persistCadenceStateToKV,
+	restoreCadenceStateFromKV,
+	formatCompactionDiagnostics,
+	countListItems,
+} from './compaction-utils';
 
 /** Compacting hook input/output types */
 type CompactingInput = { sessionID: string };
@@ -13,27 +26,12 @@ export interface CadenceHooks {
 	onCompacting: (input: CompactingInput, output: CompactingOutput) => Promise<void>;
 	/** Check if a session is currently in Cadence mode */
 	isActiveCadenceSession: (sessionId: string) => boolean;
+	/** Lazy restore: check KV for persisted Cadence state and populate in-memory Map */
+	tryRestoreFromKV: (sessionId: string) => Promise<boolean>;
 }
 
 const COMPLETION_PATTERN = /<promise>\s*DONE\s*<\/promise>/i;
 
-/**
- * Get the current git branch name.
- */
-async function getCurrentBranch(): Promise<string> {
-	try {
-		const proc = Bun.spawn(['git', 'branch', '--show-current'], {
-			stdout: 'pipe',
-			stderr: 'pipe',
-		});
-		const stdout = await new Response(proc.stdout).text();
-		await proc.exited;
-		return stdout.trim() || 'unknown';
-	} catch {
-		return 'unknown';
-	}
-}
-
 // Ultrawork trigger keywords - case insensitive matching
 const ULTRAWORK_TRIGGERS = [
 	'ultrawork',
@@ -69,11 +67,14 @@ interface CadenceSessionState {
  */
 export function createCadenceHooks(
 	ctx: PluginInput,
-	_config: CoderConfig,
+	config: CoderConfig,
 	backgroundManager?: BackgroundManager,
-	dbReader?: OpenCodeDBReader
+	dbReader?: OpenCodeDBReader,
+	lastUserMessages?: Map<string, string>
 ): CadenceHooks {
 	const activeCadenceSessions = new Map<string, CadenceSessionState>();
+	const nonCadenceSessions = new Set<string>();
+	const NON_CADENCE_CACHE_MAX = 500;
 
 	const log = (msg: string) => {
 		ctx.client.app.log({
@@ -90,11 +91,14 @@ export function createCadenceHooks(
 			const sessionId = extractSessionId(input);
 			if (!sessionId) return;
 
-			const messageText = extractMessageText(output);
-			if (!messageText) return;
-
-			// Check if this is a Cadence start command or ultrawork trigger
-			const cadenceType = getCadenceTriggerType(messageText);
+			// Use the USER's message (from chat.params) for trigger detection,
+			// not the model's output — avoids false positives when the model
+			// uses phrases like "go deep" or "be thorough" in its response.
+			// Delete after read — entries are transient (set in chat.params,
+			// consumed here in chat.message) so no unbounded Map growth.
+			const userText = lastUserMessages?.get(sessionId) ?? '';
+			lastUserMessages?.delete(sessionId);
+			const cadenceType = getCadenceTriggerType(userText);
 			if (cadenceType && !activeCadenceSessions.has(sessionId)) {
 				log(`Cadence started for session ${sessionId} via ${cadenceType}`);
 				const now = new Date().toISOString();
@@ -105,6 +109,8 @@ export function createCadenceHooks(
 					lastActivity: now,
 				};
 				activeCadenceSessions.set(sessionId, state);
+				nonCadenceSessions.delete(sessionId);
+				persistCadenceStateToKV(sessionId, { ...state }).catch(() => {});
 
 				// If triggered by ultrawork keywords, inject [CADENCE MODE] tag
 				if (cadenceType === 'ultrawork') {
@@ -115,6 +121,12 @@ export function createCadenceHooks(
 				return;
 			}
 
+			// Everything below parses the MODEL's output for structured tags
+			// (CADENCE_STATUS, iteration counts, completion signals) that the
+			// model intentionally emits — these are NOT false-positive-prone.
+			const messageText = extractMessageText(output);
+			if (!messageText) return;
+
 			// Check if this session is in Cadence mode
 			const state = activeCadenceSessions.get(sessionId);
 			if (!state) {
@@ -146,6 +158,7 @@ export function createCadenceHooks(
 				if (changed) {
 					const loopInfo = state.loopId ? ` · ${state.loopId}` : '';
 					showToast(ctx, `⚡ Cadence · ${state.iteration}/${state.maxIterations}${loopInfo}`);
+					persistCadenceStateToKV(sessionId, { ...state }).catch(() => {});
 				}
 				return;
 			}
@@ -158,6 +171,7 @@ export function createCadenceHooks(
 					state.iteration = newIteration;
 					const loopInfo = state.loopId ? ` · ${state.loopId}` : '';
 					showToast(ctx, `⚡ Cadence · ${state.iteration}/${state.maxIterations}${loopInfo}`);
+					persistCadenceStateToKV(sessionId, { ...state }).catch(() => {});
 				}
 			}
 
@@ -183,7 +197,10 @@ export function createCadenceHooks(
 
 			log(`Event received: ${event.type}`);
 
-			// Handle session.compacted - save compaction AND continue loop
+			// Handle session.compacted - save compaction AND continue loop.
+			// Note: Compaction continues in the SAME session (via session.prompt with
+			// the existing sessionId), so permissions configured in the config hook
+			// (plugin.ts) are automatically inherited — no re-application needed.
 			if (event.type === 'session.compacted') {
 				const sessionId = event.sessionId;
 				if (!sessionId) return;
@@ -285,6 +302,8 @@ Continue Cadence iteration ${state.iteration} of ${state.maxIterations}
 		/**
 		 * Called during context compaction to inject Cadence state.
 		 * This ensures the compaction summary includes critical loop state.
+		 * Uses output.prompt to REPLACE the default compaction prompt with
+		 * enriched context (planning state, images, tool calls, diagnostics).
 		 */
 		async onCompacting(input: CompactingInput, output: CompactingOutput): Promise<void> {
 			const sessionId = input.sessionID;
@@ -298,12 +317,53 @@ Continue Cadence iteration ${state.iteration} of ${state.maxIterations}
 			log(`Injecting Cadence context during compaction for session ${sessionId}`);
 			showToast(ctx, '💾 Compacting Cadence context...');
 
-			// Get current git branch
-			const branch = await getCurrentBranch();
+			// Config flags for compaction behavior
+			const compactionCfg = config?.compaction ?? {};
+			const useCustomPrompt = compactionCfg.customPrompt !== false;
+			const useInlinePlanning = compactionCfg.inlinePlanning !== false;
+			const useImageAwareness = compactionCfg.imageAwareness !== false;
+			const useSnapshotToKV = compactionCfg.snapshotToKV !== false;
+			const maxTokens = compactionCfg.maxContextTokens ?? 4000;
+
+			// 1. Build custom compaction instructions
+			const instructions = useCustomPrompt ? buildCustomCompactionPrompt('cadence') : null;
+
+			// 2. Gather enrichment data in parallel
+			const toolCallLimit = config?.compaction?.toolCallSummaryLimit ?? 5;
+			const [branch, planningState, imageDescs, toolSummaries] = await Promise.all([
+				getCurrentBranch(),
+				useInlinePlanning ? fetchAndFormatPlanningState(sessionId) : Promise.resolve(null),
+				useImageAwareness
+					? Promise.resolve(getImageDescriptions(dbReader ?? null, sessionId))
+					: Promise.resolve(null),
+				Promise.resolve(getRecentToolCallSummaries(dbReader ?? null, sessionId, toolCallLimit)),
+			]);
+
+			// 3. Build Cadence state section
+			const cadenceStateSection = `## CADENCE MODE ACTIVE
+
+This session is running in Cadence mode (long-running autonomous loop).
 
-			// Get active background tasks for this session
+**Cadence State:**
+- Session ID: ${sessionId}
+- Loop ID: ${state.loopId ?? 'unknown'}
+- Branch: ${branch}
+- Started: ${state.startedAt}
+- Iteration: ${state.iteration} / ${state.maxIterations}
+- Last activity: ${state.lastActivity}
+
+**Session Record Location:**
+\`session:${sessionId}\` in agentuity-opencode-memory
+
+After compaction:
+1. Memory will save this summary and update the session record
+2. Memory should update planning.progress with this compaction
+3. Lead will continue the loop from iteration ${state.iteration}
+4. Use 5-Question Reboot to re-orient: Where am I? Where going? Goal? Learned? Done?`;
+
+			// 4. Build background tasks section
 			const tasks = backgroundManager?.getTasksByParent(sessionId) ?? [];
-			let backgroundTaskContext = '';
+			let backgroundSection: string | null = null;
 
 			if (tasks.length > 0) {
 				const taskList = tasks
@@ -313,9 +373,7 @@ Continue Cadence iteration ${state.iteration} of ${state.maxIterations}
 					)
 					.join('\n');
 
-				backgroundTaskContext = `
-
-## Active Background Tasks
+				backgroundSection = `## Active Background Tasks
 
 This session has ${tasks.length} background task(s) running in separate sessions:
 ${taskList}
@@ -324,52 +382,70 @@ ${taskList}
 Use \`agentuity_background_output({ task_id: "..." })\` to check their status.
 Use \`agentuity_session_dashboard({ session_id: "..." })\` to get a full session tree with status, costs, and health summary for Lead-of-Leads monitoring.
 
-**Tip:** If you spawned child Leads for parallel work, delegate monitoring to BackgroundMonitor:
-\`\`\`typescript
-agentuity_background_task({
-  agent: "monitor",
-  task: "Monitor these background tasks and report when all complete:\\n${tasks.map((t) => `- ${t.id}`).join('\\n')}",
-  description: "Monitor child tasks"
-})
-\`\`\`
-`;
+**Tip:** A Monitor agent is auto-launched to watch these tasks. You will receive \`[BACKGROUND TASK COMPLETED]\` notifications as each task finishes, and \`[ALL BACKGROUND TASKS COMPLETE]\` when all are done. Use \`agentuity_session_dashboard\` for a unified progress view.`;
 			}
 
-			output.context.push(`
-## CADENCE MODE ACTIVE
-
-This session is running in Cadence mode (long-running autonomous loop).
-
-**Cadence State:**
-- Session ID: ${sessionId}
-- Loop ID: ${state.loopId ?? 'unknown'}
-- Branch: ${branch}
-- Started: ${state.startedAt}
-- Iteration: ${state.iteration} / ${state.maxIterations}
-- Last activity: ${state.lastActivity}
-
-**Session Record Location:**
-\`session:${sessionId}\` in agentuity-opencode-memory
+			// 5. Build SQLite dashboard section
+			const dashboardSection = buildSqliteDashboardSummary(dbReader, sessionId);
+
+			// 6. Combine everything into the full prompt
+			const sections: string[] = [];
+			if (instructions) sections.push(instructions);
+			sections.push(cadenceStateSection);
+			if (backgroundSection) sections.push(backgroundSection);
+			if (planningState) sections.push(planningState);
+			if (imageDescs) sections.push(imageDescs);
+			if (toolSummaries) sections.push(toolSummaries);
+			if (dashboardSection) sections.push(dashboardSection);
+
+			// 7. Add diagnostics
+			const stats: CompactionStats = {
+				planningPhasesCount: countListItems(planningState),
+				backgroundTasksCount: tasks.length,
+				imageDescriptionsCount: countListItems(imageDescs),
+				toolCallSummariesCount: countListItems(toolSummaries),
+				estimatedTokens: Math.ceil(sections.join('\n\n').length / 4),
+			};
+			const diagnostics = formatCompactionDiagnostics(stats);
+			if (diagnostics) sections.push(diagnostics);
+
+			// 8. Enforce token budget
+			let fullPrompt = sections.join('\n\n');
+			const estimatedTokens = Math.ceil(fullPrompt.length / 4);
+			if (maxTokens > 0 && estimatedTokens > maxTokens) {
+				// Trim least-critical sections first
+				const trimOrder = [diagnostics, toolSummaries, imageDescs, planningState].filter(
+					Boolean
+				);
+				let trimmed = [...sections];
+				for (const candidate of trimOrder) {
+					if (Math.ceil(trimmed.join('\n\n').length / 4) <= maxTokens) break;
+					trimmed = trimmed.filter((s) => s !== candidate);
+				}
+				fullPrompt = trimmed.join('\n\n');
+			}
 
-**Planning State:**
-If this session has planning active, the session record contains:
-- \`planning.prdKey\` - Link to the PRD being executed
-- \`planning.objective\` - What we're trying to accomplish
-- \`planning.phases\` - Current phases with status and notes
-- \`planning.current\` - Current phase
-- \`planning.findings\` - Discoveries made during work
-- \`planning.errors\` - Failures to avoid repeating
-${backgroundTaskContext}
-After compaction:
-1. Memory will save this summary and update the session record
-2. Memory should update planning.progress with this compaction
-3. Lead will continue the loop from iteration ${state.iteration}
-4. Use 5-Question Reboot to re-orient: Where am I? Where going? Goal? Learned? Done?
-`);
+			// 9. Set the full prompt or push to context
+			if (useCustomPrompt) {
+				output.prompt = fullPrompt;
+			} else {
+				output.context.push(fullPrompt);
+			}
 
-			const dashboardSummary = buildSqliteDashboardSummary(dbReader, sessionId);
-			if (dashboardSummary) {
-				output.context.push(dashboardSummary);
+			// 10. Store pre-compaction snapshot to KV (fire-and-forget)
+			if (useSnapshotToKV) {
+				storePreCompactionSnapshot(sessionId, {
+					timestamp: new Date().toISOString(),
+					sessionId,
+					planningState: planningState ? { raw: planningState } : undefined,
+					backgroundTasks: tasks.map((t) => ({
+						id: t.id,
+						description: t.description || 'No description',
+						status: t.status,
+					})),
+					cadenceState: state ? { ...state } : undefined,
+					branch,
+				}).catch(() => {}); // Fire and forget
 			}
 		},
 
@@ -380,6 +456,44 @@ After compaction:
 		isActiveCadenceSession(sessionId: string): boolean {
 			return activeCadenceSessions.has(sessionId);
 		},
+
+		/**
+		 * Lazy restore: check KV for persisted Cadence state and populate in-memory Map.
+		 * Called before routing decisions to recover state after plugin restarts.
+		 * Returns true if state was found and restored.
+		 */
+		async tryRestoreFromKV(sessionId: string): Promise<boolean> {
+			// Already in memory — nothing to restore
+			if (activeCadenceSessions.has(sessionId)) return true;
+			// Known non-Cadence session — skip KV lookup
+			if (nonCadenceSessions.has(sessionId)) return false;
+
+			try {
+				const kvState = await restoreCadenceStateFromKV(sessionId);
+				if (!kvState) {
+					if (nonCadenceSessions.size >= NON_CADENCE_CACHE_MAX) {
+						nonCadenceSessions.clear();
+					}
+					nonCadenceSessions.add(sessionId);
+					return false;
+				}
+
+				const state: CadenceSessionState = {
+					startedAt: (kvState.startedAt as string) ?? new Date().toISOString(),
+					loopId: kvState.loopId as string | undefined,
+					iteration: (kvState.iteration as number) ?? 1,
+					maxIterations: (kvState.maxIterations as number) ?? 50,
+					lastActivity: (kvState.lastActivity as string) ?? new Date().toISOString(),
+				};
+				activeCadenceSessions.set(sessionId, state);
+				log(
+					`Restored Cadence state from KV for session ${sessionId} (iteration ${state.iteration}/${state.maxIterations})`
+				);
+				return true;
+			} catch {
+				return false;
+			}
+		},
 	};
 }
 

package/src/plugin/hooks/compaction-utils.ts

@@ -0,0 +1,291 @@
+import type { OpenCodeDBReader } from '../../sqlite/reader';
+import type { CompactionStats, DBNonTextPart, PreCompactionSnapshot } from '../../sqlite/types';
+
+/**
+ * Get the current git branch name.
+ * Moved here from cadence.ts and session-memory.ts to deduplicate.
+ */
+export async function getCurrentBranch(): Promise<string> {
+	try {
+		const proc = Bun.spawn(['git', 'branch', '--show-current'], {
+			stdout: 'pipe',
+			stderr: 'pipe',
+		});
+		const stdout = await new Response(proc.stdout).text();
+		await proc.exited;
+		return stdout.trim() || 'unknown';
+	} catch {
+		return 'unknown';
+	}
+}
+
+/**
+ * Access Agentuity KV storage via CLI.
+ * All calls are wrapped in try/catch — returns null on failure.
+ */
+async function kvGet(namespace: string, key: string): Promise<unknown | null> {
+	try {
+		const proc = Bun.spawn(['agentuity', 'cloud', 'kv', 'get', namespace, key, '--json'], {
+			stdout: 'pipe',
+			stderr: 'pipe',
+		});
+		const output = await new Response(proc.stdout).text();
+		const exitCode = await proc.exited;
+		if (exitCode !== 0) return null;
+		return JSON.parse(output);
+	} catch {
+		return null;
+	}
+}
+
+async function kvSet(namespace: string, key: string, value: unknown): Promise<boolean> {
+	try {
+		const proc = Bun.spawn(
+			['agentuity', 'cloud', 'kv', 'set', namespace, key, JSON.stringify(value)],
+			{ stdout: 'pipe', stderr: 'pipe' }
+		);
+		const exitCode = await proc.exited;
+		return exitCode === 0;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Build the custom compaction prompt for our agent system.
+ * This REPLACES the default OpenCode compaction prompt via output.prompt.
+ */
+export function buildCustomCompactionPrompt(mode: 'cadence' | 'regular'): string {
+	const cadenceSection =
+		mode === 'cadence'
+			? `
+
+## Cadence Loop State
+- Loop ID, iteration number, max iterations
+- Current phase and what's in progress
+- Whether this is a Lead-of-Leads session with child tasks`
+			: '';
+
+	return `You are generating a continuation context for a multi-agent coding system (Agentuity Coder). Your summary will be the ONLY context the orchestrating Lead agent has after this compaction. Preserve everything needed for seamless continuation.
+
+## CRITICAL — Preserve These Verbatim
+1. The current task/objective (quote the user's original request exactly)
+2. All background task IDs (bg_xxx) with status, purpose, and session IDs
+3. Active planning state: current phase, completed phases, next steps, blockers
+4. ALL file paths being actively worked on (with role: created/modified/read)
+5. Key decisions made and their rationale
+6. Any corrections or gotchas discovered during the session
+7. Todo list state (what's done, in progress, pending)
+8. Descriptions of any images or attachments that appeared in conversation${cadenceSection}
+
+## Structure Your Summary As:
+
+### Active Task
+[Verbatim objective + what the agent was doing when compaction fired]
+
+### Planning State
+[Phases with status. Include phase notes, not just titles.]
+
+### Background Tasks
+[bg_xxx: description → status (running/completed/errored). Include session IDs.]
+
+### Key Context
+[Decisions, constraints, user preferences, corrections discovered]
+
+### Active Files
+[filepath → role (creating/modifying/reading) + what's being done to it]
+
+### Images & Attachments
+[Describe any images/screenshots: what they showed, when they appeared, why they mattered]
+
+### Next Steps
+[What should happen immediately after compaction resumes]
+
+## Rules
+- Use specific file paths, task IDs, phase names — NOT vague references.
+- State what tools returned, not just that they were called.
+- NEVER drop background task references — the agent MUST know what's still running.
+- Prefer completeness over brevity — this is the agent's entire working memory.`;
+}
+
+/**
+ * Fetch planning state from KV and format as markdown.
+ * Returns null if KV is unavailable or no planning state exists.
+ */
+export async function fetchAndFormatPlanningState(sessionId: string): Promise<string | null> {
+	try {
+		const record = await kvGet('agentuity-opencode-memory', `session:${sessionId}`);
+		if (!record || typeof record !== 'object') return null;
+
+		const data = (record as Record<string, unknown>).data ?? record;
+		const planning = (data as Record<string, unknown>).planning as
+			| Record<string, unknown>
+			| undefined;
+		if (!planning) return null;
+
+		const lines: string[] = ['## Planning State (from KV)'];
+		if (planning.objective) lines.push(`**Objective:** ${planning.objective}`);
+		if (planning.current) lines.push(`**Current:** ${planning.current}`);
+		if (planning.next) lines.push(`**Next:** ${planning.next}`);
+
+		const phases = planning.phases as Array<Record<string, unknown>> | undefined;
+		if (phases?.length) {
+			lines.push('', '### Phases:');
+			for (const p of phases) {
+				const status = p.status ?? 'unknown';
+				const title = p.title ?? p.content ?? 'untitled';
+				const notes = p.notes ? ` — ${String(p.notes).slice(0, 100)}` : '';
+				lines.push(`- [${status}] ${title}${notes}`);
+			}
+		}
+
+		const findings = planning.findings as string[] | undefined;
+		if (findings?.length) {
+			lines.push('', '### Key Findings:');
+			for (const f of findings.slice(0, 5)) {
+				lines.push(`- ${String(f).slice(0, 150)}`);
+			}
+		}
+
+		const errors = planning.errors as string[] | undefined;
+		if (errors?.length) {
+			lines.push('', '### Errors to Avoid:');
+			for (const e of errors.slice(0, 3)) {
+				lines.push(`- ${String(e).slice(0, 150)}`);
+			}
+		}
+
+		return lines.join('\n');
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Get image/attachment descriptions from SQLite for compaction context.
+ * Returns brief metadata about non-text parts in the conversation.
+ */
+export function getImageDescriptions(
+	dbReader: OpenCodeDBReader | null,
+	sessionId: string
+): string | null {
+	if (!dbReader?.isAvailable()) return null;
+
+	try {
+		const parts = dbReader.getNonTextParts(sessionId);
+		if (!parts.length) return null;
+
+		// Filter to image-like parts (not tool calls — those are separate)
+		const imageParts = parts.filter(
+			(p: DBNonTextPart) => !['tool-invocation', 'tool-result', 'text'].includes(p.type)
+		);
+		if (!imageParts.length) return null;
+
+		const lines: string[] = ['## Images & Attachments'];
+		for (const part of imageParts.slice(0, 10)) {
+			const when = part.timestamp ? ` at ${part.timestamp}` : '';
+			lines.push(`- [${part.type}]${when}: message ${part.messageId}`);
+		}
+		return lines.join('\n');
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Get recent tool call summaries for compaction context.
+ * CONCISE — capped at limit calls, brief descriptions only.
+ */
+export function getRecentToolCallSummaries(
+	dbReader: OpenCodeDBReader | null,
+	sessionId: string,
+	limit: number = 5
+): string | null {
+	if (!dbReader?.isAvailable() || limit <= 0) return null;
+
+	try {
+		const calls = dbReader.getRecentToolCalls(sessionId, limit);
+		if (!calls.length) return null;
+
+		const lines: string[] = ['## Recent Tool Activity'];
+		for (const call of calls) {
+			const inputBrief = call.input ? ` — ${String(call.input).slice(0, 80)}` : '';
+			const outputBrief = call.output ? ` → ${String(call.output).slice(0, 80)}` : '';
+			lines.push(`- ${call.toolName}${inputBrief}${outputBrief}`);
+		}
+		return lines.join('\n');
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Store a pre-compaction snapshot to KV as a recovery mechanism.
+ */
+export async function storePreCompactionSnapshot(
+	sessionId: string,
+	snapshot: PreCompactionSnapshot
+): Promise<void> {
+	try {
+		await kvSet('agentuity-opencode-memory', `compaction:snapshot:${sessionId}`, snapshot);
+	} catch {
+		// Silently fail — this is a best-effort recovery mechanism
+	}
+}
+
+/**
+ * Persist Cadence session state to KV for recovery after plugin restart.
+ */
+export async function persistCadenceStateToKV(
+	sessionId: string,
+	state: Record<string, unknown>
+): Promise<void> {
+	try {
+		await kvSet('agentuity-opencode-memory', `cadence:active:${sessionId}`, state);
+	} catch {
+		// Silently fail
+	}
+}
+
+/**
+ * Restore Cadence session state from KV.
+ */
+export async function restoreCadenceStateFromKV(
+	sessionId: string
+): Promise<Record<string, unknown> | null> {
+	try {
+		const state = await kvGet('agentuity-opencode-memory', `cadence:active:${sessionId}`);
+		return state as Record<string, unknown> | null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Format compaction diagnostics — brief summary of what was preserved.
+ */
+export function formatCompactionDiagnostics(stats: CompactionStats): string {
+	const parts: string[] = [];
+	if (stats.planningPhasesCount > 0) parts.push(`${stats.planningPhasesCount} planning phases`);
+	if (stats.backgroundTasksCount > 0) parts.push(`${stats.backgroundTasksCount} background tasks`);
+	if (stats.imageDescriptionsCount > 0) parts.push(`${stats.imageDescriptionsCount} image refs`);
+	if (stats.toolCallSummariesCount > 0) parts.push(`${stats.toolCallSummariesCount} tool calls`);
+
+	if (!parts.length) return '';
+	return `> **Compaction preserved:** ${parts.join(', ')} (~${stats.estimatedTokens} tokens injected)`;
+}
+
+/** Count markdown list items in a string */
+export function countListItems(s: string | null): number {
+	if (!s) return 0;
+	return (s.match(/^- /gm) ?? []).length;
+}
+
+// Re-export types used by consumers of this module
+export type { CompactionConfig } from '../../types';
+export type {
+	CompactionStats,
+	DBNonTextPart,
+	DBToolCallSummary,
+	PreCompactionSnapshot,
+} from '../../sqlite/types';