openhermes 4.11.2 → 4.13.0

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

@@ -0,0 +1,99 @@
+import path from "node:path";
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, PostToolUseHook } from "../types.ts";
+import { readSkillFrontmatter, resolveRoute } from "../../routing/index.ts";
+import type { RouteEvidence } from "../../routing/index.ts";
+import { ROUTE_GUIDANCE_PREFIX } from "../../routing/index.ts";
+import {
+  ROUTE_ACTIONS,
+  ROUTE_OUTCOMES,
+  ROUTE_VERIFICATIONS,
+  ROUTE_WORK_TYPES,
+} from "../../routing/types.ts";
+
+const ROUTE_EVIDENCE_PREFIX = "ROUTE_EVIDENCE:";
+
+function isRouteOutcome(value: unknown): value is RouteEvidence["outcome"] {
+  return typeof value === "string" && ROUTE_OUTCOMES.includes(value as RouteEvidence["outcome"]);
+}
+
+function isRouteVerification(value: unknown): value is NonNullable<RouteEvidence["verification"]> {
+  return typeof value === "string" && ROUTE_VERIFICATIONS.includes(value as NonNullable<RouteEvidence["verification"]>);
+}
+
+function isRouteAction(value: unknown): value is NonNullable<RouteEvidence["action"]> {
+  return typeof value === "string" && ROUTE_ACTIONS.includes(value as NonNullable<RouteEvidence["action"]>);
+}
+
+function isRouteWork(value: unknown): value is NonNullable<RouteEvidence["work"]> {
+  return typeof value === "string" && ROUTE_WORK_TYPES.includes(value as NonNullable<RouteEvidence["work"]>);
+}
+
+function parseRouteEvidence(output: string): RouteEvidence | null {
+  const evidenceLine = output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line.startsWith(ROUTE_EVIDENCE_PREFIX));
+
+  if (!evidenceLine) return null;
+
+  const raw = evidenceLine.slice(ROUTE_EVIDENCE_PREFIX.length).trim();
+  if (!raw) return null;
+
+  try {
+    const parsed = JSON.parse(raw) as Partial<RouteEvidence>;
+    if (!isRouteOutcome(parsed.outcome)) return null;
+    if (parsed.verification !== undefined && !isRouteVerification(parsed.verification)) return null;
+    if (parsed.action !== undefined && !isRouteAction(parsed.action)) return null;
+    if (parsed.work !== undefined && !isRouteWork(parsed.work)) return null;
+    if (parsed.target !== undefined && typeof parsed.target !== "string") return null;
+    if (parsed.reason !== undefined && typeof parsed.reason !== "string") return null;
+
+    return {
+      outcome: parsed.outcome,
+      ...(parsed.verification ? { verification: parsed.verification } : {}),
+      ...(parsed.action ? { action: parsed.action } : {}),
+      ...(parsed.work ? { work: parsed.work } : {}),
+      ...(parsed.target ? { target: parsed.target } : {}),
+      ...(parsed.reason ? { reason: parsed.reason } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export const dynamicRouteHook: PostToolUseHook = {
+  metadata: {
+    name: "dynamic-route",
+    priority: 20,
+    phase: HookPhase.LATE,
+    dependencies: [],
+    errorHandling: "isolate",
+  },
+
+  async execute(context: HookContext, output: string) {
+    const evidence = parseRouteEvidence(output);
+    const skillsDir = typeof context._routingSkillsDir === "string" ? context._routingSkillsDir : undefined;
+
+    if (!evidence || !skillsDir || !context.agent) {
+      return { result: HookResult.CONTINUE };
+    }
+
+    const skillFilePath = path.join(skillsDir, context.agent, "SKILL.md");
+    const frontmatter = readSkillFrontmatter(skillFilePath);
+    if (!frontmatter) {
+      return { result: HookResult.CONTINUE };
+    }
+
+    const resolution = resolveRoute(frontmatter.route, evidence);
+    const guidance = `${ROUTE_GUIDANCE_PREFIX} ${JSON.stringify(resolution)}`;
+    const modifiedOutput = output.includes(ROUTE_GUIDANCE_PREFIX)
+      ? output
+      : `${output.trimEnd()}\n${guidance}`.trim();
+
+    return {
+      result: HookResult.INJECT,
+      modifiedOutput,
+    };
+  },
+};

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

@@ -0,0 +1,24 @@
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, RouteHook } from "../types.ts";
+
+export const nextRouteHook: RouteHook = {
+  metadata: {
+    name: "next-route",
+    priority: 90,
+    phase: HookPhase.EARLY,
+    dependencies: [],
+    errorHandling: "isolate",
+  },
+
+  async execute(context: HookContext, route: string) {
+    const nextRoute = context._nextRoute?.selected;
+    if (!nextRoute || nextRoute === route) {
+      return { result: HookResult.CONTINUE, modifiedRoute: route };
+    }
+
+    return {
+      result: HookResult.CONTINUE,
+      modifiedRoute: nextRoute,
+    };
+  },
+};

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

@@ -7,7 +7,7 @@
 
 import { HookPhase, HookResult } from "../types.ts";
 import type { HookContext, PreToolUseHook } from "../types.ts";
-import { findLatestPlanFile } from "../../../../bootstrap.ts";
+import { resolvePlanAccess } from "../../plans/plan-location.ts";
 
 export const planCheckHook: PreToolUseHook = {
   metadata: {
@@ -19,7 +19,7 @@ export const planCheckHook: PreToolUseHook = {
   },
 
   async execute(context: HookContext) {
-    const planFile = findLatestPlanFile(context.directory);
+    const planFile = resolvePlanAccess(context.directory)?.path ?? null;
 
     if (!planFile) {
       return {

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

@@ -2,12 +2,17 @@
 // 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
+// 1. Same skill visited N+ times in one chain (default 5)
+// 2. N+ consecutive unproductive hops (default 8)
+//
+// Config from _guardConfig (centralized) with fallback to _routeTrackingConfig
+// for backward compatibility. Progressive warning at thresholds before hard stop.
 // ---------------------------------------------------------------------------
 
 import { HookPhase, HookResult } from "../types.ts";
 import type { HookContext, RouteHook } from "../types.ts";
+import type { GuardConfig, GuardProgression } from "../../guards/guard-config.ts";
+import { checkGuardProgression, DEFAULT_GUARD_CONFIG } from "../../guards/guard-config.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -55,6 +60,53 @@ export function getHopHistory(sessionId: string): HopRecord[] {
 
 const defaultArtifactCheck: (route: string) => boolean = () => false;
 
+// ---------------------------------------------------------------------------
+// Resolve max values from guard config with fallbacks
+// ---------------------------------------------------------------------------
+
+function resolveMaxValues(context: HookContext): {
+  maxSkillRepeats: number;
+  maxUnproductiveHops: number;
+  artifactCheck: (route: string) => boolean | Promise<boolean>;
+} {
+  // Primary: _guardConfig (centralized)
+  const gc: GuardConfig = context._guardConfig ?? DEFAULT_GUARD_CONFIG;
+  const maxSkillRepeats = gc.maxSkillRepeats;
+  const maxUnproductiveHops = gc.maxUnproductiveHops;
+
+  // Backward compat: _routeTrackingConfig overrides if present
+  const legacy = context._routeTrackingConfig as Partial<RouteTrackingConfig> | undefined;
+  const artifactCheck = legacy?.artifactCheck ?? defaultArtifactCheck;
+  const legacySkillRepeats = legacy?.maxSkillRepeats;
+  const legacyUnproductiveHops = legacy?.maxUnproductiveHops;
+
+  return {
+    maxSkillRepeats: legacySkillRepeats ?? maxSkillRepeats,
+    maxUnproductiveHops: legacyUnproductiveHops ?? maxUnproductiveHops,
+    artifactCheck,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Build optiRoute report helper
+// ---------------------------------------------------------------------------
+
+function buildOptiRouteReport(
+  state: RouteTrackingState,
+  reason: string,
+  maxSkillRepeats: number,
+  maxUnproductiveHops: number,
+) {
+  return {
+    reason,
+    chain: [...state.hops],
+    skillCounts: Object.fromEntries(state.skillCounts),
+    unproductiveCount: state.unproductiveCount,
+    maxSkillRepeats,
+    maxUnproductiveHops,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Hook
 // ---------------------------------------------------------------------------
@@ -88,13 +140,9 @@ export const routeTrackingHook: RouteHook = {
       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;
+    // Resolve config values
+    const { maxSkillRepeats, maxUnproductiveHops, artifactCheck } = resolveMaxValues(context);
+    const gc: GuardConfig = context._guardConfig ?? DEFAULT_GUARD_CONFIG;
 
     // Record the hop
     const producedArtifact = await artifactCheck(route);
@@ -116,29 +164,35 @@ export const routeTrackingHook: RouteHook = {
       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,
+    // Check 1: Same skill repeated too many times — with progressive warning
+    let progression = checkGuardProgression(currentSkillCount, maxSkillRepeats, gc);
+    if (progression.level === "warn" || progression.level === "escalate") {
+      // Progressive warning — annotate context but don't stop
+      context._guardProgression = progression;
+    }
+    if (progression.level === "stop") {
+      context._optiRoute = buildOptiRouteReport(
+        state,
+        `Same skill "${route}" visited ${currentSkillCount} times (max ${maxSkillRepeats})`,
         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,
+    // Check 2: Too many consecutive unproductive hops — with progressive warning
+    progression = checkGuardProgression(state.unproductiveCount, maxUnproductiveHops, gc);
+    if (progression.level === "warn" || progression.level === "escalate") {
+      // Progressive warning — annotate context but don't stop
+      context._guardProgression = progression;
+    }
+    if (progression.level === "stop") {
+      context._optiRoute = buildOptiRouteReport(
+        state,
+        `${state.unproductiveCount} consecutive unproductive hops (max ${maxUnproductiveHops})`,
         maxSkillRepeats,
         maxUnproductiveHops,
-      };
+      );
       return { result: HookResult.STOP };
     }