@agentuity/opencode 1.0.15 → 1.0.17

package/src/plugin/hooks/completion.ts

@@ -0,0 +1,61 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+import type { CoderConfig } from '../../types';
+
+export interface CompletionHooks {
+	onParams: (input: unknown) => void;
+	onMessage: (input: unknown) => void;
+}
+
+/**
+ * Creates hooks for logging agent completion metrics.
+ *
+ * Tracks the start of each LLM call (via chat.params) and logs
+ * agent name, model, and duration when the response arrives (via chat.message).
+ */
+export function createCompletionHooks(ctx: PluginInput, _config: CoderConfig): CompletionHooks {
+	const startTimes = new Map<string, { startedAt: number; agent?: string; model?: string }>();
+
+	return {
+		onParams(input: unknown): void {
+			const inp = input as {
+				sessionID?: string;
+				agent?: string;
+				model?: string;
+			};
+			if (!inp.sessionID) return;
+			startTimes.set(inp.sessionID, {
+				startedAt: Date.now(),
+				agent: inp.agent,
+				model: inp.model,
+			});
+		},
+
+		onMessage(input: unknown): void {
+			const inp = input as { sessionID?: string };
+			if (!inp.sessionID) return;
+
+			const start = startTimes.get(inp.sessionID);
+			if (!start) return;
+
+			const durationMs = Date.now() - start.startedAt;
+			const durationSec = (durationMs / 1000).toFixed(1);
+
+			const logLine = `Completion: agent=${start.agent ?? 'unknown'} model=${start.model ?? 'unknown'} duration=${durationSec}s`;
+
+			// Verbose local logging for immediate visibility
+			console.debug(`[agentuity-coder] ${logLine}`);
+
+			// Also send to the OpenCode log service
+			ctx.client.app.log({
+				body: {
+					service: 'agentuity-coder',
+					level: 'debug',
+					message: logLine,
+				},
+			});
+
+			// Clean up after logging
+			startTimes.delete(inp.sessionID);
+		},
+	};
+}

package/src/plugin/hooks/params.ts

@@ -1,5 +1,5 @@
 import type { PluginInput } from '@opencode-ai/plugin';
-import type { CoderConfig } from '../../types';
+import type { AgentConfig, CoderConfig } from '../../types';
 
 export interface ParamsHooks {
 	onParams: (input: unknown, output: unknown) => Promise<void>;
@@ -95,7 +95,11 @@ function detectMode(
 	return null;
 }
 
-export function createParamsHooks(ctx: PluginInput, _config: CoderConfig): ParamsHooks {
+export function createParamsHooks(
+	ctx: PluginInput,
+	_config: CoderConfig,
+	lastUserMessages?: Map<string, string>
+): ParamsHooks {
 	return {
 		async onParams(input: unknown, output: unknown): Promise<void> {
 			// Input contains: sessionID, agent, model, provider, message
@@ -117,6 +121,11 @@ export function createParamsHooks(ctx: PluginInput, _config: CoderConfig): Param
 			const messageContent = inputObj.message?.content || '';
 			if (!messageContent) return;
 
+			// Store user message text for downstream hooks (e.g. cadence trigger detection)
+			if (lastUserMessages && inputObj.sessionID) {
+				lastUserMessages.set(inputObj.sessionID, messageContent);
+			}
+
 			// Check for dynamic mode triggers
 			const detected = detectMode(messageContent);
 			if (!detected) return;
@@ -190,3 +199,99 @@ export function createParamsHooks(ctx: PluginInput, _config: CoderConfig): Param
  *
  * Note: Triggers use multi-word phrases to avoid false positives from common words.
  */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Model Fallback Chain
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Retryable HTTP status codes that should trigger model fallback */
+export const RETRYABLE_STATUS_CODES = [429, 500, 502, 503] as const;
+
+/**
+ * Tracks API errors per agent to enable model fallback on subsequent calls.
+ *
+ * When an agent's primary model fails with a retryable error (429, 500, 502, 503),
+ * the next `chat.params` call can select a fallback model from the agent's
+ * `fallbackModels` list.
+ *
+ * Current limitation: The `chat.params` hook can modify temperature/topP/topK/options
+ * but CANNOT change the model itself (model is in the input, not output). Full model
+ * fallback requires one of:
+ *   1. A `chat.error` hook that allows retrying with a different model
+ *   2. A `chat.model` hook that allows overriding the model selection
+ *   3. Adding `model` to the `chat.params` output type
+ *
+ * TODO: When OpenCode adds a suitable hook, implement the retry logic here:
+ *   - On API error (429/5xx), record the failure in `agentErrorState`
+ *   - On next `chat.params` call for the same agent, select next fallback model
+ *   - Log: `[ModelFallback] Switching from ${currentModel} to ${fallbackModel} due to ${error}`
+ *   - Reset fallback state after successful completion or after TTL expires
+ */
+export class ModelFallbackTracker {
+	/**
+	 * Map of agent name → { failedModel, failedAt, errorCode, fallbackIndex }
+	 * Used to track which agents have experienced API errors.
+	 */
+	private agentErrorState = new Map<
+		string,
+		{
+			failedModel: string;
+			failedAt: number;
+			errorCode: number;
+			fallbackIndex: number;
+		}
+	>();
+
+	/** TTL for error state — reset after 5 minutes */
+	private readonly ERROR_STATE_TTL_MS = 5 * 60 * 1000;
+
+	/**
+	 * Record an API error for an agent. Call this from an event handler
+	 * when a retryable API error is detected.
+	 */
+	recordError(agentName: string, model: string, errorCode: number): void {
+		const existing = this.agentErrorState.get(agentName);
+		const fallbackIndex = existing ? existing.fallbackIndex + 1 : 0;
+		this.agentErrorState.set(agentName, {
+			failedModel: model,
+			failedAt: Date.now(),
+			errorCode,
+			fallbackIndex,
+		});
+		console.debug(
+			`[ModelFallback] Recorded error for ${agentName}: model=${model} code=${errorCode} fallbackIndex=${fallbackIndex}`
+		);
+	}
+
+	/**
+	 * Get the next fallback model for an agent, if one is available.
+	 * Returns undefined if no fallback is needed or available.
+	 */
+	getNextFallback(agentName: string, agentConfig: AgentConfig): string | undefined {
+		const state = this.agentErrorState.get(agentName);
+		if (!state) return undefined;
+
+		// Check TTL
+		if (Date.now() - state.failedAt > this.ERROR_STATE_TTL_MS) {
+			this.agentErrorState.delete(agentName);
+			return undefined;
+		}
+
+		const fallbacks = agentConfig.fallbackModels;
+		if (!fallbacks?.length) return undefined;
+
+		if (state.fallbackIndex >= fallbacks.length) {
+			// Exhausted all fallbacks
+			return undefined;
+		}
+
+		return fallbacks[state.fallbackIndex];
+	}
+
+	/**
+	 * Clear error state for an agent (e.g., after successful completion).
+	 */
+	clearError(agentName: string): void {
+		this.agentErrorState.delete(agentName);
+	}
+}

package/src/plugin/hooks/session-memory.ts

@@ -1,23 +1,18 @@
 import type { PluginInput } from '@opencode-ai/plugin';
 import type { CoderConfig } from '../../types';
 import type { BackgroundManager } from '../../background';
-
-/**
- * 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';
-	}
-}
+import type { OpenCodeDBReader } from '../../sqlite';
+import type { CompactionStats } from '../../sqlite/types';
+import {
+	getCurrentBranch,
+	buildCustomCompactionPrompt,
+	fetchAndFormatPlanningState,
+	getImageDescriptions,
+	getRecentToolCallSummaries,
+	storePreCompactionSnapshot,
+	formatCompactionDiagnostics,
+	countListItems,
+} from './compaction-utils';
 
 export interface SessionMemoryHooks {
 	onEvent: (input: {
@@ -38,8 +33,9 @@ export interface SessionMemoryHooks {
  */
 export function createSessionMemoryHooks(
 	ctx: PluginInput,
-	_config: CoderConfig,
-	backgroundManager?: BackgroundManager
+	config: CoderConfig,
+	backgroundManager?: BackgroundManager,
+	dbReader?: OpenCodeDBReader
 ): SessionMemoryHooks {
 	const log = (msg: string) => {
 		ctx.client.app.log({
@@ -55,6 +51,10 @@ export function createSessionMemoryHooks(
 		/**
 		 * Listen for session.compacted event.
 		 * The compaction summary is already in context - just tell Lead to save it.
+		 *
+		 * 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.
 		 */
 		async onEvent(input: {
 			event: { type: string; properties?: Record<string, unknown> };
@@ -144,7 +144,8 @@ Then continue with the current task if there is one.`,
 
 		/**
 		 * Inject Memory system info during compaction.
-		 * This gets included in OpenCode's generated summary.
+		 * Uses output.prompt to REPLACE the default compaction prompt with
+		 * enriched context (planning state, images, tool calls, diagnostics).
 		 */
 		async onCompacting(
 			input: { sessionID: string },
@@ -153,12 +154,43 @@ Then continue with the current task if there is one.`,
 			const sessionId = input.sessionID;
 			log(`Compacting session ${sessionId}`);
 
-			// 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('regular') : 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 session state section
+			const sessionStateSection = `## Session Memory
+
+This session's context is being saved to persistent memory.
+Session record location: \`session:${sessionId}\` in agentuity-opencode-memory
+Current branch: ${branch}
 
-			// Get active background tasks for this session
+After compaction:
+1. Memory will save this summary to the session record
+2. If planning is active, Memory should update planning.progress with this compaction
+3. Memory will apply inline reasoning if significant patterns/corrections emerged`;
+
+			// 4. Build background tasks section
 			const tasks = backgroundManager?.getTasksByParent(sessionId) ?? [];
-			let backgroundTaskContext = '';
+			let backgroundSection: string | null = null;
 
 			if (tasks.length > 0) {
 				const taskList = tasks
@@ -168,38 +200,72 @@ Then continue with the current task if there is one.`,
 					)
 					.join('\n');
 
-				backgroundTaskContext = `
-
-## Active Background Tasks
+				backgroundSection = `## Active Background Tasks
 
 This session has ${tasks.length} background task(s) running in separate sessions:
 ${taskList}
 
 **CRITICAL:** Task IDs and session IDs persist across compaction - these tasks are still running.
-Use \`agentuity_background_output({ task_id: "..." })\` to check their status.
-`;
+Use \`agentuity_background_output({ task_id: "..." })\` to check their status.`;
 			}
 
-			output.context.push(`
-## Session Memory
+			// 5. Combine everything into the full prompt
+			const sections: string[] = [];
+			if (instructions) sections.push(instructions);
+			sections.push(sessionStateSection);
+			if (backgroundSection) sections.push(backgroundSection);
+			if (planningState) sections.push(planningState);
+			if (imageDescs) sections.push(imageDescs);
+			if (toolSummaries) sections.push(toolSummaries);
+
+			// 6. 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);
+
+			// 7. 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');
+			}
 
-This session's context is being saved to persistent memory.
-Session record location: \`session:${sessionId}\` in agentuity-opencode-memory
-Current branch: ${branch}
+			// 8. Set the full prompt or push to context
+			if (useCustomPrompt) {
+				output.prompt = fullPrompt;
+			} else {
+				output.context.push(fullPrompt);
+			}
 
-**Planning State (if active):**
-If this session has planning active (user requested "track progress" or similar), the session record contains:
-- \`planning.prdKey\` - Link to PRD if one exists
-- \`planning.objective\` - What we're trying to accomplish
-- \`planning.phases\` - Current phases with status and notes
-- \`planning.findings\` - Discoveries made during work
-- \`planning.errors\` - Failures to avoid repeating
-${backgroundTaskContext}
-After compaction:
-1. Memory will save this summary to the session record
-2. If planning is active, Memory should update planning.progress with this compaction
-3. Memory will apply inline reasoning if significant patterns/corrections emerged
-`);
+			// 9. 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,
+					})),
+					branch,
+				}).catch(() => {}); // Fire and forget
+			}
 		},
 	};
 }

package/src/plugin/hooks/tools.ts

@@ -165,7 +165,38 @@ export function createToolHooks(ctx: PluginInput, config: CoderConfig): ToolHook
 			}
 		},
 
-		async after(_input: unknown, _output: unknown): Promise<void> {},
+		async after(input: unknown, output: unknown): Promise<void> {
+			// Graceful handling for unavailable tools: if a tool execution produced an
+			// error indicating the tool doesn't exist or is unavailable, normalize the
+			// output to a helpful message so the session continues instead of crashing.
+			const toolName = extractToolName(input);
+			if (!toolName) return;
+
+			const out = output as {
+				output?: string;
+				title?: string;
+				metadata?: Record<string, unknown>;
+			};
+			if (typeof out.output !== 'string') return;
+
+			const lower = out.output.toLowerCase();
+			const isToolMissing =
+				(lower.includes('not found') ||
+					lower.includes('not available') ||
+					lower.includes('does not exist') ||
+					lower.includes('unknown tool') ||
+					lower.includes('no such tool')) &&
+				(lower.includes('tool') || lower.includes(toolName.toLowerCase()));
+
+			if (isToolMissing) {
+				out.output = JSON.stringify({
+					error: `Tool '${toolName}' is not available in this session. It may have been removed or is not installed. Please use an alternative approach or ask the user for guidance.`,
+					tool: toolName,
+					recoverable: true,
+				});
+				out.title = `Tool unavailable: ${toolName}`;
+			}
+		},
 	};
 }
 

package/src/plugin/plugin.ts

@@ -15,6 +15,7 @@ import { createKeywordHooks } from './hooks/keyword';
 import { createParamsHooks } from './hooks/params';
 import { createCadenceHooks } from './hooks/cadence';
 import { createSessionMemoryHooks } from './hooks/session-memory';
+import { createCompletionHooks } from './hooks/completion';
 import type { AgentRole } from '../types';
 import { BackgroundManager } from '../background';
 import type { SessionTreeNode } from '../sqlite';
@@ -92,10 +93,15 @@ export async function createCoderPlugin(ctx: PluginInput): Promise<Hooks> {
 	const resolvedDbPath = resolveOpenCodeDBPath();
 	const dbReader = new OpenCodeDBReader(resolvedDbPath ? { dbPath: resolvedDbPath } : undefined);
 
+	// Shared Map: chat.params stores the user's message text per session,
+	// chat.message reads it for trigger detection (avoids scanning model output).
+	const lastUserMessages = new Map<string, string>();
+
 	const sessionHooks = createSessionHooks(ctx, coderConfig);
 	const toolHooks = createToolHooks(ctx, coderConfig);
 	const keywordHooks = createKeywordHooks(ctx, coderConfig);
 	const paramsHooks = createParamsHooks(ctx, coderConfig);
+	const completionHooks = createCompletionHooks(ctx, coderConfig);
 	const tmuxManager = coderConfig.tmux?.enabled
 		? new TmuxSessionManager(ctx, coderConfig.tmux, {
 				onLog: (message) =>
@@ -157,11 +163,22 @@ export async function createCoderPlugin(ctx: PluginInput): Promise<Hooks> {
 		});
 
 	// Create hooks that need backgroundManager for task reference injection during compaction
-	const cadenceHooks = createCadenceHooks(ctx, coderConfig, backgroundManager, dbReader);
+	const cadenceHooks = createCadenceHooks(
+		ctx,
+		coderConfig,
+		backgroundManager,
+		dbReader,
+		lastUserMessages
+	);
 
 	// Session memory hooks handle checkpointing and compaction for non-Cadence sessions
 	// Orchestration (deciding which module handles which session) happens below in the hooks
-	const sessionMemoryHooks = createSessionMemoryHooks(ctx, coderConfig, backgroundManager);
+	const sessionMemoryHooks = createSessionMemoryHooks(
+		ctx,
+		coderConfig,
+		backgroundManager,
+		dbReader
+	);
 
 	const configHandler = createConfigHandler(coderConfig);
 
@@ -193,11 +210,15 @@ export async function createCoderPlugin(ctx: PluginInput): Promise<Hooks> {
 		...(tools ? { tool: tools } : {}),
 		config: configHandler,
 		'chat.message': async (input: unknown, output: unknown) => {
+			completionHooks.onMessage(input);
 			await keywordHooks.onMessage(input, output);
 			await sessionHooks.onMessage(input, output);
 			await cadenceHooks.onMessage(input, output);
 		},
-		'chat.params': paramsHooks.onParams,
+		'chat.params': async (input: unknown, output: unknown) => {
+			completionHooks.onParams(input);
+			await paramsHooks.onParams(input, output);
+		},
 		'tool.execute.before': toolHooks.before,
 		'tool.execute.after': toolHooks.after,
 		'shell.env': async (_input: unknown, output: unknown) => {
@@ -230,16 +251,28 @@ export async function createCoderPlugin(ctx: PluginInput): Promise<Hooks> {
 			}
 			// Orchestrate: route to appropriate module based on session type
 			const sessionId = extractSessionIdFromEvent(input);
-			if (sessionId && cadenceHooks.isActiveCadenceSession(sessionId)) {
-				await cadenceHooks.onEvent(input);
-			} else if (sessionId) {
-				// Non-Cadence sessions - handle session.compacted for checkpointing
-				await sessionMemoryHooks.onEvent(
-					input as { event: { type: string; properties?: Record<string, unknown> } }
-				);
+			if (sessionId) {
+				// Try lazy restore from KV if not in memory (survives plugin restarts)
+				if (!cadenceHooks.isActiveCadenceSession(sessionId)) {
+					await cadenceHooks.tryRestoreFromKV(sessionId);
+				}
+
+				if (cadenceHooks.isActiveCadenceSession(sessionId)) {
+					await cadenceHooks.onEvent(input);
+				} else {
+					// Non-Cadence sessions - handle session.compacted for checkpointing
+					await sessionMemoryHooks.onEvent(
+						input as { event: { type: string; properties?: Record<string, unknown> } }
+					);
+				}
 			}
 		},
 		'experimental.session.compacting': async (input, output) => {
+			// Try lazy restore from KV if not in memory (survives plugin restarts)
+			if (!cadenceHooks.isActiveCadenceSession(input.sessionID)) {
+				await cadenceHooks.tryRestoreFromKV(input.sessionID);
+			}
+
 			// Orchestrate: route to appropriate module based on session type
 			if (cadenceHooks.isActiveCadenceSession(input.sessionID)) {
 				await cadenceHooks.onCompacting(input, output);
@@ -318,6 +351,16 @@ function createConfigHandler(
 			};
 		}
 
+		// Compaction config: increase reserved token buffer to accommodate our enriched
+		// compaction prompts (planning state, image descriptions, tool summaries, diagnostics).
+		// Default OpenCode reserved buffer is too small for the context we inject.
+		const existingCompaction = (config.compaction ?? {}) as Record<string, unknown>;
+		const existingReserved = existingCompaction.reserved;
+		config.compaction = {
+			...existingCompaction,
+			reserved: typeof existingReserved === 'number' ? existingReserved : 40_000,
+		};
+
 		config.command = {
 			...(config.command as Record<string, CommandDefinition> | undefined),
 			...commands,
@@ -360,6 +403,7 @@ function createAgentConfigs(
 			...(agent.reasoningEffort ? { reasoningEffort: agent.reasoningEffort } : {}),
 			...(agent.thinking ? { thinking: agent.thinking } : {}),
 			...(agent.hidden ? { hidden: agent.hidden } : {}),
+			...(agent.fallbackModels?.length ? { fallbackModels: agent.fallbackModels } : {}),
 		};
 	}
 

package/src/sqlite/index.ts

@@ -1,13 +1,17 @@
 export { OpenCodeDBReader } from './reader';
 export type {
+	CompactionStats,
 	DBMessage,
+	DBNonTextPart,
 	DBPart,
 	DBSession,
 	DBTextPart,
 	DBTodo,
 	DBToolCall,
+	DBToolCallSummary,
 	MessageTokens,
 	OpenCodeDBConfig,
+	PreCompactionSnapshot,
 	SessionCostSummary,
 	SessionStatus,
 	SessionSummary,

package/src/sqlite/queries.ts

@@ -47,4 +47,9 @@ export const QUERIES = {
 	SEARCH_SESSIONS: `SELECT id, project_id, parent_id, slug, directory, title, version, share_url, summary_additions, summary_deletions, summary_files, summary_diffs, time_created, time_updated, time_compacting, time_archived FROM session WHERE title LIKE ? COLLATE NOCASE ORDER BY time_updated DESC`,
 
 	SEARCH_SESSIONS_LIMITED: `SELECT id, project_id, parent_id, slug, directory, title, version, share_url, summary_additions, summary_deletions, summary_files, summary_diffs, time_created, time_updated, time_compacting, time_archived FROM session WHERE title LIKE ? COLLATE NOCASE ORDER BY time_updated DESC LIMIT ?`,
+
+	GET_NON_TEXT_PARTS: `SELECT * FROM part WHERE session_id = ?
+		AND json_valid(data)
+		AND json_extract(data, '$.type') != 'text'
+		ORDER BY time_created DESC LIMIT ?`,
 } as const;