openhermes 4.9.2 → 4.11.2

package/harness/lib/composer/fragments/09-guardrails.md

@@ -0,0 +1,12 @@
+## Guardrails
+
+- Same skill 5+ times in one chain → STOP, write OptiRoute report to plan, surface
+- 5 subagent failures on same task → surface BLOCKER
+- Before routing: if next skill's required input is missing and cannot be discovered → surface
+- Confidence is evaluated once per session, not per routing hop — only re-evaluate when new user input arrives
+- User skills at `~/.agents/skills/` and `~/.config/opencode/skills/` load on demand via skill tool
+- Subagent sessions: give narrow objective, relevant context, boundaries, success criteria. One level deep only. Verify results after return.
+
+## Routing
+
+After every skill: read its `route:` frontmatter (pass / fail / blocker). Route immediately. Do not ask. Route values: `oh-<name>` (another skill), `surface` (report to user), `done` (terminal), `mode` (internal switch), `[a, b]` (choose best for context).

package/harness/lib/composer/index.ts

@@ -0,0 +1 @@
+export { compose, composeFragment, listFragments } from "./compose.ts"

package/harness/lib/hooks/builtins/confidence-gate-hook.ts

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// ConfidenceGateHook — RouteHook, priority=70, phase=NORMAL
+//
+// Before routing, check if confidence gate needs to pause.
+// Adjust route based on confidence level.
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, RouteHook } from "../types.ts";
+
+export interface ConfidenceGateState {
+  level: "HIGH" | "MEDIUM" | "LOW";
+  exchanges: number;
+  lastAction: string;
+}
+
+export const confidenceGateHook: RouteHook = {
+  metadata: {
+    name: "confidence-gate",
+    priority: 70,
+    phase: HookPhase.NORMAL,
+    dependencies: [],
+    errorHandling: "isolate",
+  },
+
+  async execute(context: HookContext, route: string) {
+    // Read confidence state from context if available
+    const confidenceLevel: string | undefined = context._confidenceLevel as
+      | string
+      | undefined;
+
+    if (!confidenceLevel) {
+      // No confidence gate info — pass through unchanged
+      return { result: HookResult.CONTINUE, modifiedRoute: route };
+    }
+
+    // Store the confidence assessment for routing decisions
+    const state: ConfidenceGateState = {
+      level: confidenceLevel as ConfidenceGateState["level"],
+      exchanges: (context._confidenceExchanges as number) ?? 0,
+      lastAction: "assessed",
+    };
+
+    // HIGH confidence: proceed without modification
+    if (state.level === "HIGH") {
+      return {
+        result: HookResult.CONTINUE,
+        modifiedRoute: route,
+      };
+    }
+
+    // MEDIUM confidence: echo if first pass, otherwise proceed
+    if (state.level === "MEDIUM" && state.exchanges === 0) {
+      return {
+        result: HookResult.INJECT,
+        modifiedRoute: `${route}?echo=confirm`,
+      };
+    }
+
+    // LOW confidence: pause if first pass, otherwise proceed
+    if (state.level === "LOW" && state.exchanges === 0) {
+      return {
+        result: HookResult.INJECT,
+        modifiedRoute: `${route}?question=pause`,
+      };
+    }
+
+    return { result: HookResult.CONTINUE, modifiedRoute: route };
+  },
+};

package/harness/lib/hooks/builtins/delegation-depth-hook.ts

@@ -0,0 +1,59 @@
+// ---------------------------------------------------------------------------
+// DelegationDepthHook — PreToolUse, priority=60, phase=NORMAL
+//
+// Loop guard — track sub-agent call depth.
+// If depth > 5, STOP and escalate.
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, PreToolUseHook } from "../types.ts";
+
+/** Module-level depth tracker — maps sessionId to current depth */
+const depthTrackers = new Map<string, number>();
+
+export function resetDepthTracker(): void {
+  depthTrackers.clear();
+}
+
+export function getDepth(sessionId: string): number {
+  return depthTrackers.get(sessionId) ?? 0;
+}
+
+export const delegationDepthHook: PreToolUseHook = {
+  metadata: {
+    name: "delegation-depth",
+    priority: 60,
+    phase: HookPhase.NORMAL,
+    dependencies: [],
+    errorHandling: "propagate",
+  },
+
+  async execute(context: HookContext) {
+    const sessionId = context.sessionId;
+
+    // Bump depth
+    const currentDepth = (depthTrackers.get(sessionId) ?? 0) + 1;
+    depthTrackers.set(sessionId, currentDepth);
+
+    // The configured limit (can be overridden via context)
+    const maxDepth = (context._maxDelegationDepth as number) ?? 5;
+
+    if (currentDepth >= maxDepth) {
+      return {
+        result: HookResult.STOP,
+        modifiedContext: {
+          _depthExceeded: true,
+          _depthError: `LOOP GUARD: Delegation depth exceeded (max ${maxDepth}). Surface to orchestrator with findings and stop delegating.`,
+          _delegationDepth: currentDepth,
+        },
+      };
+    }
+
+    return {
+      result: HookResult.CONTINUE,
+      modifiedContext: {
+        _delegationDepth: currentDepth,
+      },
+    };
+  },
+};

package/harness/lib/hooks/builtins/error-recovery-hook.ts

@@ -0,0 +1,107 @@
+// ---------------------------------------------------------------------------
+// ErrorRecoveryHook — PostToolUse, priority=50, phase=LATE
+//
+// After sub-agent call, check if output indicates error.
+// Use the RecoveryHandler to match patterns and inject recovery actions.
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, PostToolUseHook } from "../types.ts";
+import { RecoveryHandler } from "../../recovery/handler.ts";
+import type { ErrorContext } from "../../recovery/interfaces.ts";
+
+export const errorRecoveryHook: PostToolUseHook = {
+  metadata: {
+    name: "error-recovery",
+    priority: 50,
+    phase: HookPhase.LATE,
+    dependencies: [],
+    errorHandling: "isolate",
+  },
+
+  async execute(context: HookContext, output: string) {
+    // Check if the output looks like an error
+    const isErrorOutput = looksLikeError(output);
+    if (!isErrorOutput) {
+      return { result: HookResult.CONTINUE };
+    }
+
+    // Classify the error and get a recovery action
+    const handler = RecoveryHandler.getInstance();
+    const errorContext: ErrorContext = {
+      sessionId: context.sessionId,
+      error: new Error(output.slice(0, 500)), // Truncate for classification
+      attempt: (context._recoveryAttempt as number) ?? 0,
+      timestamp: Date.now(),
+      agent: context.agent,
+    };
+
+    const action = handler.handleError(errorContext);
+
+    // Build a recovery instruction based on the action
+    const recoveryInstruction = buildRecoveryInstruction(action);
+
+    return {
+      result: HookResult.INJECT,
+      modifiedOutput: output,
+      injectRecovery: recoveryInstruction,
+    };
+  },
+};
+
+/**
+ * Heuristic check: does the output look like an error?
+ * Looks for common error patterns in tool output.
+ */
+function looksLikeError(output: string): boolean {
+  if (!output || output.length === 0) return false;
+
+  const errorPatterns = [
+    /error/i,
+    /exception/i,
+    /failed/i,
+    /failure/i,
+    /unable to/i,
+    /could not/i,
+    /not found/i,
+    /ECONNREFUSED/i,
+    /ETIMEDOUT/i,
+    /rate.?limited/i,
+    /too many requests/i,
+    /context.?length/i,
+    /token.?limit/i,
+    /parse.?error/i,
+    /syntax.?error/i,
+    /timeout/i,
+    /execution.?timed.?out/i,
+  ];
+
+  // Check first 2000 chars to avoid false positives in long output
+  const head = output.slice(0, 2000);
+  return errorPatterns.some((p) => p.test(head));
+}
+
+/**
+ * Build a recovery instruction string from a RecoveryAction.
+ */
+function buildRecoveryInstruction(
+  action: { type: string; delay?: number; maxAttempts?: number; reason: string; modifyPrompt?: string },
+): string {
+  const parts: string[] = [
+    `[HOOK: Error Recovery]`,
+    `Action: ${action.type}`,
+    `Reason: ${action.reason}`,
+  ];
+
+  if (action.delay) {
+    parts.push(`Delay: ${action.delay}ms before retry`);
+  }
+  if (action.maxAttempts) {
+    parts.push(`Max attempts: ${action.maxAttempts}`);
+  }
+  if (action.modifyPrompt) {
+    parts.push(`Modification: ${action.modifyPrompt}`);
+  }
+
+  return parts.join("\n");
+}

package/harness/lib/hooks/builtins/memory-sync-hook.ts

@@ -0,0 +1,73 @@
+// ---------------------------------------------------------------------------
+// MemorySyncHook — PostToolUse, priority=40, phase=LATE
+//
+// After each step, sync memory entries to plan file.
+// Uses MemoryManager from harness/lib/memory/memory-manager.ts
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, PostToolUseHook } from "../types.ts";
+import { MemoryManager } from "../../memory/memory-manager.ts";
+import { PlanStore } from "../../memory/plan-store.ts";
+import { findLatestPlanFile } from "../../../../bootstrap.ts";
+import { MemoryLevel } from "../../memory/interfaces.ts";
+
+export const memorySyncHook: PostToolUseHook = {
+  metadata: {
+    name: "memory-sync",
+    priority: 40,
+    phase: HookPhase.LATE,
+    dependencies: [],
+    errorHandling: "isolate",
+  },
+
+  async execute(context: HookContext, output: string) {
+    // Sync memory entries to plan file
+    const planFile = findLatestPlanFile(context.directory);
+    if (!planFile) {
+      // No plan file to sync to — skip silently
+      return { result: HookResult.CONTINUE };
+    }
+
+    const mem = MemoryManager.getInstance();
+
+    // Extract findings from the session memory (TASK level)
+    const taskEntries = mem.getEntries(MemoryLevel.TASK);
+
+    // Sync important task entries as plan findings
+    for (const entry of taskEntries) {
+      if (entry.importance >= 0.6) {
+        try {
+          await PlanStore.addFinding(planFile, context.sessionId, {
+            description: entry.content,
+            severity: entry.importance >= 0.8 ? "warning" : "info",
+          });
+        } catch {
+          // Plan sync is best-effort — don't break execution
+        }
+      }
+    }
+
+    // Sync any decisions
+    const missionEntries = mem.getEntries(MemoryLevel.MISSION);
+    for (const entry of missionEntries) {
+      if (entry.metadata?.type === "decision" && entry.importance >= 0.7) {
+        try {
+          await PlanStore.addDecision(planFile, context.sessionId, {
+            description: entry.content,
+            rationale: (entry.metadata.rationale as string) ?? "Auto-synced decision",
+          });
+        } catch {
+          // Best-effort
+        }
+      }
+    }
+
+    return {
+      result: HookResult.CONTINUE,
+      modifiedContext: {
+        _memorySyncCount: taskEntries.filter((e) => e.importance >= 0.6).length,
+      },
+    };
+  },
+};

package/harness/lib/hooks/builtins/plan-check-hook.ts

@@ -0,0 +1,43 @@
+// ---------------------------------------------------------------------------
+// PlanCheckHook — PreToolUse, priority=90, phase=EARLY
+//
+// Before any sub-agent call, verify plan file exists at the expected path.
+// If missing, inject "create plan first" instruction.
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, PreToolUseHook } from "../types.ts";
+import { findLatestPlanFile } from "../../../../bootstrap.ts";
+
+export const planCheckHook: PreToolUseHook = {
+  metadata: {
+    name: "plan-check",
+    priority: 90,
+    phase: HookPhase.EARLY,
+    dependencies: [],
+    errorHandling: "propagate",
+  },
+
+  async execute(context: HookContext) {
+    const planFile = findLatestPlanFile(context.directory);
+
+    if (!planFile) {
+      return {
+        result: HookResult.INJECT,
+        modifiedContext: {
+          _planCheck: "missing",
+          _planCheckInstruction:
+            "No plan file found. Create a plan first before proceeding with any sub-agent tasks.",
+        },
+      };
+    }
+
+    return {
+      result: HookResult.CONTINUE,
+      modifiedContext: {
+        _planCheck: "found",
+        _planFilePath: planFile,
+      },
+    };
+  },
+};

package/harness/lib/hooks/builtins/route-tracking-hook.ts

@@ -0,0 +1,147 @@
+// ---------------------------------------------------------------------------
+// RouteTrackingHook — RouteHook, priority=55, phase=LATE
+//
+// Loop guard — mechanically enforce two limits:
+// 1. Same skill visited 5+ times in one chain
+// 2. 8+ consecutive unproductive hops
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, RouteHook } from "../types.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface HopRecord {
+  skill: string;
+  timestamp: number;
+  producedArtifact: boolean;
+}
+
+export interface RouteTrackingConfig {
+  maxSkillRepeats: number;
+  maxUnproductiveHops: number;
+  artifactCheck: (route: string) => boolean | Promise<boolean>;
+}
+
+interface RouteTrackingState {
+  hops: HopRecord[];
+  skillCounts: Map<string, number>;
+  unproductiveCount: number;
+}
+
+// ---------------------------------------------------------------------------
+// Module-level state
+// ---------------------------------------------------------------------------
+
+const sessionStates = new Map<string, RouteTrackingState>();
+
+export function resetRouteTracker(sessionId?: string): void {
+  if (sessionId) {
+    sessionStates.delete(sessionId);
+  } else {
+    sessionStates.clear();
+  }
+}
+
+export function getHopHistory(sessionId: string): HopRecord[] {
+  return sessionStates.get(sessionId)?.hops ?? [];
+}
+
+// ---------------------------------------------------------------------------
+// Default artifact check (conservative — assumes unproductive)
+// ---------------------------------------------------------------------------
+
+const defaultArtifactCheck: (route: string) => boolean = () => false;
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+export const routeTrackingHook: RouteHook = {
+  metadata: {
+    name: "route-tracking",
+    priority: 55,
+    phase: HookPhase.LATE,
+    dependencies: [],
+    errorHandling: "propagate",
+  },
+
+  async execute(context: HookContext, route: string) {
+    // Skip terminal routes — they don't count as routing hops
+    const terminalRoutes = new Set(["surface", "done", "oh-handoff"]);
+    if (terminalRoutes.has(route)) {
+      return { result: HookResult.CONTINUE, modifiedRoute: route };
+    }
+
+    const sessionId = context.sessionId;
+
+    // Get or create state for this session
+    let state = sessionStates.get(sessionId);
+    if (!state) {
+      state = {
+        hops: [],
+        skillCounts: new Map<string, number>(),
+        unproductiveCount: 0,
+      };
+      sessionStates.set(sessionId, state);
+    }
+
+    // Read config from context (or use defaults)
+    // Support both `_routeTrackingConfig` and `hooks.route_tracking.*` conventions
+    const config =
+      (context._routeTrackingConfig ?? {}) as RouteTrackingConfig;
+    const maxSkillRepeats = config.maxSkillRepeats ?? 5;
+    const maxUnproductiveHops = config.maxUnproductiveHops ?? 8;
+    const artifactCheck = config.artifactCheck ?? defaultArtifactCheck;
+
+    // Record the hop
+    const producedArtifact = await artifactCheck(route);
+    const hop: HopRecord = {
+      skill: route,
+      timestamp: Date.now(),
+      producedArtifact,
+    };
+    state.hops.push(hop);
+
+    // Update skill count
+    const currentSkillCount = (state.skillCounts.get(route) ?? 0) + 1;
+    state.skillCounts.set(route, currentSkillCount);
+
+    // Update unproductive counter (resets on any productive hop)
+    if (producedArtifact) {
+      state.unproductiveCount = 0;
+    } else {
+      state.unproductiveCount += 1;
+    }
+
+    // Check 1: Same skill repeated too many times
+    if (currentSkillCount >= maxSkillRepeats) {
+      context._optiRoute = {
+        reason: `Same skill "${route}" visited ${currentSkillCount} times (max ${maxSkillRepeats})`,
+        chain: [...state.hops],
+        skillCounts: Object.fromEntries(state.skillCounts),
+        unproductiveCount: state.unproductiveCount,
+        maxSkillRepeats,
+        maxUnproductiveHops,
+      };
+      return { result: HookResult.STOP };
+    }
+
+    // Check 2: Too many consecutive unproductive hops
+    if (state.unproductiveCount >= maxUnproductiveHops) {
+      context._optiRoute = {
+        reason: `${state.unproductiveCount} consecutive unproductive hops (max ${maxUnproductiveHops})`,
+        chain: [...state.hops],
+        skillCounts: Object.fromEntries(state.skillCounts),
+        unproductiveCount: state.unproductiveCount,
+        maxSkillRepeats,
+        maxUnproductiveHops,
+      };
+      return { result: HookResult.STOP };
+    }
+
+    return { result: HookResult.CONTINUE, modifiedRoute: route };
+  },
+};

package/harness/lib/hooks/builtins/sanity-check-hook.ts

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// SanityCheckHook — PostToolUse, priority=30, phase=LATE
+//
+// After each tool invocation, check the output for LLM degeneration patterns
+// (repetition, low diversity, gibberish, etc.). Track consecutive anomalies
+// per session. If 2+ consecutive anomalies detected, inject a recovery
+// instruction to compact/refresh context before it cascades.
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, PostToolUseHook } from "../types.ts";
+import { checkOutputSanity } from "../../sanity/checker.ts";
+import { AnomalyTracker } from "../../sanity/anomaly-tracker.ts";
+
+export const sanityCheckHook: PostToolUseHook = {
+  metadata: {
+    name: "sanity-check",
+    priority: 30,
+    phase: HookPhase.LATE,
+    dependencies: [],
+    errorHandling: "isolate",
+  },
+
+  async execute(context: HookContext, output: string) {
+    const sessionId = context.sessionId;
+
+    // Run the sanity checker on the output
+    const result = checkOutputSanity(output);
+
+    // Record the result in the anomaly tracker
+    const tracker = AnomalyTracker.getInstance();
+    const tracking = tracker.record(sessionId, result);
+
+    if (result.isHealthy) {
+      // Output is healthy — no action needed
+      return { result: HookResult.CONTINUE };
+    }
+
+    // Unhealthy output detected
+    if (tracking.shouldEscalate) {
+      // Escalation threshold reached — inject recovery instruction
+      return {
+        result: HookResult.INJECT,
+        modifiedOutput: output,
+        injectRecovery: tracking.recoveryMessage ?? "recovery: compact context",
+      };
+    }
+
+    // First anomaly (below threshold) — let it pass with a warning
+    return { result: HookResult.CONTINUE };
+  },
+};

package/harness/lib/hooks/builtins/shell-detect-hook.ts

@@ -0,0 +1,96 @@
+// ---------------------------------------------------------------------------
+// ShellDetectHook — PreToolUse, priority=80, phase=EARLY
+//
+// Before sub-agent calls that need CLI, inject SHELL.md preamble.
+// Detect platform, add appropriate shell context.
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, PreToolUseHook } from "../types.ts";
+import { getHarnessDir } from "../../../../lib/harness-resolver.ts";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export const shellDetectHook: PreToolUseHook = {
+  metadata: {
+    name: "shell-detect",
+    priority: 80,
+    phase: HookPhase.EARLY,
+    dependencies: [],
+    errorHandling: "isolate",
+  },
+
+  async execute(context: HookContext) {
+    const platform = os.platform();
+    const isWindows = platform === "win32";
+
+    // Detect shell type
+    let shellType = "unknown";
+    if (isWindows) {
+      // On Windows: detect PowerShell, CMD, or Git Bash
+      const comSpec = process.env.COMSPEC ?? "";
+      if (process.env.PSModulePath || process.env.PSExecutionPolicy) {
+        shellType = "powershell";
+      } else if (comSpec.toLowerCase().includes("cmd")) {
+        shellType = "cmd";
+      } else {
+        // Could be Git Bash
+        shellType = process.env.BASH ? "bash" : "powershell";
+      }
+    } else {
+      shellType = "bash";
+    }
+
+    // Try to load SHELL.md
+    let shellPreamble = "";
+    try {
+      const shellDocPath = path.join(getHarnessDir(), "instructions", "SHELL.md");
+      await fs.promises.access(shellDocPath);
+      shellPreamble = (await fs.promises.readFile(shellDocPath, "utf8")).trim();
+    } catch {
+      // If SHELL.md can't be read, provide minimal preamble
+      shellPreamble = "";
+    }
+
+    return {
+      result: HookResult.CONTINUE,
+      modifiedContext: {
+        _shellPlatform: platform,
+        _shellType: shellType,
+        _shellPreamble: shellPreamble || getDefaultPreamble(shellType, platform),
+      },
+    };
+  },
+};
+
+function getDefaultPreamble(shellType: string, _platform: string): string {
+  if (shellType === "powershell") {
+    return [
+      "## Shell Environment",
+      "",
+      "Detected: PowerShell on Windows",
+      "- File ops, scoop installs, ps1 scripts, env vars → PowerShell",
+      "- git, bun, npm, node → any shell (all work)",
+      "- rm -rf, make, unix scripts → Git Bash",
+      "",
+    ].join("\n");
+  }
+  if (shellType === "cmd") {
+    return [
+      "## Shell Environment",
+      "",
+      "Detected: CMD on Windows",
+      "- .bat/.cmd scripts → CMD",
+      "- git, bun, npm, node → any shell",
+      "",
+    ].join("\n");
+  }
+  return [
+    "## Shell Environment",
+    "",
+    `Detected: ${shellType}`,
+    "- Standard POSIX shell commands available",
+    "",
+  ].join("\n");
+}