@agentuity/opencode 0.1.40 → 0.1.42

package/src/plugin/plugin.ts

@@ -1,24 +1,58 @@
 import type { PluginInput, Hooks } from '@opencode-ai/plugin';
+import { tool } from '@opencode-ai/plugin';
 import type { AgentConfig, CommandDefinition } from '../types';
+import { loadAllSkills, type LoadedSkill } from '../skills';
 import { agents } from '../agents';
-import { loadCoderConfig, getDefaultConfig, mergeConfig } from '../config';
+import { loadCoderConfig, getDefaultConfig, mergeConfig, validateAndWarnConfigs } from '../config';
 import { createSessionHooks } from './hooks/session';
 import { createToolHooks } from './hooks/tools';
 import { createKeywordHooks } from './hooks/keyword';
 import { createParamsHooks } from './hooks/params';
 import { createCadenceHooks } from './hooks/cadence';
 import { createSessionMemoryHooks } from './hooks/session-memory';
-import { z } from 'zod';
 import type { AgentRole } from '../types';
+import { BackgroundManager } from '../background';
+import { TmuxSessionManager } from '../tmux';
+
+// Sandbox environment detection
+const SANDBOX_ID = process.env.AGENTUITY_SANDBOX_ID;
+const IN_SANDBOX = !!SANDBOX_ID;
+
+// Sandbox context injected into Lead, Builder, and Architect prompts
+const SANDBOX_CONTEXT = IN_SANDBOX
+	? `
+## Sandbox Environment
+
+You are running inside an Agentuity Sandbox (ID: ${SANDBOX_ID}).
+
+**Permissions:** All file operations are allowed without prompts.
+
+**File Locations:**
+- Working directory: \`/home/agentuity\`
+- Temp files: \`/home/agentuity/tmp/\` (preferred over \`/tmp/\`)
+- Artifacts: \`/home/agentuity/.agentuity/\`
+
+**Tips:**
+- No permission prompts - you can read/write freely
+- Sandbox is isolated - safe to experiment
+- Use \`/home/agentuity/\` paths for all file operations
+`
+	: '';
+
+// Agents that should receive sandbox context in their prompts
+const SANDBOX_AWARE_AGENTS: AgentRole[] = ['lead', 'builder', 'architect'];
 
 // Agent display names for @mentions
 const AGENT_MENTIONS: Record<AgentRole, string> = {
 	lead: '@Agentuity Coder Lead',
 	scout: '@Agentuity Coder Scout',
 	builder: '@Agentuity Coder Builder',
+	architect: '@Agentuity Coder Architect',
 	reviewer: '@Agentuity Coder Reviewer',
 	memory: '@Agentuity Coder Memory',
 	expert: '@Agentuity Coder Expert',
+	planner: '@Agentuity Coder Planner',
+	runner: '@Agentuity Coder Runner',
 };
 
 export async function createCoderPlugin(ctx: PluginInput): Promise<Hooks> {
@@ -38,6 +72,30 @@ export async function createCoderPlugin(ctx: PluginInput): Promise<Hooks> {
 	const keywordHooks = createKeywordHooks(ctx, coderConfig);
 	const paramsHooks = createParamsHooks(ctx, coderConfig);
 	const cadenceHooks = createCadenceHooks(ctx, coderConfig);
+	const tmuxManager = coderConfig.tmux?.enabled
+		? new TmuxSessionManager(ctx, coderConfig.tmux, {
+				onLog: (message) =>
+					ctx.client.app.log({
+						body: {
+							service: 'agentuity-coder',
+							level: 'info',
+							message,
+						},
+					}),
+			})
+		: undefined;
+	const backgroundManager = new BackgroundManager(ctx, coderConfig.background, {
+		onSubagentSessionCreated: tmuxManager
+			? (event) => {
+					void tmuxManager.onSessionCreated(event);
+				}
+			: undefined,
+		onSubagentSessionDeleted: tmuxManager
+			? (event) => {
+					void tmuxManager.onSessionDeleted(event);
+				}
+			: undefined,
+	});
 
 	// Session memory hooks handle checkpointing and compaction for non-Cadence sessions
 	// Orchestration (deciding which module handles which session) happens below in the hooks
@@ -45,12 +103,20 @@ export async function createCoderPlugin(ctx: PluginInput): Promise<Hooks> {
 
 	const configHandler = createConfigHandler(coderConfig);
 
-	// Get the tool helper from Open Code context if available
-	const toolHelper = (ctx as { tool?: unknown }).tool as
-		| ((schema: (s: typeof z) => unknown) => unknown)
-		| undefined;
+	// Create plugin tools using the @opencode-ai/plugin tool helper
+	const tools = createTools(backgroundManager);
+
+	// Create a logger for shutdown handler
+	const shutdownLogger = (message: string) =>
+		ctx.client.app.log({
+			body: {
+				service: 'agentuity-coder',
+				level: 'info',
+				message: `[shutdown] ${message}`,
+			},
+		});
 
-	const tools = toolHelper ? createTools(toolHelper) : undefined;
+	registerShutdownHandler(backgroundManager, tmuxManager, shutdownLogger);
 
 	// Show startup toast (fire and forget, don't block)
 	try {
@@ -73,6 +139,10 @@ export async function createCoderPlugin(ctx: PluginInput): Promise<Hooks> {
 		'tool.execute.before': toolHooks.before,
 		'tool.execute.after': toolHooks.after,
 		event: async (input) => {
+			const event = extractEventFromInput(input);
+			if (event) {
+				backgroundManager.handleEvent(event);
+			}
 			// Orchestrate: route to appropriate module based on session type
 			const sessionId = extractSessionIdFromEvent(input);
 			if (sessionId && cadenceHooks.isActiveCadenceSession(sessionId)) {
@@ -101,27 +171,60 @@ function createConfigHandler(
 	return async (config: Record<string, unknown>) => {
 		const agentConfigs = createAgentConfigs(coderConfig);
 		const commands = createCommands();
+		const loadedSkills = await loadAllSkills(coderConfig.skills);
+		const skillCommands = createSkillCommands(loadedSkills);
+
+		// Merge agent configs: our defaults first, then user's opencode.json overrides on top
+		// This allows users to customize any agent via their opencode.json
+		const userAgentConfigs = config.agent as Record<string, AgentConfig> | undefined;
+		const mergedAgents: Record<string, AgentConfig> = { ...agentConfigs };
+
+		// Shallow merge user overrides on top of our defaults (nested objects like tools are replaced, not merged)
+		if (userAgentConfigs) {
+			for (const [name, userConfig] of Object.entries(userAgentConfigs)) {
+				if (mergedAgents[name]) {
+					// Merge user config on top of our default
+					mergedAgents[name] = {
+						...mergedAgents[name],
+						...userConfig,
+					};
+				} else {
+					// User defined a new agent not in our defaults
+					mergedAgents[name] = userConfig;
+				}
+			}
+		}
 
-		config.agent = {
-			...(config.agent as Record<string, AgentConfig> | undefined),
-			...agentConfigs,
-		};
+		config.agent = mergedAgents;
+
+		// Validate merged configs and warn about mismatches
+		validateAndWarnConfigs(mergedAgents);
+
+		// In sandbox, allow all permissions without prompts
+		if (IN_SANDBOX) {
+			config.permission = {
+				'*': 'allow',
+				external_directory: {
+					'/home/agentuity/**': 'allow',
+					'*': 'allow',
+				},
+			};
+		}
 
 		config.command = {
 			...(config.command as Record<string, CommandDefinition> | undefined),
 			...commands,
+			...skillCommands,
 		};
 	};
 }
 
 function createAgentConfigs(
-	config: ReturnType<typeof getDefaultConfig>
+	_config: ReturnType<typeof getDefaultConfig>
 ): Record<string, AgentConfig> {
 	const result: Record<string, AgentConfig> = {};
 
 	for (const agent of Object.values(agents)) {
-		const modelConfig = config.agents?.[agent.role];
-
 		// Convert tools.exclude to Open Code format (tool: false)
 		const tools: Record<string, boolean> = {};
 		if (agent.tools?.exclude) {
@@ -130,16 +233,25 @@ function createAgentConfigs(
 			}
 		}
 
+		// Inject sandbox context into specific agents when running in sandbox
+		const shouldInjectSandbox =
+			IN_SANDBOX && SANDBOX_AWARE_AGENTS.includes(agent.role as AgentRole);
+		const prompt = shouldInjectSandbox
+			? `${agent.systemPrompt}\n${SANDBOX_CONTEXT}`
+			: agent.systemPrompt;
+
+		// Use agent defaults directly - user overrides happen in createConfigHandler
 		result[agent.displayName] = {
 			description: agent.description,
-			model: modelConfig?.model ?? agent.defaultModel,
-			prompt: agent.systemPrompt,
+			model: agent.defaultModel,
+			prompt,
 			mode: agent.mode ?? 'subagent',
 			...(Object.keys(tools).length > 0 ? { tools } : {}),
-			// Pass through thinking/reasoning settings
 			...(agent.variant ? { variant: agent.variant } : {}),
 			...(agent.temperature !== undefined ? { temperature: agent.temperature } : {}),
 			...(agent.maxSteps !== undefined ? { maxSteps: agent.maxSteps } : {}),
+			...(agent.reasoningEffort ? { reasoningEffort: agent.reasoningEffort } : {}),
+			...(agent.thinking ? { thinking: agent.thinking } : {}),
 		};
 	}
 
@@ -158,20 +270,24 @@ You are the Agentuity Coder Lead agent orchestrating the Agentuity Coder team.
 ## Your Team (use @mentions to invoke)
 - **@Agentuity Coder Scout**: Explore codebase, find patterns, research docs (read-only)
 - **@Agentuity Coder Builder**: Implement features, write code, run tests
+- **@Agentuity Coder Architect**: Complex autonomous tasks, Cadence mode (GPT Codex)
 - **@Agentuity Coder Reviewer**: Review changes, catch issues, apply fixes
 - **@Agentuity Coder Memory**: Store context, remember decisions
 - **@Agentuity Coder Expert**: Agentuity CLI and cloud services specialist
+- **@Agentuity Coder Planner**: Deep planning for complex architecture decisions
+- **@Agentuity Coder Runner**: Run lint/build/test commands, returns structured results
 
 ## Task
 $ARGUMENTS
 
 ## Guidelines
 1. Use @Agentuity Coder Scout first to understand context
-2. Delegate implementation to @Agentuity Coder Builder
-3. Have @Agentuity Coder Reviewer check the work
-4. Use @Agentuity Coder Expert for Agentuity CLI questions
-5. Only use cloud services when genuinely helpful
-6. **When done, tell @Agentuity Coder Memory to memorialize the session**
+2. Delegate implementation to @Agentuity Coder Builder (or Architect for complex work)
+3. Delegate lint/build/test commands to @Agentuity Coder Runner for structured results
+4. Have @Agentuity Coder Reviewer check the work
+5. Use @Agentuity Coder Expert for Agentuity CLI questions
+6. Only use cloud services when genuinely helpful
+7. **When done, tell @Agentuity Coder Memory to memorialize the session**
 </coder-mode>`,
 			agent: 'Agentuity Coder Lead',
 			argumentHint: '"task description"',
@@ -289,10 +405,13 @@ You are the Agentuity Coder Lead in **Cadence mode** — a long-running autonomo
 
 ## Your Team (use @mentions to invoke)
 - **@Agentuity Coder Scout**: Explore codebase, find patterns, research docs (read-only)
-- **@Agentuity Coder Builder**: Implement features, write code, run tests
+- **@Agentuity Coder Architect**: Complex autonomous implementation (GPT Codex with high reasoning) — **USE THIS FOR CADENCE**
+- **@Agentuity Coder Builder**: Quick fixes, simple changes (for minor iterations only)
 - **@Agentuity Coder Reviewer**: Review changes, catch issues, apply fixes
 - **@Agentuity Coder Memory**: Store context, remember decisions, checkpoints
 - **@Agentuity Coder Expert**: Agentuity CLI and cloud services specialist
+- **@Agentuity Coder Planner**: Deep planning for complex architecture decisions
+- **@Agentuity Coder Runner**: Run lint/build/test commands, returns structured results
 
 ## Task
 $ARGUMENTS
@@ -306,7 +425,8 @@ $ARGUMENTS
 2. **Each iteration**:
    - Ask @Agentuity Coder Memory for relevant context
    - Use @Agentuity Coder Scout to understand what's needed
-   - Delegate implementation to @Agentuity Coder Builder
+   - For complex planning, consult @Agentuity Coder Planner
+   - Delegate implementation to **@Agentuity Coder Architect** (preferred for Cadence)
    - Have @Agentuity Coder Reviewer verify the work
    - Tell @Agentuity Coder Memory to store checkpoint
 
@@ -318,10 +438,11 @@ $ARGUMENTS
 4. **Tell @Agentuity Coder Memory to memorialize** the completed session
 
 ## Guidelines
-- **Always delegate** — use Scout for research, Builder for code, Reviewer for verification
+- **Use Architect for implementation** — Architect has GPT Codex with maximum reasoning, ideal for autonomous work
+- Use regular Builder only for trivial fixes within an iteration
 - Ask Memory for context at each iteration start
 - Store checkpoints at each iteration end
-- If stuck, ask Scout to re-evaluate before pausing
+- If stuck on architecture, consult Planner before trying more approaches
 - Use @Agentuity Coder Expert for sandbox/cloud operations
 - Respect max iterations (50 default)`,
 			agent: 'Agentuity Coder Lead',
@@ -330,40 +451,178 @@ $ARGUMENTS
 	};
 }
 
-function createTools(tool: (schema: (s: typeof z) => unknown) => unknown): Hooks['tool'] {
-	const coderDelegate = tool((s) => ({
+function createSkillCommands(skills: LoadedSkill[]): Record<string, CommandDefinition> {
+	const commands: Record<string, CommandDefinition> = {};
+
+	for (const skill of skills) {
+		const baseDir = normalizeBaseDir(skill.resolvedPath);
+		commands[skill.name] = {
+			name: skill.name,
+			description: skill.metadata.description,
+			template: `<skill-instruction>
+Base directory for this skill: ${baseDir}/
+File references (@path) in this skill are relative to this directory.
+
+${skill.content}
+</skill-instruction>
+
+<user-request>
+$ARGUMENTS
+</user-request>`,
+			...(skill.metadata.agent ? { agent: skill.metadata.agent } : {}),
+			...(skill.metadata.model ? { model: skill.metadata.model } : {}),
+			...(skill.metadata['argument-hint']
+				? { argumentHint: skill.metadata['argument-hint'] }
+				: {}),
+			...(skill.metadata.subtask ? { subtask: true } : {}),
+		};
+	}
+
+	return commands;
+}
+
+function normalizeBaseDir(path: string): string {
+	return path.replace(/[\\/]+$/, '');
+}
+
+function createTools(backgroundManager: BackgroundManager): Hooks['tool'] {
+	// Use the schema from @opencode-ai/plugin's tool helper to avoid Zod version mismatches
+	const s = tool.schema;
+
+	const coderDelegate = tool({
 		description: `Delegate a task to a specialized Agentuity Coder agent.
 
 Use this to:
 - Scout: Explore codebase, find patterns, research documentation
-- Builder: Implement features, write code, run tests
+- Builder: Implement features, write code, run tests (interactive work)
+- Architect: Complex autonomous tasks, Cadence mode, deep reasoning (GPT Codex)
 - Reviewer: Review changes, catch issues, apply fixes
 - Memory: Store context, remember decisions across sessions
-- Expert: Get help with Agentuity CLI and cloud services`,
-		args: s.object({
+- Expert: Get help with Agentuity CLI and cloud services
+- Planner: Strategic advisor for complex architecture and deep planning (read-only)`,
+		args: {
 			agent: s
-				.enum(['scout', 'builder', 'reviewer', 'memory', 'expert'])
+				.enum([
+					'scout',
+					'builder',
+					'architect',
+					'reviewer',
+					'memory',
+					'expert',
+					'planner',
+					'runner',
+				])
 				.describe('Which agent to delegate to'),
 			task: s.string().describe('Clear description of the task'),
 			context: s.string().optional().describe('Additional context from previous tasks'),
-		}),
-		execute: async (args: { agent: AgentRole; task: string; context?: string }) => {
-			const mention = AGENT_MENTIONS[args.agent];
+		},
+		async execute(args) {
+			const mention = AGENT_MENTIONS[args.agent as AgentRole];
 			let prompt = `${mention}\n\n## Task\n${args.task}`;
 			if (args.context) {
 				prompt = `${mention}\n\n## Context\n${args.context}\n\n## Task\n${args.task}`;
 			}
-			return {
-				output: `To delegate this task, use the Task tool with this prompt:\n\n${prompt}\n\nThe ${args.agent} agent will handle this task.`,
-			};
+			return `To delegate this task, use the Task tool with this prompt:\n\n${prompt}\n\nThe ${args.agent} agent will handle this task.`;
+		},
+	});
+
+	const backgroundTask = tool({
+		description: `Launch a task to run in the background. Use this for parallel execution of multiple independent tasks.
+
+IMPORTANT: Use this tool instead of the 'task' tool when:
+- You need to run multiple agents in parallel
+- Tasks are independent and don't need sequential execution
+- The user asks for "parallel", "background", or "concurrent" work`,
+		args: {
+			agent: s
+				.enum([
+					'lead',
+					'scout',
+					'builder',
+					'architect',
+					'reviewer',
+					'memory',
+					'expert',
+					'planner',
+					'runner',
+				])
+				.describe('Agent role to run the task'),
+			task: s.string().describe('Task prompt to run in the background'),
+			description: s.string().optional().describe('Short description of the task'),
+		},
+		async execute(args, context) {
+			const parentSessionId = context.sessionID;
+			if (!parentSessionId) {
+				return JSON.stringify({
+					taskId: 'unknown',
+					status: 'error',
+					message: 'Missing session context for background task.',
+				});
+			}
+
+			const agentName = resolveAgentName(args.agent as AgentRole);
+			const bgTask = await backgroundManager.launch({
+				description: args.description ?? args.task,
+				prompt: args.task,
+				agent: agentName,
+				parentSessionId,
+				parentMessageId: context.messageID,
+			});
+			return JSON.stringify({
+				taskId: bgTask.id,
+				status: bgTask.status,
+				message:
+					bgTask.status === 'error'
+						? (bgTask.error ?? 'Failed to launch background task.')
+						: 'Background task launched.',
+			});
+		},
+	});
+
+	const backgroundOutput = tool({
+		description: 'Retrieve output for a background task.',
+		args: {
+			task_id: s.string().describe('Background task ID'),
 		},
-	}));
+		async execute(args) {
+			const bgTask = backgroundManager.getTask(args.task_id);
+			if (!bgTask) {
+				return JSON.stringify({
+					taskId: args.task_id,
+					status: 'error',
+					error: 'Task not found.',
+				});
+			}
+			return JSON.stringify({
+				taskId: bgTask.id,
+				status: bgTask.status,
+				result: bgTask.result,
+				error: bgTask.error,
+			});
+		},
+	});
+
+	const backgroundCancel = tool({
+		description: 'Cancel a running background task.',
+		args: {
+			task_id: s.string().describe('Background task ID'),
+		},
+		async execute(args) {
+			const success = backgroundManager.cancel(args.task_id);
+			return JSON.stringify({
+				taskId: args.task_id,
+				success,
+				message: success ? 'Background task cancelled.' : 'Unable to cancel task.',
+			});
+		},
+	});
 
-	// Type assertion needed because the tool() helper returns unknown
-	// but the runtime type is correct (it's created by OpenCode's tool helper)
 	return {
 		coder_delegate: coderDelegate,
-	} as Hooks['tool'];
+		background_task: backgroundTask,
+		background_output: backgroundOutput,
+		background_cancel: backgroundCancel,
+	};
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -381,3 +640,76 @@ function extractSessionIdFromEvent(input: unknown): string | undefined {
 		(inp.event.properties.sessionID as string | undefined)
 	);
 }
+
+function resolveAgentName(role: AgentRole): string {
+	const agent = agents[role];
+	return agent?.displayName ?? role;
+}
+
+function extractEventFromInput(
+	input: unknown
+): { type: string; properties?: Record<string, unknown> } | undefined {
+	if (typeof input !== 'object' || input === null) return undefined;
+	const inp = input as { event?: { type?: string; properties?: Record<string, unknown> } };
+	if (!inp.event || typeof inp.event.type !== 'string') return undefined;
+	return { type: inp.event.type, properties: inp.event.properties };
+}
+
+function registerShutdownHandler(
+	manager: BackgroundManager,
+	tmuxManager?: TmuxSessionManager,
+	logger?: (msg: string) => void
+): void {
+	if (typeof process === 'undefined') {
+		logger?.('[shutdown] process is undefined, cannot register handlers');
+		return;
+	}
+
+	const log = logger ?? (() => {});
+	let shutdownCalled = false;
+
+	log(
+		`Registering shutdown handlers (PID: ${process.pid}, tmuxManager: ${tmuxManager ? 'yes' : 'no'})`
+	);
+	log(`Current tracked sessions in tmuxManager: ${tmuxManager ? 'checking...' : 'N/A'}`);
+
+	const shutdown = (signal?: string) => {
+		// Prevent multiple shutdown calls
+		if (shutdownCalled) {
+			log(`Shutdown already in progress, ignoring ${signal ?? 'unknown'} signal`);
+			return;
+		}
+		shutdownCalled = true;
+
+		log(`Shutdown triggered by ${signal ?? 'unknown'} signal`);
+
+		try {
+			log('Shutting down background manager...');
+			manager.shutdown();
+			log('Background manager shutdown complete');
+		} catch (error) {
+			log(`Background manager shutdown error: ${error}`);
+		}
+
+		if (tmuxManager) {
+			try {
+				log('Cleaning up tmux sessions...');
+				// Use sync version to ensure cleanup completes before process exits
+				tmuxManager.cleanupSync();
+				log('Tmux cleanup complete');
+			} catch (error) {
+				log(`Tmux cleanup error: ${error}`);
+			}
+		}
+
+		log('Shutdown complete');
+	};
+
+	process.once('beforeExit', () => shutdown('beforeExit'));
+	process.once('SIGINT', () => shutdown('SIGINT'));
+	process.once('SIGTERM', () => shutdown('SIGTERM'));
+	process.once('SIGHUP', () => shutdown('SIGHUP')); // Handle tmux pane close
+	process.once('exit', () => shutdown('exit')); // Also handle exit event for extra safety
+
+	log('Shutdown handlers registered for: beforeExit, SIGINT, SIGTERM, SIGHUP, exit');
+}

package/src/skills/frontmatter.ts

@@ -0,0 +1,25 @@
+import yaml from 'yaml';
+
+interface ParsedFrontmatter<T = Record<string, unknown>> {
+	data: T;
+	body: string;
+}
+
+export function parseFrontmatter<T = Record<string, unknown>>(
+	content: string
+): ParsedFrontmatter<T> {
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!match) {
+		return { data: {} as T, body: content.trim() };
+	}
+
+	const frontmatter = match[1] ?? '';
+	const body = content.slice(match[0].length).trim();
+
+	try {
+		const data = yaml.parse(frontmatter) as T;
+		return { data: (data ?? {}) as T, body };
+	} catch {
+		return { data: {} as T, body: content.trim() };
+	}
+}

package/src/skills/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './frontmatter';
+export * from './loader';