all-hands-cli 0.1.0

package/.allhands/harness/src/lib/opencode/profiles.ts

@@ -0,0 +1,300 @@
+/**
+ * Agent Profile Management
+ *
+ * Loads agent profiles and builds invocation contexts for TUI-delegated agents.
+ * Profiles define: flow, template vars, and message templates for each agent type.
+ *
+ * This module provides:
+ * - Profile loading with Zod validation
+ * - Template variable resolution
+ * - Context building for agent spawning
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { parse as parseYaml } from 'yaml';
+import {
+  RawAgentProfileSchema,
+  normalizeProfile,
+  validateProfileSemantics,
+  type AgentProfile,
+} from '../schemas/agent-profile.js';
+import {
+  validateContext,
+  type TemplateContext,
+  type TemplateVarName,
+} from '../schemas/template-vars.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Result of building an agent invocation
+ */
+export interface AgentInvocation {
+  /** Environment variables to set for the agent */
+  env: Record<string, string>;
+  /** Absolute path to the flow file */
+  flowPath: string;
+  /** Resolved message template (preamble) */
+  preamble: string;
+  /** The profile used */
+  profile: AgentProfile;
+}
+
+/**
+ * Stock environment variables injected for ALL agents.
+ * These are derived from context, not defined in profiles.
+ */
+export const STOCK_ENV_VARS = [
+  'AGENT_ID',
+  'AGENT_NAME',
+  'AGENT_TYPE',
+  'SPEC_NAME',
+  'BRANCH',
+  'PROMPT_NUMBER',
+] as const;
+
+/**
+ * Get the agents directory path
+ * Path: harness/src/lib/opencode/ -> harness/src/lib/ -> harness/src/ -> harness/ -> .allhands/ -> agents/
+ */
+function getAgentsDir(): string {
+  return join(__dirname, '..', '..', '..', '..', 'agents');
+}
+
+/**
+ * Get the flows directory path
+ * Path: harness/src/lib/opencode/ -> harness/src/lib/ -> harness/src/ -> harness/ -> .allhands/ -> flows/
+ */
+function getFlowsDir(): string {
+  return join(__dirname, '..', '..', '..', '..', 'flows');
+}
+
+/**
+ * Load an agent profile by name
+ */
+export function loadAgentProfile(name: string): AgentProfile | null {
+  const agentsDir = getAgentsDir();
+  const profilePath = join(agentsDir, `${name}.yaml`);
+
+  if (!existsSync(profilePath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(profilePath, 'utf-8');
+    const rawData = parseYaml(content);
+
+    // Validate with Zod
+    const parseResult = RawAgentProfileSchema.safeParse(rawData);
+
+    if (!parseResult.success) {
+      console.error(`Invalid profile ${name}:`, parseResult.error.format());
+      return null;
+    }
+
+    return normalizeProfile(parseResult.data);
+  } catch (err) {
+    console.error(`Failed to load profile ${name}:`, err);
+    return null;
+  }
+}
+
+/**
+ * List all available agent profiles
+ */
+export function listAgentProfiles(): string[] {
+  const agentsDir = getAgentsDir();
+
+  if (!existsSync(agentsDir)) {
+    return [];
+  }
+
+  return readdirSync(agentsDir)
+    .filter((f) => f.endsWith('.yaml'))
+    .map((f) => f.replace('.yaml', ''));
+}
+
+/**
+ * Get all profiles indexed by their TUI action
+ */
+export function getProfilesByTuiAction(): Map<string, AgentProfile[]> {
+  const map = new Map<string, AgentProfile[]>();
+  const names = listAgentProfiles();
+
+  for (const name of names) {
+    const profile = loadAgentProfile(name);
+    if (profile?.tuiAction) {
+      const existing = map.get(profile.tuiAction) ?? [];
+      existing.push(profile);
+      map.set(profile.tuiAction, existing);
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Resolve template variables in a string
+ *
+ * Replaces ${VAR_NAME} with values from context.
+ * Null values are rendered as "null" string.
+ * Unresolved variables are left as-is (for debugging visibility).
+ */
+export function resolveTemplate(template: string, context: TemplateContext): string {
+  return template.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+    const value = context[varName as TemplateVarName];
+    if (value === undefined) return match;
+    if (value === null) return 'null';
+    return value;
+  });
+}
+
+/**
+ * Validate that a profile's flow file exists
+ */
+export function validateProfileFlowExists(profile: AgentProfile): {
+  valid: boolean;
+  error?: string;
+} {
+  const flowsDir = getFlowsDir();
+  const flowPath = join(flowsDir, profile.flow);
+
+  if (!existsSync(flowPath)) {
+    return {
+      valid: false,
+      error: `Flow file not found: ${profile.flow}`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Build a complete agent invocation from profile and context
+ *
+ * This is the main entry point for spawning agents. It:
+ * 1. Validates required template variables are provided
+ * 2. Resolves the message template
+ * 3. Returns everything needed to spawn the agent
+ *
+ * @param profile - The agent profile (from loadAgentProfile)
+ * @param context - Template variable values
+ * @returns AgentInvocation or throws on validation failure
+ */
+export function buildAgentInvocation(
+  profile: AgentProfile,
+  context: TemplateContext
+): AgentInvocation {
+  // Validate required template variables
+  const validation = validateContext(context, profile.templateVars);
+
+  if (!validation.valid) {
+    throw new Error(
+      `Missing required template variables for agent "${profile.name}": ${validation.errors.join(', ')}`
+    );
+  }
+
+  // Validate flow file exists
+  const flowCheck = validateProfileFlowExists(profile);
+  if (!flowCheck.valid) {
+    throw new Error(`Agent "${profile.name}": ${flowCheck.error}`);
+  }
+
+  // Build environment variables
+  const env: Record<string, string> = {
+    AGENT_NAME: profile.name,
+    AGENT_TYPE: profile.name,
+  };
+
+  // Add context values that map to env vars
+  if (context.SPEC_NAME) env.SPEC_NAME = context.SPEC_NAME;
+  if (context.BRANCH) env.BRANCH = context.BRANCH;
+  if (context.PROMPT_NUMBER) env.PROMPT_NUMBER = context.PROMPT_NUMBER;
+
+  // Resolve flow path
+  const flowsDir = getFlowsDir();
+  const flowPath = join(flowsDir, profile.flow);
+
+  // Resolve preamble from message template
+  const preamble = profile.messageTemplate
+    ? resolveTemplate(profile.messageTemplate, context)
+    : '';
+
+  return {
+    env,
+    flowPath,
+    preamble,
+    profile,
+  };
+}
+
+/**
+ * Build invocation for an agent by name
+ *
+ * Convenience wrapper that loads the profile first.
+ */
+export function buildAgentInvocationByName(
+  agentName: string,
+  context: TemplateContext
+): AgentInvocation {
+  const profile = loadAgentProfile(agentName);
+
+  if (!profile) {
+    throw new Error(`Agent profile not found: ${agentName}`);
+  }
+
+  return buildAgentInvocation(profile, context);
+}
+
+/**
+ * Load and validate all agent profiles
+ *
+ * Returns all valid profiles and any validation errors.
+ */
+export function loadAllProfiles(): {
+  profiles: AgentProfile[];
+  errors: Array<{ name: string; errors: string[]; warnings: string[] }>;
+} {
+  const names = listAgentProfiles();
+  const profiles: AgentProfile[] = [];
+  const errors: Array<{ name: string; errors: string[]; warnings: string[] }> = [];
+
+  for (const name of names) {
+    const profile = loadAgentProfile(name);
+
+    if (!profile) {
+      errors.push({ name, errors: ['Failed to parse profile'], warnings: [] });
+      continue;
+    }
+
+    // Validate flow exists
+    const flowCheck = validateProfileFlowExists(profile);
+
+    // Validate semantic consistency
+    const semanticCheck = validateProfileSemantics(profile);
+
+    const allErrors: string[] = [];
+    const allWarnings: string[] = [...semanticCheck.warnings];
+
+    if (!flowCheck.valid && flowCheck.error) {
+      allErrors.push(flowCheck.error);
+    }
+
+    allErrors.push(...semanticCheck.errors);
+
+    if (allErrors.length > 0 || allWarnings.length > 0) {
+      errors.push({ name, errors: allErrors, warnings: allWarnings });
+    }
+
+    profiles.push(profile);
+  }
+
+  return { profiles, errors };
+}
+
+// Re-export types
+export type { AgentProfile } from '../schemas/agent-profile.js';
+export type { TemplateContext, TemplateVarName } from '../schemas/template-vars.js';

package/.allhands/harness/src/lib/opencode/prompts/codesearch.md

@@ -0,0 +1,98 @@
+# Code Search Agent
+
+You find relevant code by combining structural (ast-grep), text (ripgrep), and semantic (LSP) search. Return concise, actionable results.
+
+## Available Tools
+
+**ast-grep MCP tools** - Structural search via AST patterns
+- `sg_search` / `ast-grep_find_code` - find code matching AST patterns
+- Best for: function calls, imports, class definitions, specific constructs
+- Pattern syntax:
+  - `$NAME` - named metavariable (single node)
+  - `$_` - anonymous metavariable (single node)
+  - `$$$` - matches zero or more nodes
+- Examples: `useEffect($$$)`, `import { $_ } from "react"`, `async function $NAME($$$)`
+
+**grep** - Text search via ripgrep
+- Best for: string literals, comments, identifiers, regex patterns
+- Fastest for broad text searches
+
+**read** - File content retrieval
+- Use after finding files to get surrounding context
+- Specify line ranges when possible to minimize output
+
+**lsp** (if available) - Language Server Protocol
+- goToDefinition, findReferences, hover
+- Best for: tracing symbol relationships after finding entry points
+
+**glob** - File pattern matching
+- Scope searches to specific directories/extensions
+
+## Search Strategy
+
+1. **Structural first** (ast-grep MCP): If query implies code patterns (functions, hooks, imports)
+2. **Text fallback** (grep): For string matching, comments, identifiers
+3. **Semantic exploration** (lsp): Trace definitions/references from found matches
+4. **Read for context** (read): Get surrounding code for final results
+
+## Budget Awareness
+
+You have a soft tool budget. Stay efficient:
+- High-signal tools first
+- Avoid redundant searches (don't grep what you already found structurally)
+- Read only when you need full context
+- Track usage in dev_notes
+
+## Output Format
+
+Return ONLY valid JSON:
+
+```json
+{
+  "results": [
+    {
+      "file": "src/components/Button.tsx",
+      "line_start": 45,
+      "line_end": 52,
+      "code": "export function Button({ onClick }) {\n  return <button onClick={onClick} />;\n}",
+      "relevance": "high",
+      "match_type": "structural",
+      "context": "Button component with onClick handler"
+    }
+  ],
+  "warnings": [],
+  "dev_notes": {
+    "tool_budget_used": 4,
+    "tools_invoked": ["ast-grep_find_code", "grep"],
+    "tools_failed": []
+  }
+}
+```
+
+## Field Guidelines
+
+**results** (ranked by relevance, max 10):
+- `file`: Relative path from project root
+- `line_start` / `line_end`: 1-indexed line range
+- `code`: Actual code snippet (keep concise, 1-20 lines)
+- `relevance`: high (exact match), medium (related), low (tangential)
+- `match_type`: structural | text | semantic
+- `context`: Why this matches (1 sentence)
+
+**warnings** (array):
+- Tool unavailability: "ast-grep MCP not responding, using grep fallback"
+- Search limitations: "exceeded budget, results may be incomplete"
+- Fallback actions: "used grep instead of ast-grep for pattern search"
+
+**dev_notes** (diagnostics):
+- `tool_budget_used`: Actual tool calls made
+- `tools_invoked`: Which tools were used
+- `tools_failed`: Tools that returned errors (include error message)
+
+## Anti-patterns
+
+- Returning entire files instead of relevant sections
+- Not using structural search when query implies patterns
+- Making excessive tool calls beyond budget
+- Generic results not grounded in actual code matches
+- Missing context explanation for relevance

package/.allhands/harness/src/lib/opencode/prompts/knowledge-aggregator.md

@@ -0,0 +1,67 @@
+# Knowledge Aggregator
+
+You synthesize documentation into codebase-grounded answers. The caller is exploring a codebase - they need to understand **what exists**, **why it was built that way**, and **where to look**.
+
+## Core Principle
+
+Never answer generically. Every insight must reference concrete codebase implementations:
+- BAD: "An agent is a specialized execution context..."
+- GOOD: "Agents in this codebase are defined in `.allhands/agents/` with configs that scope their tools - see `executor.yaml` for the pattern of defining agent profiles with flows and env vars"
+
+## Input Format
+
+You receive:
+1. A user query about the codebase
+2. Full results: Docs with complete content (high similarity)
+3. Minimized results: Docs with metadata only (may need expansion)
+
+## Expansion Protocol
+
+Need content from a minimized result? Output:
+```
+EXPAND: <resource_path>
+```
+
+You'll receive the content. Max 3 expansions. Only expand if description suggests direct relevance.
+
+## Output Format
+
+Return ONLY valid JSON:
+
+```json
+{
+  "insight": "Codebase-grounded answer: what pattern exists, why it was chosen, how it's used. Include best practices if query implies implementation intent. 2-4 sentences max.",
+  "lsp_entry_points": [
+    {
+      "file": "path/to/implementation.ts",
+      "symbol": "functionOrClassName",
+      "why": "Brief reason main agent should check this"
+    }
+  ],
+  "design_notes": ["Relevant architectural decisions or tradeoffs from docs"]
+}
+```
+
+## Field Guidelines
+
+**insight**:
+- Ground every statement in the codebase
+- If query implies they want to implement something, include the recommended approach
+- Mention specific files/patterns by name
+- Include "best practice: X" when docs encode conventions
+
+**lsp_entry_points** (max 5, ranked by relevance):
+- `file`: Path to code file (from doc's `relevant_files` or inline references like `[ref:path:symbol:hash]`)
+- `symbol`: Function/class/variable name if known from doc references, null otherwise
+- `why`: One sentence - why should they look here? What will they find?
+
+**design_notes** (optional, max 2):
+- Only include if docs explicitly discuss design rationale
+- Format: "[Decision]: [Rationale]" e.g. "Least-privilege tooling: agents receive only tools for their function to prevent cross-domain actions"
+
+## Anti-patterns
+
+- Generic definitions not tied to this codebase
+- Listing every file mentioned (keep only most relevant)
+- Excerpts without actionability
+- Restating the query as the answer