all-hands-cli 0.1.6 → 0.1.7

package/.allhands/harness/src/commands/solutions.ts

@@ -3,19 +3,30 @@
  *
  * Grep-based search for documented solutions in docs/solutions/.
  * Uses frontmatter fields (tags, module, component, symptoms) for precise matching.
+ * Search includes AI aggregation with memory context from docs/memories.md.
  *
  * Usage:
- *   ah solutions search <query>           Search solutions by keywords
- *   ah solutions search <query> --full    Include full content of matches
- *   ah solutions list                     List all solution categories
- *   ah solutions list <category>          List solutions in a category
+ *   ah solutions search <query>                Search solutions with AI aggregation + memory context
+ *   ah solutions search <query> --no-aggregate Skip aggregation, return raw matches
+ *   ah solutions search <query> --full         Include full content of matches (no-aggregate mode)
  */
 
 import { Command } from 'commander';
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
-import { basename, join } from 'path';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { parse } from 'yaml';
 import { tracedAction } from '../lib/base-command.js';
+import { AgentRunner, withDebugInfo, type SolutionSearchOutput } from '../lib/opencode/index.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const AGGREGATOR_PROMPT_PATH = join(__dirname, '../lib/opencode/prompts/solutions-aggregator.md');
+
+const getAggregatorPrompt = (): string => {
+  return readFileSync(AGGREGATOR_PROMPT_PATH, 'utf-8');
+};
 
 const getProjectRoot = (): string => {
   return process.env.PROJECT_ROOT || process.cwd();
@@ -25,6 +36,10 @@ const getSolutionsDir = (): string => {
   return join(getProjectRoot(), 'docs', 'solutions');
 };
 
+const getMemoriesPath = (): string => {
+  return join(getProjectRoot(), 'docs', 'memories.md');
+};
+
 interface SolutionFrontmatter {
   title: string;
   date: string;
@@ -45,6 +60,13 @@ interface SolutionMatch {
   matchedFields: string[];
 }
 
+interface MemoryEntry {
+  name: string;
+  domain: string;
+  source: string;
+  description: string;
+}
+
 /**
  * Extract keywords from a search query.
  * Handles quoted phrases and splits on whitespace.
@@ -155,20 +177,6 @@ function findSolutionFiles(dir: string): string[] {
   return files;
 }
 
-/**
- * Get all category directories.
- */
-function getCategories(dir: string): string[] {
-  if (!existsSync(dir)) return [];
-
-  return readdirSync(dir)
-    .filter(entry => {
-      const fullPath = join(dir, entry);
-      return statSync(fullPath).isDirectory();
-    })
-    .sort();
-}
-
 /**
  * Search for solutions matching the query.
  */
@@ -221,22 +229,107 @@ function getSolutionContent(filePath: string): string | null {
   }
 }
 
+/**
+ * Parse all memory entries from docs/memories.md.
+ */
+function parseMemories(): MemoryEntry[] {
+  const memoriesPath = getMemoriesPath();
+  if (!existsSync(memoriesPath)) return [];
+
+  const content = readFileSync(memoriesPath, 'utf-8');
+  const lines = content.split('\n');
+  const entries: MemoryEntry[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip non-table lines, header rows, and separator rows
+    if (!trimmed.startsWith('|') || trimmed.includes('---') || /\|\s*Name\s*\|/i.test(trimmed)) {
+      continue;
+    }
+
+    // Parse table row
+    const cells = trimmed.split('|').map(c => c.trim()).filter(c => c.length > 0);
+    if (cells.length >= 4) {
+      entries.push({
+        name: cells[0],
+        domain: cells[1],
+        source: cells[2],
+        description: cells[3],
+      });
+    }
+  }
+
+  return entries;
+}
+
 export function register(program: Command): void {
   const solutionsCmd = program
     .command('solutions')
-    .description('Search and browse documented solutions');
+    .description('Search and browse documented solutions (includes memory context)');
 
   // Search command
   solutionsCmd
     .command('search <query>')
-    .description('Search solutions by keywords (searches title, tags, component, symptoms)')
-    .option('--full', 'Include full content of matched solutions')
+    .description('Search solutions by keywords with AI aggregation and memory context')
+    .option('--full', 'Include full content of matched solutions (non-aggregated mode)')
     .option('--limit <n>', 'Maximum number of results', '10')
-    .action(tracedAction('solutions search', async (query: string, options: { full?: boolean; limit?: string }) => {
-      const limit = parseInt(options.limit || '10', 10);
+    .option('--no-aggregate', 'Skip aggregation, return raw matches')
+    .option('--debug', 'Include agent debug metadata (model, timing, fallback) in output')
+    .action(tracedAction('solutions search', async (query: string, _opts: Record<string, unknown>, command: Command) => {
+      const opts = command.opts();
+      const limit = parseInt(opts.limit as string || '10', 10);
+      const noAggregate = opts.aggregate === false;
+      const debug = !!opts.debug;
+      const full = !!opts.full;
+
       const matches = searchSolutions(query, limit);
 
       if (matches.length === 0) {
+        // Still check memories even when no solution matches
+        if (!noAggregate) {
+          const memories = parseMemories();
+          if (memories.length > 0) {
+            // Build aggregation input with only memories
+            const userMessage = JSON.stringify({
+              query,
+              solutions: [],
+              memories,
+            });
+
+            const projectRoot = getProjectRoot();
+            const runner = new AgentRunner(projectRoot);
+
+            try {
+              const agentResult = await runner.run<SolutionSearchOutput>(
+                {
+                  name: 'solutions-aggregator',
+                  systemPrompt: getAggregatorPrompt(),
+                  timeoutMs: 60000,
+                  steps: 5,
+                },
+                userMessage,
+              );
+
+              if (agentResult.success && agentResult.data) {
+                console.log(JSON.stringify(withDebugInfo({
+                  success: true,
+                  query,
+                  aggregated: true,
+                  guidance: agentResult.data.guidance,
+                  relevant_solutions: agentResult.data.relevant_solutions,
+                  memory_insights: agentResult.data.memory_insights,
+                  design_notes: agentResult.data.design_notes,
+                  source_matches: 0,
+                }, agentResult, debug), null, 2));
+                return;
+              }
+            } catch {
+              // Fall through to no-results output
+            }
+          }
+        }
+
         console.log(JSON.stringify({
           success: true,
           query,
@@ -247,107 +340,130 @@ export function register(program: Command): void {
         return;
       }
 
-      // Format output
-      const results = matches.map(match => {
-        const result: Record<string, unknown> = {
-          path: match.path,
-          title: match.frontmatter.title,
-          score: match.score,
-          matched_fields: match.matchedFields,
-          severity: match.frontmatter.severity,
-          problem_type: match.frontmatter.problem_type,
-          component: match.frontmatter.component,
-          tags: match.frontmatter.tags,
-        };
+      // Return raw matches if aggregation disabled
+      if (noAggregate) {
+        const results = matches.map(match => {
+          const result: Record<string, unknown> = {
+            path: match.path,
+            title: match.frontmatter.title,
+            score: match.score,
+            matched_fields: match.matchedFields,
+            severity: match.frontmatter.severity,
+            problem_type: match.frontmatter.problem_type,
+            component: match.frontmatter.component,
+            tags: match.frontmatter.tags,
+          };
+
+          if (full) {
+            result.content = getSolutionContent(match.path);
+          }
+
+          return result;
+        });
 
-        if (options.full) {
-          result.content = getSolutionContent(match.path);
-        }
+        console.log(JSON.stringify({
+          success: true,
+          query,
+          keywords: extractKeywords(query),
+          result_count: results.length,
+          results,
+          aggregated: false,
+        }, null, 2));
+        return;
+      }
 
-        return result;
+      // Build aggregation input
+      const solutionsInput = matches.map(m => {
+        const content = getSolutionContent(m.path);
+        return {
+          title: m.frontmatter.title,
+          path: m.path,
+          severity: m.frontmatter.severity,
+          problem_type: m.frontmatter.problem_type,
+          component: m.frontmatter.component,
+          tags: m.frontmatter.tags,
+          content: content || '',
+        };
       });
 
-      console.log(JSON.stringify({
-        success: true,
-        query,
-        keywords: extractKeywords(query),
-        result_count: results.length,
-        results,
-      }, null, 2));
-    }));
-
-  // List command
-  solutionsCmd
-    .command('list [category]')
-    .description('List solution categories or solutions in a category')
-    .action(tracedAction('solutions list', async (category?: string) => {
-      const solutionsDir = getSolutionsDir();
+      const memories = parseMemories();
 
-      if (!category) {
-        // List all categories
-        const categories = getCategories(solutionsDir);
+      const userMessage = JSON.stringify({
+        query,
+        solutions: solutionsInput,
+        memories,
+      });
 
-        if (categories.length === 0) {
-          console.log(JSON.stringify({
+      const projectRoot = getProjectRoot();
+      const runner = new AgentRunner(projectRoot);
+
+      try {
+        const agentResult = await runner.run<SolutionSearchOutput>(
+          {
+            name: 'solutions-aggregator',
+            systemPrompt: getAggregatorPrompt(),
+            timeoutMs: 60000,
+            steps: 5,
+          },
+          userMessage,
+        );
+
+        if (!agentResult.success) {
+          // Graceful degradation: return raw matches on aggregation failure
+          const results = matches.map(match => ({
+            path: match.path,
+            title: match.frontmatter.title,
+            score: match.score,
+            matched_fields: match.matchedFields,
+            severity: match.frontmatter.severity,
+            problem_type: match.frontmatter.problem_type,
+            component: match.frontmatter.component,
+            tags: match.frontmatter.tags,
+          }));
+
+          console.log(JSON.stringify(withDebugInfo({
             success: true,
-            message: 'No solution categories found. Create docs/solutions/<category>/ directories.',
-            categories: [],
-          }, null, 2));
+            query,
+            results,
+            count: results.length,
+            aggregated: false,
+            aggregation_error: agentResult.error,
+          }, agentResult, debug), null, 2));
           return;
         }
 
-        // Count solutions in each category
-        const categoryCounts = categories.map(cat => {
-          const catDir = join(solutionsDir, cat);
-          const files = findSolutionFiles(catDir);
-          return { category: cat, count: files.length };
-        });
-
-        console.log(JSON.stringify({
+        console.log(JSON.stringify(withDebugInfo({
           success: true,
-          categories: categoryCounts,
-        }, null, 2));
-        return;
-      }
-
-      // List solutions in specific category
-      const categoryDir = join(solutionsDir, category);
+          query,
+          aggregated: true,
+          guidance: agentResult.data!.guidance,
+          relevant_solutions: agentResult.data!.relevant_solutions,
+          memory_insights: agentResult.data!.memory_insights,
+          design_notes: agentResult.data!.design_notes,
+          source_matches: matches.length,
+        }, agentResult, debug), null, 2));
+      } catch (error) {
+        // Graceful degradation on any error
+        const message = error instanceof Error ? error.message : String(error);
+        const results = matches.map(match => ({
+          path: match.path,
+          title: match.frontmatter.title,
+          score: match.score,
+          matched_fields: match.matchedFields,
+          severity: match.frontmatter.severity,
+          problem_type: match.frontmatter.problem_type,
+          component: match.frontmatter.component,
+          tags: match.frontmatter.tags,
+        }));
 
-      if (!existsSync(categoryDir)) {
-        const available = getCategories(solutionsDir);
         console.log(JSON.stringify({
-          success: false,
-          error: `Category not found: ${category}`,
-          available_categories: available,
+          success: true,
+          query,
+          results,
+          count: results.length,
+          aggregated: false,
+          aggregation_error: message,
         }, null, 2));
-        process.exit(1);
       }
-
-      const files = findSolutionFiles(categoryDir);
-      const solutions = files.map(file => {
-        const fm = parseFrontmatter(file);
-        const relativePath = file.replace(getProjectRoot() + '/', '');
-        return {
-          path: relativePath,
-          title: fm?.title || basename(file, '.md'),
-          date: fm?.date,
-          severity: fm?.severity,
-          tags: fm?.tags || [],
-        };
-      });
-
-      // Sort by date descending
-      solutions.sort((a, b) => {
-        if (!a.date) return 1;
-        if (!b.date) return -1;
-        return b.date.localeCompare(a.date);
-      });
-
-      console.log(JSON.stringify({
-        success: true,
-        category,
-        solution_count: solutions.length,
-        solutions,
-      }, null, 2));
     }));
 }

package/.allhands/harness/src/commands/spawn.ts

@@ -9,7 +9,7 @@ import { Command } from "commander";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { AgentRunner } from "../lib/opencode/index.js";
+import { AgentRunner, withDebugInfo } from "../lib/opencode/index.js";
 import { BaseCommand, type CommandResult } from "../lib/base-command.js";
 import { loadProjectSettings } from "../hooks/shared.js";
 
@@ -60,11 +60,13 @@ class CodesearchCommand extends BaseCommand {
     cmd
       .argument("<query>", "Code search query (natural language or pattern)")
       .option("--budget <n>", "Soft tool budget hint for the agent", String(DEFAULT_TOOL_BUDGET))
-      .option("--steps <n>", "Hard step limit for agent iterations", String(DEFAULT_STEPS_LIMIT));
+      .option("--steps <n>", "Hard step limit for agent iterations", String(DEFAULT_STEPS_LIMIT))
+      .option("--debug", "Include agent debug metadata (model, timing, fallback) in output");
   }
 
   async execute(args: Record<string, unknown>): Promise<CommandResult> {
     const query = args.query as string;
+    const debug = !!args.debug;
     const settings = loadProjectSettings();
     const toolBudget = parseInt(
       (args.budget as string) ??
@@ -98,13 +100,6 @@ Respond with JSON matching the required schema.`;
           systemPrompt: getCodesearchPrompt(),
           timeoutMs: DEFAULT_TIMEOUT_MS,
           steps: stepsLimit,
-          // MCP servers can be configured via environment or passed explicitly
-          // mcp: {
-          //   "ast-grep": {
-          //     type: "local",
-          //     command: ["uvx", "--from", "ast-grep-mcp", "ast-grep-mcp"],
-          //   },
-          // },
         },
         userMessage
       );
@@ -115,16 +110,14 @@ Respond with JSON matching the required schema.`;
 
       const data = result.data!;
 
-      // Warnings are included in the response data
-
-      return this.success({
+      return this.success(withDebugInfo({
         query,
         result_count: data.results.length,
         results: data.results,
         warnings: data.warnings,
         dev_notes: data.dev_notes,
         metadata: result.metadata,
-      });
+      }, result, debug));
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       return this.error("spawn_error", message);

package/.allhands/harness/src/hooks/shared.ts

@@ -538,6 +538,7 @@ export interface OracleSettings {
 /** OpenCode SDK agent execution settings */
 export interface OpencodeSdkSettings {
   model?: string;
+  fallbackModel?: string;
   codesearchToolBudget?: number;
 }
 

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

@@ -36,6 +36,8 @@ export interface AgentResult<T = unknown> {
     model: string;
     tokens_used?: number;
     duration_ms: number;
+    fallback?: boolean;
+    primary_error?: string;
   };
 }
 
@@ -56,6 +58,38 @@ export interface AggregatorInput {
   minimized_results: SearchResult[];
 }
 
+// Skills aggregator output
+export interface SkillSearchOutput {
+  guidance: string;
+  relevant_skills: Array<{
+    name: string;
+    file: string;
+    relevance: string;
+    key_excerpts: string[];
+    references: string[];
+  }>;
+  design_notes?: string[];
+}
+
+// Solutions aggregator output
+export interface SolutionSearchOutput {
+  guidance: string;
+  relevant_solutions: Array<{
+    title: string;
+    file: string;
+    relevance: string;
+    key_excerpts: string[];
+    related_memories: string[];
+  }>;
+  memory_insights: Array<{
+    name: string;
+    domain: string;
+    source: string;
+    relevance: string;
+  }>;
+  design_notes?: string[];
+}
+
 // Knowledge aggregator output
 export interface AggregatorOutput {
   insight: string;
@@ -68,3 +102,34 @@ export interface AggregatorOutput {
 }
 
 export { AgentRunner } from "./runner.js";
+
+// Debug metadata for agent results (included when --debug flag is passed)
+export interface AgentDebugInfo {
+  model_used: string;
+  time_taken_ms: number;
+  fallback_used: boolean;
+  primary_error?: string;
+  tokens_used?: number;
+}
+
+/**
+ * Conditionally enrich a payload with agent debug metadata.
+ * Use with --debug flag on commands that run opencode agents.
+ */
+export function withDebugInfo<T extends Record<string, unknown>>(
+  payload: T,
+  result: AgentResult,
+  debug: boolean,
+): T & { _debug?: AgentDebugInfo } {
+  if (!debug || !result.metadata) return payload;
+  return {
+    ...payload,
+    _debug: {
+      model_used: result.metadata.model,
+      time_taken_ms: result.metadata.duration_ms,
+      fallback_used: result.metadata.fallback ?? false,
+      primary_error: result.metadata.primary_error,
+      tokens_used: result.metadata.tokens_used,
+    },
+  };
+}

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

@@ -0,0 +1,77 @@
+# Skills Aggregator
+
+You synthesize domain expertise from skill files into task-relevant guidance. The caller needs actionable knowledge for their implementation task - not a skill catalog.
+
+## Core Principle
+
+Extract what matters for the task. Every piece of guidance must be grounded in skill content:
+- BAD: "Follow best practices for component design..."
+- GOOD: "The building-expo-ui skill specifies using `<Link.Preview>` for context menus and `contentInsetAdjustmentBehavior="automatic"` over SafeAreaView - see `.allhands/skills/building-expo-ui/SKILL.md`"
+
+## Input Format
+
+You receive JSON with:
+1. `query`: The user's task description or question
+2. `skills`: Array of matched skills, each containing:
+   - `name`: Skill identifier
+   - `description`: What the skill covers
+   - `globs`: File patterns this skill applies to
+   - `file`: Path to SKILL.md
+   - `content`: Full SKILL.md body (without frontmatter)
+   - `reference_files`: Paths to reference docs within the skill directory
+
+## Expansion Protocol
+
+Need content from a reference file? Output:
+```
+EXPAND: <reference_file_path>
+```
+
+You'll receive the content. Max 3 expansions. Only expand if the reference file path suggests direct relevance to the query.
+
+## Output Format
+
+Return ONLY valid JSON:
+
+```json
+{
+  "guidance": "Task-relevant synthesis: what patterns to follow, what to avoid, key conventions. Ground every statement in skill content. 3-6 sentences max.",
+  "relevant_skills": [
+    {
+      "name": "skill-name",
+      "file": ".allhands/skills/skill-name/SKILL.md",
+      "relevance": "Why this skill matters for the query",
+      "key_excerpts": ["Specific actionable instructions extracted from the skill"],
+      "references": [".allhands/skills/skill-name/references/relevant-doc.md"]
+    }
+  ],
+  "design_notes": ["Architectural decisions or constraints from skills that affect the task"]
+}
+```
+
+## Field Guidelines
+
+**guidance**:
+- Synthesize across all matched skills into coherent task guidance
+- Include specific patterns, conventions, and constraints
+- Mention file paths and skill names for attribution
+- If skills encode best practices, state them as "best practice: X"
+
+**relevant_skills** (ranked by relevance to query):
+- `name`: Skill identifier
+- `file`: Path to SKILL.md
+- `relevance`: One sentence - why does this skill matter for the task?
+- `key_excerpts`: 1-4 specific, actionable instructions extracted verbatim or closely paraphrased from the skill
+- `references`: Paths that contain deeper information for the caller. May include the SKILL.md itself (from `file`) alongside reference docs (from `reference_files`). Only include paths that are relevant to the query.
+
+**design_notes** (optional, max 3):
+- Only include if skills explicitly discuss design rationale or constraints
+- Format: "[Constraint]: [Detail]" e.g. "First principles required: MUST cite first principles by name when adding features"
+
+## Anti-patterns
+
+- Generic advice not grounded in skill content
+- Copying entire skill files instead of extracting task-relevant parts
+- Including skills that aren't relevant to the query
+- Restating the query as guidance
+- Listing every reference file (only include relevant ones)