@jaguilar87/gaia 5.0.0-rc.2

package/bin/gaia-evidence

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""
+gaia-evidence -- Execute evidence.shape blocks from a brief's frontmatter.
+
+Usage:
+    gaia-evidence run <brief.md>
+    gaia-evidence --help
+
+The runner resolves each AC's evidence type and delegates to run_command or
+run_artifact. Artifacts are persisted under the brief's evidence/ directory
+and a fresh INDEX.md is rendered. Exit code 0 means every AC passed.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Make gaia-ops-dev importable so `hooks.modules.evidence` resolves whether
+# this script runs from a checkout or a symlinked install.
+_SCRIPT_DIR = Path(__file__).resolve().parent
+_PLUGIN_ROOT = _SCRIPT_DIR.parent
+if str(_PLUGIN_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PLUGIN_ROOT))
+
+from hooks.modules.evidence.index_writer import write_index
+from hooks.modules.evidence.loader import (
+    InvalidBriefFrontmatter,
+    UnknownEvidenceType,
+    load_acs,
+)
+from hooks.modules.evidence.runner import (
+    EvidenceResult,
+    run_artifact,
+    run_command,
+)
+
+
+def _cmd_run(brief_path_str: str) -> int:
+    """Execute every AC in the brief; return 0 if all pass."""
+    brief_path = Path(brief_path_str).resolve()
+    if not brief_path.is_file():
+        print(f"error: brief not found: {brief_path}", file=sys.stderr)
+        return 2
+
+    try:
+        acs = load_acs(brief_path)
+    except InvalidBriefFrontmatter as exc:
+        print(f"error: invalid frontmatter: {exc}", file=sys.stderr)
+        return 2
+    except UnknownEvidenceType as exc:
+        print(f"error: unknown evidence type: {exc}", file=sys.stderr)
+        return 2
+
+    if not acs:
+        print("no acceptance_criteria in brief", file=sys.stderr)
+        return 0
+
+    brief_dir = brief_path.parent
+    evidence_dir = brief_dir / "evidence"
+    evidence_dir.mkdir(parents=True, exist_ok=True)
+
+    results: list[tuple[str, EvidenceResult]] = []
+    all_passed = True
+
+    for ac in acs:
+        artifact_rel = ac.artifact or f"evidence/{ac.id}.txt"
+        artifact_path = (brief_dir / artifact_rel).resolve()
+
+        if ac.type == "command":
+            result = run_command(ac.shape, artifact_path)
+        elif ac.type == "artifact":
+            result = run_artifact(ac.shape, artifact_path)
+        else:
+            # Types registered by the loader but not yet supported.
+            artifact_path.parent.mkdir(parents=True, exist_ok=True)
+            artifact_path.write_text(
+                f"evidence type '{ac.type}' not yet implemented\n",
+                encoding="utf-8",
+            )
+            result = EvidenceResult(
+                passed=False,
+                output=f"unsupported type: {ac.type}",
+                artifact_path=artifact_path,
+                error=f"unsupported_type:{ac.type}",
+            )
+
+        status = "PASS" if result.passed else "FAIL"
+        err = f" ({result.error})" if result.error else ""
+        print(f"[{status}] {ac.id}: {ac.description}{err}")
+        if not result.passed:
+            all_passed = False
+        results.append((ac.id, result))
+
+    write_index(evidence_dir, results)
+    return 0 if all_passed else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="gaia-evidence",
+        description=(
+            "Execute evidence.shape blocks declared in a brief's frontmatter "
+            "and persist artifacts under the brief's evidence/ directory."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run_parser = sub.add_parser(
+        "run",
+        help="Run every AC in the given brief.md",
+    )
+    run_parser.add_argument(
+        "brief",
+        help="Path to brief.md with an acceptance_criteria frontmatter block",
+    )
+
+    args = parser.parse_args(argv)
+    if args.command == "run":
+        return _cmd_run(args.brief)
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/gaia-history.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+
+/**
+ * @jaguilar87/gaia - Agent Session History CLI
+ *
+ * Shows recent agent sessions with task descriptions, outcomes, and token usage.
+ *
+ * Usage:
+ *   npx gaia-history                    # last 20 sessions
+ *   npx gaia-history --today / -t       # today only
+ *   npx gaia-history --blocked / -b     # BLOCKED or NEEDS_INPUT sessions only
+ *   npx gaia-history --agent <name> / -a <name>  # filter by agent
+ *   npx gaia-history --limit <n> / -n <n>        # show N sessions (default 20)
+ */
+
+import { join, dirname, resolve } from 'path';
+import fs from 'fs/promises';
+import { existsSync } from 'fs';
+import chalk from 'chalk';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+function findProjectRoot() {
+  if (process.env.INIT_CWD) {
+    if (existsSync(join(process.env.INIT_CWD, '.claude'))) return process.env.INIT_CWD;
+  }
+  let currentDir = process.cwd();
+  const root = resolve('/');
+  while (currentDir !== root) {
+    if (existsSync(join(currentDir, '.claude'))) return currentDir;
+    currentDir = dirname(currentDir);
+  }
+  return process.env.INIT_CWD || process.cwd();
+}
+
+const CWD = findProjectRoot();
+
+// ─────────────────────────────────────────────────────────────
+// DATA READERS
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Read workflow metrics from the episodic memory index (primary source).
+ * Falls back to workflow-episodic-memory/metrics.jsonl for backward compatibility.
+ * Fields: timestamp, agent, exit_code, output_length, task_id, session_id,
+ *         plan_status, output_tokens_approx, prompt
+ */
+async function readWorkflowMetrics() {
+  // Primary: episodic-memory/index.json
+  try {
+    const indexPath = join(CWD, '.claude', 'project-context', 'episodic-memory', 'index.json');
+    if (existsSync(indexPath)) {
+      const data = JSON.parse(await fs.readFile(indexPath, 'utf-8'));
+      const episodes = (data.episodes || []).filter(e => e.agent);
+      if (episodes.length > 0) return episodes;
+    }
+  } catch { /* fall through to legacy */ }
+
+  // Fallback: workflow-episodic-memory/metrics.jsonl
+  try {
+    const metricsPath = join(CWD, '.claude', 'project-context', 'workflow-episodic-memory', 'metrics.jsonl');
+    if (!existsSync(metricsPath)) return [];
+
+    const content = await fs.readFile(metricsPath, 'utf-8');
+    return content.split('\n')
+      .filter(l => l.trim())
+      .map(l => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(r => r !== null && r.agent); // skip blank-agent entries
+  } catch {
+    return [];
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// FORMAT HELPERS
+// ─────────────────────────────────────────────────────────────
+
+const GENERIC_PROMPT_RE = /^SubagentStop for /i;
+
+/**
+ * Format time as HH:MM (always, since history spans at most a few days).
+ */
+function formatTime(iso) {
+  if (!iso) return '?';
+  try {
+    const d = new Date(iso);
+    const today = new Date().toISOString().slice(0, 10);
+    const dayStr = d.toISOString().slice(0, 10);
+    const timeStr = d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', hour12: false });
+    if (dayStr === today) return timeStr;
+    return `${dayStr.slice(5)} ${timeStr}`;
+  } catch {
+    return iso.slice(11, 16);
+  }
+}
+
+/**
+ * Truncate a task description to fit the table column.
+ */
+function truncate(str, maxLen) {
+  if (!str) return '';
+  str = str.replace(/\n/g, ' ').replace(/\s+/g, ' ').trim();
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 1) + '…';
+}
+
+/**
+ * Format approximate token count.
+ */
+function formatTokens(n) {
+  if (n === null || n === undefined) return '   n/a';
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`.padStart(6);
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`.padStart(6);
+  return `${n}`.padStart(6);
+}
+
+/**
+ * Color a plan_status string for display.
+ */
+function colorStatus(status) {
+  if (!status) return chalk.gray('  n/a  ');
+  const s = status.toUpperCase();
+  if (s === 'COMPLETE') return chalk.green(s.padEnd(8));
+  if (s === 'BLOCKED') return chalk.red(s.padEnd(8));
+  if (s === 'NEEDS_INPUT') return chalk.yellow(s.padEnd(8));
+  if (s === 'IN_PROGRESS') return chalk.cyan(s.padEnd(8));
+  if (s === 'REVIEW') return chalk.magenta(s.padEnd(8));
+  return chalk.gray(s.padEnd(8));
+}
+
+// ─────────────────────────────────────────────────────────────
+// MAIN
+// ─────────────────────────────────────────────────────────────
+
+async function main() {
+  process.stderr.write('[DEPRECATED] gaia-history.js is deprecated. Use: python3 bin/gaia history\n[DEPRECATED] Migration guide: see CHANGELOG.md\n');
+
+  const args = yargs(hideBin(process.argv))
+    .option('today', { alias: 't', type: 'boolean', default: false, description: 'Show today only' })
+    .option('blocked', { alias: 'b', type: 'boolean', default: false, description: 'Show BLOCKED/NEEDS_INPUT only' })
+    .option('agent', { alias: 'a', type: 'string', description: 'Filter by agent name' })
+    .option('limit', { alias: 'n', type: 'number', default: 20, description: 'Max sessions to show' })
+    .help('h').alias('h', 'help')
+    .version(false)
+    .parse();
+
+  const claudeDir = join(CWD, '.claude');
+  if (!existsSync(claudeDir)) {
+    console.log(chalk.yellow('\n  gaia-ops not installed in this directory'));
+    console.log(chalk.gray('  Run: npx gaia-scan\n'));
+    process.exit(1);
+  }
+
+  let entries = await readWorkflowMetrics();
+
+  if (entries.length === 0) {
+    console.log(chalk.yellow('\n  No agent session history found yet'));
+    console.log(chalk.gray('  History is recorded after each agent completes\n'));
+    process.exit(0);
+  }
+
+  // Apply filters
+  if (args.today) {
+    const today = new Date().toISOString().slice(0, 10);
+    entries = entries.filter(r => r.timestamp && r.timestamp.startsWith(today));
+  }
+
+  if (args.blocked) {
+    entries = entries.filter(r => {
+      const s = (r.plan_status || '').toUpperCase();
+      return s === 'BLOCKED' || s === 'NEEDS_INPUT';
+    });
+  }
+
+  if (args.agent) {
+    const needle = args.agent.toLowerCase();
+    entries = entries.filter(r => r.agent && r.agent.toLowerCase().includes(needle));
+  }
+
+  // Sort newest-first, then apply limit
+  entries = entries
+    .slice()
+    .sort((a, b) => (b.timestamp || '').localeCompare(a.timestamp || ''))
+    .slice(0, args.limit);
+
+  if (entries.length === 0) {
+    console.log(chalk.yellow('\n  No sessions match the current filters\n'));
+    process.exit(0);
+  }
+
+  // Column widths
+  const TIME_W  = 11;
+  const AGENT_W = 22;
+  const TASK_W  = 38;
+  const STATUS_W = 12;
+  const SEP = chalk.gray('─'.repeat(TIME_W + AGENT_W + TASK_W + STATUS_W + 16));
+
+  console.log(chalk.cyan('\n  Agent Session History'));
+  console.log('  ' + SEP);
+  console.log(
+    chalk.gray(
+      `  ${'Time'.padEnd(TIME_W)} ${'Agent'.padEnd(AGENT_W)} ${'Task'.padEnd(TASK_W)} ${'Status'.padEnd(STATUS_W)} ~Tokens`
+    )
+  );
+  console.log('  ' + SEP);
+
+  let totalTokens = 0;
+  const agentSet = new Set();
+
+  for (const entry of entries) {
+    const time  = formatTime(entry.timestamp).padEnd(TIME_W);
+    const agent = (entry.agent || 'unknown').padEnd(AGENT_W);
+
+    // Build task description: use prompt if it's not a generic "SubagentStop for ..." fallback
+    const rawPrompt = entry.prompt || '';
+    const task = GENERIC_PROMPT_RE.test(rawPrompt) || !rawPrompt
+      ? chalk.gray('(no description)'.padEnd(TASK_W))
+      : truncate(rawPrompt, TASK_W).padEnd(TASK_W);
+
+    const status = colorStatus(entry.plan_status);
+    const tokens = formatTokens(entry.output_tokens_approx);
+    const tokensStr = chalk.gray(tokens);
+
+    console.log(`  ${chalk.gray(time)} ${chalk.bold(agent)} ${task} ${status} ${tokensStr}`);
+
+    if (typeof entry.output_tokens_approx === 'number') totalTokens += entry.output_tokens_approx;
+    agentSet.add(entry.agent || 'unknown');
+  }
+
+  console.log('  ' + SEP);
+
+  // Footer summary
+  const totalStr = totalTokens > 0 ? `~${totalTokens >= 1000 ? (totalTokens / 1000).toFixed(1) + 'k' : totalTokens} tokens approx` : '';
+  console.log(
+    chalk.gray(
+      `  Total: ${entries.length} sessions | ${agentSet.size} agent${agentSet.size !== 1 ? 's' : ''}`
+      + (totalStr ? ` | ${totalStr}` : '')
+    )
+  );
+  console.log('');
+
+  // Tips
+  if (!args.today && !args.blocked && !args.agent) {
+    console.log(chalk.gray('  Flags: --today | --blocked | --agent <name> | --limit <n>\n'));
+  }
+}
+
+main().catch(err => {
+  console.error(chalk.red(`\n  Error: ${err.message}\n`));
+  process.exit(1);
+});