@agentuity/opencode 1.0.16 → 1.0.17

package/src/config/loader.ts

@@ -146,7 +146,7 @@ const DEFAULT_BLOCKED_COMMANDS = [
 
 const DEFAULT_BACKGROUND_CONFIG: BackgroundTaskConfig = {
 	enabled: true,
-	defaultConcurrency: 1,
+	defaultConcurrency: 5,
 	staleTimeoutMs: 30 * 60 * 1000,
 	providerConcurrency: {},
 	modelConcurrency: {},
@@ -199,7 +199,7 @@ function mergeBackgroundConfig(
 	if (!base && !override) return undefined;
 	return {
 		enabled: override?.enabled ?? base?.enabled ?? true,
-		defaultConcurrency: override?.defaultConcurrency ?? base?.defaultConcurrency ?? 1,
+		defaultConcurrency: override?.defaultConcurrency ?? base?.defaultConcurrency ?? 5,
 		staleTimeoutMs: override?.staleTimeoutMs ?? base?.staleTimeoutMs ?? 30 * 60 * 1000,
 		providerConcurrency: {
 			...(base?.providerConcurrency ?? {}),

package/src/plugin/hooks/cadence.ts

@@ -197,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;
@@ -379,14 +382,7 @@ ${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.`;
 			}
 
 			// 5. Build SQLite dashboard section

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>;
@@ -199,3 +199,99 @@ export function createParamsHooks(
  *
  * 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

@@ -51,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> };

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';
@@ -99,7 +100,8 @@ export async function createCoderPlugin(ctx: PluginInput): Promise<Hooks> {
 	const sessionHooks = createSessionHooks(ctx, coderConfig);
 	const toolHooks = createToolHooks(ctx, coderConfig);
 	const keywordHooks = createKeywordHooks(ctx, coderConfig);
-	const paramsHooks = createParamsHooks(ctx, coderConfig, lastUserMessages);
+	const paramsHooks = createParamsHooks(ctx, coderConfig);
+	const completionHooks = createCompletionHooks(ctx, coderConfig);
 	const tmuxManager = coderConfig.tmux?.enabled
 		? new TmuxSessionManager(ctx, coderConfig.tmux, {
 				onLog: (message) =>
@@ -208,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) => {
@@ -397,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/tools/background.ts

@@ -105,6 +105,12 @@ export function createBackgroundTools(manager: BackgroundManager): {
 			status: string;
 			result?: string;
 			error?: string;
+			progress?: {
+				toolCalls: number;
+				lastTool?: string;
+				lastToolSec: number;
+				activeTools: number;
+			};
 		}> {
 			const task = manager.getTask(args.task_id);
 			if (!task) {
@@ -114,12 +120,34 @@ export function createBackgroundTools(manager: BackgroundManager): {
 					error: 'Task not found.',
 				};
 			}
+
+			// Include compact progress snapshot only for active tasks.
+			// Three numbers + optional tool name — minimal context cost.
+			// lastToolSec: seconds since the last tool call event was received.
+			//   0 = active right now; >300 with activeTools=0 = genuinely stuck.
+			let progress:
+				| { toolCalls: number; lastTool?: string; lastToolSec: number; activeTools: number }
+				| undefined;
+
+			if ((task.status === 'running' || task.status === 'pending') && task.progress) {
+				const lastToolSec = Math.floor(
+					(Date.now() - task.progress.lastUpdate.getTime()) / 1000
+				);
+				progress = {
+					toolCalls: task.progress.toolCalls,
+					lastTool: task.progress.lastTool,
+					lastToolSec,
+					activeTools: task.progress.activeToolCallsInFlight,
+				};
+			}
+
 			return {
 				taskId: task.id,
 				sessionId: task.sessionId,
 				status: task.status,
 				result: task.result,
 				error: task.error,
+				progress,
 			};
 		},
 	};

package/src/types.ts

@@ -89,6 +89,16 @@ export interface AgentConfig {
 	reasoningEffort?: ReasoningEffort;
 	/** Extended thinking configuration for Anthropic models */
 	thinking?: ThinkingConfig;
+	/**
+	 * Ordered list of fallback model IDs to try when the primary model fails
+	 * with a retryable error (429 rate limit, 500/502/503 server error).
+	 * Models are tried in order until one succeeds.
+	 *
+	 * Example: ['anthropic/claude-sonnet-4-20250514', 'openai/gpt-4.1']
+	 */
+	fallbackModels?: string[];
+	/** Hidden from @ autocomplete */
+	hidden?: boolean;
 }
 
 export interface AgentContext {