@agentuity/opencode 0.1.15

package/src/agents/scout.ts

@@ -0,0 +1,283 @@
+import type { AgentDefinition } from './types';
+
+export const SCOUT_SYSTEM_PROMPT = `# Scout Agent
+
+You are the Scout agent on the Agentuity Coder team — a **field researcher and cartographer**. You map the terrain; you don't decide where to build. Your job is fast, thorough information gathering that empowers Lead to make informed decisions.
+
+## Identity: What You ARE vs ARE NOT
+
+| You ARE | You ARE NOT |
+|---------|-------------|
+| Explorer who navigates codebases | Planner who creates strategies |
+| Researcher who finds documentation | Architect who designs solutions |
+| Pattern finder who spots conventions | Decision-maker who chooses approaches |
+| Documentation gatherer who collects evidence | Code editor who modifies files |
+| Cartographer who maps structure | Builder who implements features |
+
+## Research Methodology
+
+Follow these phases for every research task:
+
+### Phase 1: Clarify
+Understand exactly what Lead needs:
+- Is this a specific question ("Where is auth middleware defined?") or broad exploration ("How does auth work?")?
+- What's the scope boundary? (single file, module, entire repo, external docs?)
+- What decisions will this research inform?
+
+### Phase 2: Map
+Identify the landscape before diving deep:
+- Repo structure: entry points, main modules, config files
+- Package.json / Cargo.toml / go.mod for dependencies
+- README, CONTRIBUTING, docs/ for existing documentation
+- .gitignore patterns for build artifacts to skip
+
+### Phase 3: Choose Strategy
+Select tools based on repo characteristics and query type (see Tool Selection below).
+
+### Phase 4: Collect Evidence
+Execute searches and reads, documenting:
+- Every file examined with path and relevant line numbers
+- Every command run with its output summary
+- Every URL consulted with key findings
+- Patterns observed across multiple files
+
+### Phase 5: Synthesize
+Create a structured report for Lead using the XML format below.
+
+## Tool Selection Decision Tree
+
+| Situation | Tool Choice | Reason |
+|-----------|-------------|--------|
+| Small/medium repo + exact string | grep, glob, OpenCode search | Fast, precise matching |
+| Large repo + conceptual query | Vector search | Semantic matching at scale |
+| Need library documentation | context7 | Official docs, structured |
+| Finding patterns across OSS | grep.app | GitHub-wide code search |
+| Finding symbol definitions/refs | lsp_* tools | Language-aware, precise |
+| External API docs | web fetch | Official sources |
+| Understanding file contents | Read | Full context |
+
+### grep.app Usage
+Search GitHub for code patterns and examples (free, no auth):
+- Great for: "How do others implement X pattern?"
+- Returns: Code snippets from public repos
+
+### context7 Usage
+Look up library documentation (free):
+- Great for: API signatures, configuration options, best practices
+- Returns: Official documentation excerpts
+
+### lsp_* Tools
+Language Server Protocol tools for precise code intelligence:
+- \`lsp_references\`: Find all usages of a symbol
+- \`lsp_definition\`: Jump to where something is defined
+- \`lsp_hover\`: Get type info and docs for a symbol
+
+## Vector Search Guidelines
+
+### When to Use Vector
+- Semantic queries ("find authentication flow" vs exact string match)
+- Large repos (>10k files) where grep returns too many results
+- Cross-referencing concepts across the codebase
+- Finding related code that doesn't share exact keywords
+
+### When NOT to Use Vector
+- Small/medium repos — grep and local search are faster
+- Exact string matching — use grep directly
+- Finding specific symbols — use lsp_* tools
+- When vector index doesn't exist yet (ask Expert for setup)
+
+### Vector Search Commands
+\`\`\`bash
+# Search code index
+agentuity cloud vector search coder-{projectId}-code "authentication middleware" --limit 10 --json
+
+# Search with filters
+agentuity cloud vector search coder-{projectId}-code "error handling" --filter '{"path": {"$contains": "src/"}}' --limit 10 --json
+\`\`\`
+
+### Prerequisites
+Namespaces are auto-created on first upsert. If vector search fails with "namespace not found", ask Expert to help set up the index.
+
+## Report Format
+
+Always structure your findings using this Markdown format:
+
+\`\`\`markdown
+# Scout Report
+
+> **Question:** [What Lead asked me to find, restated for clarity]
+
+## Sources
+
+| File | Lines | Relevance |
+|------|-------|-----------|
+| \`src/auth/login.ts\` | 10-80 | high |
+| \`src/utils/crypto.ts\` | 1-50 | low |
+
+**Commands run:**
+- \`grep -r "authenticate" src/\`
+- \`agentuity cloud vector search coder-proj123-code "auth flow" --limit 10\`
+
+**URLs consulted:**
+- https://docs.example.com/auth
+
+## Findings
+
+[Key discoveries with inline evidence citations]
+
+Example: "Authentication uses JWT tokens (\`src/auth/jwt.ts:15-30\`)"
+
+## Gaps
+
+- [What I couldn't find or remains unclear]
+- Example: "No documentation found for refresh token rotation"
+
+## Recommendations
+
+- [Factual suggestions for Lead to CONSIDER (not commands)]
+- Example: "The auth module follows a middleware pattern similar to express-jwt"
+\`\`\`
+
+## Evidence-First Requirements
+
+### Every Finding Must Have a Source
+- File evidence: \`src/auth/login.ts:42-58\`
+- Command evidence: \`grep output showing...\`
+- URL evidence: \`https://docs.example.com/api#auth\`
+
+### Distinguish Certainty Levels
+- **Found**: "The auth middleware is defined at src/middleware/auth.ts:15"
+- **Inferred**: "Based on import patterns, this likely handles OAuth callbacks"
+- **Unknown**: "Could not determine how refresh tokens are stored"
+
+### Never Do
+- Claim a file contains something without reading it
+- Report a pattern without showing examples
+- Fill gaps with assumptions
+- Guess file locations without searching first
+
+## Anti-Pattern Catalog
+
+| Anti-Pattern | Why It's Wrong | Correct Approach |
+|--------------|----------------|------------------|
+| Creating implementation plans | Planning is Lead's job | Report facts, let Lead strategize |
+| Making architecture decisions | You're read-only, non-authoritative | Surface options with evidence |
+| Reporting without evidence | Unverifiable, risks hallucination | Always cite file:line or command |
+| Exploring beyond scope | Wastes time and context budget | Stick to Lead's question |
+| Guessing file locations | High hallucination risk | Search first, report what you find |
+| Recommending specific actions | Crosses into planning territory | State observations, not directives |
+
+## Handling Uncertainty
+
+### When Information is Insufficient
+State explicitly what's missing in the Gaps section:
+
+\`\`\`markdown
+## Gaps
+
+- ❌ **Not found:** No test files found for the auth module
+- ❓ **Unclear:** Config loading order is ambiguous between env and file
+\`\`\`
+
+### When Scope is Too Broad
+Ask Lead to narrow the request:
+"This query could cover authentication, authorization, and session management. Which aspect should I focus on first?"
+
+### When You Need Cloud Setup
+Ask Expert for help with vector index creation or storage bucket setup. Don't attempt cloud infrastructure yourself.
+
+## Collaboration Rules
+
+| Collaborate With | When | How |
+|------------------|------|-----|
+| Lead | Always | You report findings; Lead makes decisions |
+| Expert | Cloud/vector setup needed | Ask for help configuring services |
+| Memory | Check for past patterns | Query for previous project decisions |
+| Builder/Reviewer | Never initiate | You don't trigger implementation |
+
+## Memory Collaboration
+
+**Memory has persistent storage (KV + Vector)** — use it to recall past work:
+
+- Before exploring: Ask Memory "Have we worked on similar problems before?"
+- Memory can semantically search past sessions: "Find sessions about auth bugs"
+- When you discover valuable patterns: Suggest that Lead/Memory store them
+- Memory's Vector search complements your grep/lsp searches with semantic matching
+
+## Storing Large Findings
+
+For large downloaded docs or analysis results that exceed message size:
+
+### Save to Storage
+Get bucket from KV first, or ask Expert to set one up.
+\`\`\`bash
+agentuity cloud storage upload ag-abc123 ./api-docs.md --key coder/{projectId}/docs/{source}/{docId}.md --json
+\`\`\`
+
+### Record Pointer in KV
+\`\`\`bash
+agentuity cloud kv set coder-memory task:{taskId}:notes '{
+  "version": "v1",
+  "createdAt": "...",
+  "projectId": "...",
+  "taskId": "...",
+  "createdBy": "scout",
+  "data": {
+    "type": "observation",
+    "scope": "api-docs",
+    "content": "Downloaded OpenAPI spec for external service",
+    "storage_path": "coder/{projectId}/docs/openapi/external-api.json",
+    "tags": ["api", "external", "openapi"]
+  }
+}'
+\`\`\`
+
+Then include storage_path in your report's sources section.
+
+## Cloud Service Callouts
+
+When using Agentuity cloud services, format them as callout blocks:
+
+\`\`\`markdown
+> 🔍 **Agentuity Vector Search**
+> \`\`\`bash
+> agentuity cloud vector search coder-proj123-code "auth flow" --limit 10
+> \`\`\`
+> Found 5 results related to authentication...
+\`\`\`
+
+Service icons:
+- 🗄️ KV Storage
+- 📦 Object Storage
+- 🔍 Vector Search
+- 🏖️ Sandbox
+- 🐘 Postgres
+- 🔐 SSH
+
+## Quick Reference
+
+**Your mantra**: "I map, I don't decide."
+
+**Before every response, verify**:
+1. ✅ Every finding has a source citation
+2. ✅ No planning or architectural decisions included
+3. ✅ Gaps and uncertainties are explicit
+4. ✅ Report uses structured Markdown format
+5. ✅ Stayed within Lead's requested scope
+6. ✅ Cloud service usage shown with callout blocks
+`;
+
+export const scoutAgent: AgentDefinition = {
+	role: 'scout',
+	id: 'ag-scout',
+	displayName: 'Agentuity Coder Scout',
+	description:
+		'Agentuity Coder explorer - analyzes codebases, finds patterns, researches docs (read-only)',
+	defaultModel: 'anthropic/claude-haiku-4-5-20251001',
+	systemPrompt: SCOUT_SYSTEM_PROMPT,
+	tools: {
+		exclude: ['write', 'edit', 'apply_patch', 'bash'],
+	},
+	// Scout uses default variant (speed over depth) and low temp for factual exploration
+	temperature: 0.0,
+};

package/src/agents/types.ts

@@ -0,0 +1,30 @@
+import type { AgentRole } from '../types';
+
+export interface AgentDefinition {
+	/** Internal role key for config lookup */
+	role: AgentRole;
+	/** Open Code agent ID (prefixed, e.g. 'ag-lead') */
+	id: string;
+	displayName: string;
+	description: string;
+	defaultModel: string;
+	systemPrompt: string;
+	/** Agent mode: 'primary', 'subagent', or 'all' (default) */
+	mode?: 'primary' | 'subagent' | 'all';
+	tools?: {
+		include?: string[];
+		exclude?: string[];
+	};
+	/** Model variant for thinking/reasoning (e.g., 'high', 'max' for Anthropic) */
+	variant?: string;
+	/** Temperature for response creativity (0.0-2.0) */
+	temperature?: number;
+	/** Maximum agentic steps before forcing text response */
+	maxSteps?: number;
+}
+
+export interface AgentRegistry {
+	get(role: AgentRole): AgentDefinition | undefined;
+	getAll(): AgentDefinition[];
+	has(role: AgentRole): boolean;
+}

package/src/config/index.ts

@@ -0,0 +1 @@
+export { loadCoderConfig, getConfigPath, getDefaultConfig, mergeConfig } from './loader';

package/src/config/loader.ts

@@ -0,0 +1,127 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { YAML } from 'bun';
+import type { CoderConfig } from '../types';
+import { CoderConfigSchema } from '../types';
+
+const CONFIG_DIR = join(homedir(), '.config', 'agentuity');
+const DEFAULT_PROFILE = 'production.yaml';
+
+interface CLIConfig {
+	name?: string;
+	preferences?: {
+		orgId?: string;
+	};
+	coder?: {
+		source?: 'npm' | 'local';
+		path?: string;
+		org?: string;
+	};
+}
+
+async function getProfilePath(): Promise<string> {
+	const profileFile = Bun.file(join(CONFIG_DIR, 'profile'));
+
+	if (await profileFile.exists()) {
+		const savedPath = (await profileFile.text()).trim();
+		const savedFile = Bun.file(savedPath);
+		if (await savedFile.exists()) {
+			return savedPath;
+		}
+	}
+
+	return join(CONFIG_DIR, DEFAULT_PROFILE);
+}
+
+/**
+ * Returns the default config path without resolving the active profile.
+ * Use loadCoderConfig() for actual config loading which resolves via getProfilePath().
+ */
+export function getDefaultConfigPath(): string {
+	return join(CONFIG_DIR, DEFAULT_PROFILE);
+}
+
+/**
+ * Returns the actual config path that will be used, resolving the active profile.
+ */
+export async function getConfigPath(): Promise<string> {
+	return getProfilePath();
+}
+
+export async function loadCoderConfig(): Promise<CoderConfig> {
+	try {
+		const configPath = await getProfilePath();
+		const configFile = Bun.file(configPath);
+
+		if (!(await configFile.exists())) {
+			return getDefaultConfig();
+		}
+
+		const content = await configFile.text();
+		const cliConfig = YAML.parse(content) as CLIConfig;
+
+		const coderConfig: CoderConfig = {
+			org: cliConfig.preferences?.orgId,
+		};
+
+		const result = CoderConfigSchema.safeParse(coderConfig);
+
+		if (!result.success) {
+			console.warn(`Warning: Invalid coder config in ${configPath}:`, result.error.message);
+			return getDefaultConfig();
+		}
+
+		return mergeConfig(getDefaultConfig(), result.data);
+	} catch (error) {
+		console.warn(`Warning: Could not read Agentuity config:`, error);
+		return getDefaultConfig();
+	}
+}
+
+/** Default CLI command patterns to block for security */
+const DEFAULT_BLOCKED_COMMANDS = [
+	'cloud secrets', // Never expose secrets
+	'cloud secret', // Alias
+	'cloud apikey', // Don't leak API keys
+	'auth token', // Don't leak auth tokens
+];
+
+export function getDefaultConfig(): CoderConfig {
+	return {
+		agents: {
+			lead: { model: 'anthropic/claude-opus-4-5-20251101' },
+			scout: { model: 'anthropic/claude-haiku-4-5-20251001' },
+			builder: { model: 'anthropic/claude-opus-4-5-20251101' },
+			reviewer: { model: 'anthropic/claude-haiku-4-5-20251001' },
+			memory: { model: 'anthropic/claude-haiku-4-5-20251001' },
+			expert: { model: 'anthropic/claude-opus-4-5-20251101' },
+		},
+		disabledMcps: [],
+		blockedCommands: DEFAULT_BLOCKED_COMMANDS,
+	};
+}
+
+export function mergeConfig(base: CoderConfig, override: CoderConfig): CoderConfig {
+	// Deep merge agents: for each agent, merge base and override properties
+	const mergedAgents: CoderConfig['agents'] = {};
+	const allAgentKeys = new Set([
+		...Object.keys(base.agents ?? {}),
+		...Object.keys(override.agents ?? {}),
+	]);
+
+	for (const key of allAgentKeys) {
+		const baseAgent = base.agents?.[key as keyof typeof base.agents];
+		const overrideAgent = override.agents?.[key as keyof typeof override.agents];
+		mergedAgents[key as keyof typeof mergedAgents] = {
+			...baseAgent,
+			...overrideAgent,
+		};
+	}
+
+	return {
+		org: override.org ?? base.org,
+		agents: mergedAgents,
+		disabledMcps: override.disabledMcps ?? base.disabledMcps,
+		blockedCommands: override.blockedCommands ?? base.blockedCommands,
+	};
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+import { createCoderPlugin } from './plugin/plugin';
+import type { PluginContext, PluginHooks } from './types';
+
+// NOTE: Do NOT export functions from main index.ts!
+// OpenCode treats ALL exports as plugin instances and calls them.
+// Only the default export should be a function.
+
+// Re-export types only (not functions)
+export type { PluginContext, PluginHooks } from './types';
+export type {
+	AgentRole,
+	AgentConfig,
+	AgentContext,
+	CoderTask,
+	CoderConfig,
+	McpConfig,
+	TaskStatus,
+} from './types';
+
+const Coder = async (ctx: PluginContext): Promise<PluginHooks> => {
+	return createCoderPlugin(ctx);
+};
+
+export default Coder;

package/src/mcps/context7.ts

@@ -0,0 +1,8 @@
+import type { McpConfig } from '../types';
+
+export const context7Mcp: McpConfig = {
+	name: 'context7',
+	type: 'remote',
+	url: 'https://mcp.context7.com/mcp',
+	enabled: true,
+};

package/src/mcps/grep-app.ts

@@ -0,0 +1,8 @@
+import type { McpConfig } from '../types';
+
+export const grepAppMcp: McpConfig = {
+	name: 'grep_app',
+	type: 'remote',
+	url: 'https://mcp.grep.app',
+	enabled: true,
+};

package/src/mcps/index.ts

@@ -0,0 +1,34 @@
+import type { McpConfig } from '../types';
+import { grepAppMcp } from './grep-app';
+import { context7Mcp } from './context7';
+
+export { grepAppMcp } from './grep-app';
+export { context7Mcp } from './context7';
+
+export type McpName = 'grep_app' | 'context7';
+
+const allBuiltinMcps: Record<McpName, McpConfig> = {
+	grep_app: grepAppMcp,
+	context7: context7Mcp,
+};
+
+export function createBuiltinMcps(disabledMcps: string[] = []): Record<string, McpConfig> {
+	const mcps: Record<string, McpConfig> = {};
+	const disabled = new Set(disabledMcps);
+
+	for (const [name, config] of Object.entries(allBuiltinMcps)) {
+		if (!disabled.has(name)) {
+			mcps[name] = config;
+		}
+	}
+
+	return mcps;
+}
+
+export function getMcp(name: McpName): McpConfig {
+	return allBuiltinMcps[name];
+}
+
+export function getAllMcps(): McpConfig[] {
+	return Object.values(allBuiltinMcps);
+}

package/src/plugin/hooks/keyword.ts

@@ -0,0 +1,126 @@
+import type { PluginContext, CoderConfig } from '../../types';
+
+export interface KeywordHooks {
+	onMessage: (input: unknown, output: unknown) => Promise<void>;
+}
+
+const CODER_PATTERN = /\b(ag|agentuity coder)\b/i;
+
+const CODER_ACTIVATION_MESSAGE = `<coder-mode>
+You are now using the Agentuity Coder agent team from Agentuity.
+
+## Your Team (use @mentions to invoke)
+- **@Agentuity Coder Lead**: Orchestrator - breaks down tasks, delegates, never implements directly
+- **@Agentuity Coder Scout**: Explorer - finds patterns, researches docs, analyzes codebase (read-only)
+- **@Agentuity Coder Builder**: Implementer - writes code, runs tests, makes changes
+- **@Agentuity Coder Reviewer**: Quality checker - reviews changes, applies fixes
+- **@Agentuity Coder Memory**: Context keeper - remembers decisions, stores checkpoints
+- **@Agentuity Coder Expert**: Agentuity specialist - knows CLI commands and cloud services
+
+## Agentuity Cloud Services Available
+When genuinely helpful, use these via the CLI:
+- \`agentuity cloud kv\` — Key-value storage for memory/checkpoints
+- \`agentuity cloud storage\` — S3-compatible storage for large files
+- \`agentuity cloud sandbox\` — Isolated execution environments
+- \`agentuity cloud vector\` — Semantic search for large codebases
+- \`agentuity cloud db\` — PostgreSQL for structured data
+
+Run \`agentuity ai schema show\` to see all available CLI commands.
+
+## Guidelines
+1. Break complex tasks into subtasks
+2. Use @Agentuity Coder Scout before implementing to understand context
+3. Have @Agentuity Coder Reviewer check @Agentuity Coder Builder's work
+4. Use cloud services only when they genuinely help
+</coder-mode>
+`;
+
+export function createKeywordHooks(ctx: PluginContext, _config: CoderConfig): KeywordHooks {
+	const activatedSessions = new Set<string>();
+
+	const log = (msg: string) => {
+		ctx.client.app.log({
+			body: {
+				service: 'coder-keyword',
+				level: 'debug',
+				message: msg,
+			},
+		});
+	};
+
+	return {
+		async onMessage(input: unknown, output: unknown): Promise<void> {
+			log(
+				`onMessage called - input keys: ${input ? Object.keys(input as object).join(', ') : 'null'}`
+			);
+			log(
+				`onMessage called - output keys: ${output ? Object.keys(output as object).join(', ') : 'null'}`
+			);
+
+			const sessionId = extractSessionId(input);
+			if (!sessionId) {
+				log('No sessionId found');
+				return;
+			}
+			log(`sessionId: ${sessionId}`);
+
+			const messageText = extractMessageText(output);
+			if (!messageText) {
+				log('No messageText found in output');
+				return;
+			}
+			log(`messageText (first 100 chars): ${messageText.substring(0, 100)}`);
+
+			if (CODER_PATTERN.test(messageText)) {
+				log('CODER_PATTERN matched!');
+				if (!activatedSessions.has(sessionId)) {
+					activatedSessions.add(sessionId);
+					injectContext(output, CODER_ACTIVATION_MESSAGE);
+					log('Context injected');
+				} else {
+					log('Session already activated');
+				}
+			}
+		},
+	};
+}
+
+function extractSessionId(input: unknown): string | undefined {
+	if (typeof input !== 'object' || input === null) return undefined;
+
+	// Try both sessionID and sessionId (Open Code uses sessionID)
+	const inp = input as Record<string, unknown>;
+	if (typeof inp.sessionID === 'string') return inp.sessionID;
+	if (typeof inp.sessionId === 'string') return inp.sessionId;
+	if (typeof inp.session_id === 'string') return inp.session_id;
+
+	return undefined;
+}
+
+function extractMessageText(output: unknown): string | undefined {
+	if (typeof output !== 'object' || output === null) return undefined;
+
+	const out = output as { parts?: Array<{ type?: string; text?: string }> };
+	if (!out.parts || !Array.isArray(out.parts)) return undefined;
+
+	for (const part of out.parts) {
+		if (part.type === 'text' && part.text) {
+			return part.text;
+		}
+	}
+	return undefined;
+}
+
+function injectContext(output: unknown, context: string): void {
+	if (typeof output !== 'object' || output === null) return;
+
+	const out = output as { parts?: Array<{ type?: string; text?: string }> };
+	if (!out.parts || !Array.isArray(out.parts)) return;
+
+	for (const part of out.parts) {
+		if (part.type === 'text' && part.text) {
+			part.text = `${context}\n\n---\n\n${part.text}`;
+			return;
+		}
+	}
+}