openhermes 4.11.2 → 4.13.0

package/harness/lib/hooks/types.ts

@@ -1,71 +1,116 @@
-// ---------------------------------------------------------------------------
-// Hook System — type definitions
-// ---------------------------------------------------------------------------
-
-export enum HookPhase {
-  EARLY = 0,
-  NORMAL = 1,
-  LATE = 2,
-}
-
-export interface HookContext {
-  sessionId: string;
-  agent: string;
-  directory: string;
-  sessions: Map<string, unknown>;
-  [key: string]: unknown;
-}
-
-export interface HookMetadata {
-  name: string;
-  priority: number;       // 0-100, higher = earlier within phase
-  phase: HookPhase;
-  dependencies: string[]; // hook names this depends on
-  errorHandling: "propagate" | "isolate" | "retry";
-}
-
-export enum HookResult {
-  CONTINUE = "continue",
-  STOP = "stop",
-  INJECT = "inject",
-}
-
-export interface PreToolUseHook {
-  metadata: HookMetadata;
-  execute(
-    context: HookContext,
-  ): Promise<{ result: HookResult; modifiedContext?: Partial<HookContext> }>;
-}
-
-export interface PostToolUseHook {
-  metadata: HookMetadata;
-  execute(
-    context: HookContext,
-    output: string,
-  ): Promise<{
-    result: HookResult;
-    modifiedOutput?: string;
-    injectRecovery?: string;
-  }>;
-}
-
-export interface RouteHook {
-  metadata: HookMetadata;
-  execute(
-    context: HookContext,
-    route: string,
-  ): Promise<{ result: HookResult; modifiedRoute?: string }>;
-}
-
-export interface SessionHook {
-  metadata: HookMetadata;
-  onSessionStart(context: HookContext): Promise<void>;
-  onSessionEnd(context: HookContext): Promise<void>;
-}
-
-// Union type for any hook in the registry
-export type AnyHook =
-  | PreToolUseHook
-  | PostToolUseHook
-  | RouteHook
-  | SessionHook;
+// ---------------------------------------------------------------------------
+// Hook System — type definitions
+// ---------------------------------------------------------------------------
+
+export enum HookPhase {
+  EARLY = 0,
+  NORMAL = 1,
+  LATE = 2,
+}
+
+export interface HookContextBase {
+  sessionId: string;
+  agent: string;
+  directory: string;
+  sessions: Map<string, unknown>;
+}
+
+export interface HookContextExtras {
+  _planCheck?: "missing" | "found";
+  _planFilePath?: string;
+  _planCheckInstruction?: string;
+
+  _shellPlatform?: string;
+  _shellType?: string;
+  _shellPreamble?: string;
+
+  _delegationDepth?: number;
+  _depthExceeded?: boolean;
+  _depthError?: string;
+
+  _confidenceLevel?: "HIGH" | "MEDIUM" | "LOW" | string;
+  _confidenceExchanges?: number;
+
+  // Guard configuration (centralized — replaces _routeTrackingConfig and _maxDelegationDepth)
+  _guardConfig?: import("../guards/guard-config.ts").GuardConfig;
+  _guardProgression?: import("../guards/guard-config.ts").GuardProgression;
+
+  // Subagent failure tracking
+  _subagentFailures?: number;
+  _subagentFailureThreshold?: number;
+  _optiRoute?: {
+    reason: string;
+    chain: Array<{
+      skill: string;
+      timestamp: number;
+      producedArtifact: boolean;
+    }>;
+    skillCounts: Record<string, number>;
+    unproductiveCount: number;
+    maxSkillRepeats: number;
+    maxUnproductiveHops: number;
+  };
+
+  _routingSkillsDir?: string;
+  _nextRoute?: import("../routing/index.ts").RuntimeRouteDecision;
+
+  [key: string]: unknown;
+}
+
+export type HookContext = HookContextBase & HookContextExtras;
+
+export type HookContextPatch = Partial<HookContextBase> &
+  Partial<HookContextExtras>;
+
+export interface HookMetadata {
+  name: string;
+  priority: number;       // 0-100, higher = earlier within phase
+  phase: HookPhase;
+  dependencies: string[]; // hook names this depends on
+  errorHandling: "propagate" | "isolate" | "retry";
+}
+
+export enum HookResult {
+  CONTINUE = "continue",
+  STOP = "stop",
+  INJECT = "inject",
+}
+
+export interface PreToolUseHook {
+  metadata: HookMetadata;
+  execute(
+    context: HookContext,
+  ): Promise<{ result: HookResult; modifiedContext?: HookContextPatch }>;
+}
+
+export interface PostToolUseHook {
+  metadata: HookMetadata;
+  execute(
+    context: HookContext,
+    output: string,
+  ): Promise<{
+    result: HookResult;
+    modifiedOutput?: string;
+  }>;
+}
+
+export interface RouteHook {
+  metadata: HookMetadata;
+  execute(
+    context: HookContext,
+    route: string,
+  ): Promise<{ result: HookResult; modifiedRoute?: string }>;
+}
+
+export interface SessionHook {
+  metadata: HookMetadata;
+  onSessionStart(context: HookContext): Promise<void>;
+  onSessionEnd(context: HookContext): Promise<void>;
+}
+
+// Union type for any hook in the registry
+export type AnyHook =
+  | PreToolUseHook
+  | PostToolUseHook
+  | RouteHook
+  | SessionHook;

package/harness/lib/plans/plan-location.ts

@@ -0,0 +1,134 @@
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+let _planStorageOverride: string | undefined
+
+export interface PlanAccess {
+  path: string
+  status: string | null
+  objective: string | null
+  summary: string | null
+}
+
+export function setPlanStorageDirForTest(dir: string | undefined): void {
+  _planStorageOverride = dir
+}
+
+export function planStorageDir(): string {
+  return _planStorageOverride ?? path.join(os.homedir(), ".local", "share", "openhermes", "plans")
+}
+
+function getProjectName(projectDir: string): string {
+  return path.basename(projectDir)
+}
+
+function ensureDir(dir: string): void {
+  try {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true })
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    console.error(`[openhermes] Failed to create directory ${dir}: ${msg}`)
+  }
+}
+
+function readPlanAccess(filePath: string): PlanAccess | null {
+  if (!fs.existsSync(filePath)) return null
+  const source = fs.readFileSync(filePath, "utf8")
+  const status = source.match(/^Status:\s*(.+)$/m)?.[1]?.trim() ?? null
+  const objective = source.match(/^Objective:\s*(.+)$/m)?.[1]?.trim() ?? null
+  if (!status && !objective) return null
+  const parts = [status ? `status=${status}` : null, objective ? `objective=${objective}` : null].filter(Boolean)
+  return {
+    path: filePath,
+    status,
+    objective,
+    summary: `Active plan: ${parts.join(" | ")}`,
+  }
+}
+
+export function resolvePlanAccess(projectDir: string): PlanAccess | null {
+  const latest = findLatestPlanFile(projectDir)
+  if (!latest) return null
+  return readPlanAccess(latest)
+}
+
+export function findLatestPlanFile(projectDir: string): string | null {
+  const projectName = getProjectName(projectDir)
+  const storage = planStorageDir()
+  const projectDirPath = path.join(storage, projectName)
+  if (!fs.existsSync(projectDirPath)) return null
+  let latest: string | null = null
+  let highest = -1
+  try {
+    for (const entry of fs.readdirSync(projectDirPath)) {
+      const m = entry.match(/^plan-(\d{3})\.md$/)
+      if (m) {
+        const n = parseInt(m[1], 10)
+        if (n > highest) {
+          highest = n
+          latest = path.join(projectDirPath, entry)
+        }
+      }
+    }
+  } catch {
+    return null
+  }
+  return latest
+}
+
+export function ensurePlanFile(projectDir: string): string {
+  const access = resolvePlanAccess(projectDir)
+  if (access?.status === "active" || access?.status === "in-progress") {
+    return access.path
+  }
+
+  const projectName = getProjectName(projectDir)
+  const storage = planStorageDir()
+  const projectDirPath = path.join(storage, projectName)
+  ensureDir(projectDirPath)
+
+  const latest = access?.path ?? findLatestPlanFile(projectDir)
+  let nextSeq = 1
+  if (latest) {
+    const m = path.basename(latest).match(/^plan-(\d{3})\.md$/)
+    if (m) nextSeq = parseInt(m[1], 10) + 1
+  }
+
+  const seq = String(nextSeq).padStart(3, "0")
+  const planId = `${projectName}/plan-${seq}.md`
+  const planPath = path.join(projectDirPath, `plan-${seq}.md`)
+  const now = new Date().toISOString().replace("T", " ").slice(0, 16)
+
+  const content = [
+    `# PLAN: ${projectName}`,
+    "",
+    `Plan ID: ${planId}`,
+    `Project: ${projectName}`,
+    `Status: active`,
+    `Created: ${now}`,
+    `Updated: ${now}`,
+    `Project Path: ${projectDir}`,
+    `Plan Path: ${planPath}`,
+    `Objective: (pending classification)`,
+    "",
+    "## Tasks",
+    "",
+    "- [ ] (discoverable — pending classification)",
+    "",
+  ].join("\n")
+
+  try {
+    fs.writeFileSync(planPath, content, "utf8")
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    console.error(`[openhermes] Failed to write plan file ${planPath}: ${msg}`)
+  }
+  return planPath
+}
+
+export function readPlanSummary(projectDir: string): string | null {
+  return resolvePlanAccess(projectDir)?.summary ?? null
+}

package/harness/lib/routing/index.ts

@@ -0,0 +1,21 @@
+export { extractFrontmatter, parseSkillFrontmatter, readSkillFrontmatter, emptySkillRoutes } from "./skill-frontmatter.ts";
+export { resolveRoute } from "./route-resolver.ts";
+export {
+  clearRuntimeRouteDecision,
+  consumeRouteGuidance,
+  extractRouteGuidance,
+  extractRuntimeRouteDecision,
+  getRuntimeRouteDecision,
+  NEXT_ROUTE_PREFIX,
+  rememberRuntimeRouteDecision,
+  ROUTE_GUIDANCE_PREFIX,
+} from "./route-guidance.ts";
+export { ROUTE_OUTCOMES } from "./types.ts";
+export type {
+  RouteEvidence,
+  RouteOutcome,
+  RouteResolution,
+  RuntimeRouteDecision,
+  SkillRouteMap,
+  SkillRoutingFrontmatter,
+} from "./types.ts";

package/harness/lib/routing/route-guidance.ts

@@ -0,0 +1,147 @@
+import {
+  ROUTE_ACTIONS,
+  ROUTE_OUTCOMES,
+  ROUTE_VERIFICATIONS,
+  ROUTE_WORK_TYPES,
+} from "./types.ts";
+import type {
+  RouteAction,
+  RouteOutcome,
+  RouteResolution,
+  RouteVerification,
+  RouteWork,
+  RuntimeRouteDecision,
+} from "./types.ts";
+
+export const ROUTE_GUIDANCE_PREFIX = "ROUTE_GUIDANCE:";
+export const NEXT_ROUTE_PREFIX = "NEXT_ROUTE:";
+
+interface ConsumedRouteGuidance {
+  output: string;
+  selected: string | null;
+}
+
+const runtimeRouteState = new Map<string, RuntimeRouteDecision>();
+
+function isRouteOutcome(value: unknown): value is RouteOutcome {
+  return typeof value === "string" && ROUTE_OUTCOMES.includes(value as RouteOutcome);
+}
+
+function isRouteVerification(value: unknown): value is RouteVerification {
+  return typeof value === "string" && ROUTE_VERIFICATIONS.includes(value as RouteVerification);
+}
+
+function isRouteAction(value: unknown): value is RouteAction {
+  return typeof value === "string" && ROUTE_ACTIONS.includes(value as RouteAction);
+}
+
+function isRouteWork(value: unknown): value is RouteWork {
+  return typeof value === "string" && ROUTE_WORK_TYPES.includes(value as RouteWork);
+}
+
+export function extractRouteGuidance(output: string): RouteResolution | null {
+  const guidanceLine = output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line.startsWith(ROUTE_GUIDANCE_PREFIX));
+
+  if (!guidanceLine) return null;
+
+  const raw = guidanceLine.slice(ROUTE_GUIDANCE_PREFIX.length).trim();
+  if (!raw) return null;
+
+  try {
+    const parsed = JSON.parse(raw) as Partial<RouteResolution>;
+    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 (!Array.isArray(parsed.candidates) || !parsed.candidates.every((candidate) => typeof candidate === "string")) {
+      return null;
+    }
+    if (parsed.selected !== null && parsed.selected !== undefined && typeof parsed.selected !== "string") {
+      return null;
+    }
+    if (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 } : {}),
+      candidates: parsed.candidates,
+      selected: parsed.selected ?? null,
+      reason: parsed.reason,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function consumeRouteGuidance(output: string): ConsumedRouteGuidance {
+  const guidance = extractRouteGuidance(output);
+  if (!guidance?.selected || output.includes(NEXT_ROUTE_PREFIX)) {
+    return { output, selected: guidance?.selected ?? null };
+  }
+
+  return {
+    output: `${output.trimEnd()}\n${NEXT_ROUTE_PREFIX} ${guidance.selected}`,
+    selected: guidance.selected,
+  };
+}
+
+function extractExplicitNextRoute(output: string): string | null {
+  const routeLine = output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line.startsWith(NEXT_ROUTE_PREFIX));
+
+  if (!routeLine) return null;
+
+  const raw = routeLine.slice(NEXT_ROUTE_PREFIX.length).trim();
+  if (!raw || /\s/.test(raw)) return null;
+  return raw;
+}
+
+export function extractRuntimeRouteDecision(output: string): RuntimeRouteDecision | null {
+  const explicitNextRoute = extractExplicitNextRoute(output);
+  if (explicitNextRoute) {
+    return {
+      selected: explicitNextRoute,
+      source: "next_route",
+    };
+  }
+
+  const guidance = extractRouteGuidance(output);
+  if (!guidance?.selected) return null;
+
+  return {
+    selected: guidance.selected,
+    source: "route_guidance",
+    outcome: guidance.outcome,
+    verification: guidance.verification,
+    action: guidance.action,
+    work: guidance.work,
+    candidates: guidance.candidates,
+    reason: guidance.reason,
+  };
+}
+
+export function rememberRuntimeRouteDecision(sessionId: string, output: string): RuntimeRouteDecision | null {
+  const decision = extractRuntimeRouteDecision(output);
+  if (!decision) {
+    runtimeRouteState.delete(sessionId);
+    return null;
+  }
+
+  runtimeRouteState.set(sessionId, decision);
+  return decision;
+}
+
+export function getRuntimeRouteDecision(sessionId: string): RuntimeRouteDecision | null {
+  return runtimeRouteState.get(sessionId) ?? null;
+}
+
+export function clearRuntimeRouteDecision(sessionId: string): void {
+  runtimeRouteState.delete(sessionId);
+}

package/harness/lib/routing/route-resolver.ts

@@ -0,0 +1,58 @@
+import type { RouteEvidence, RouteResolution, SkillRouteMap } from "./types.ts";
+
+function findCandidate(candidates: string[], fragment: string): string | null {
+  return candidates.find((candidate) => candidate.includes(fragment)) ?? null;
+}
+
+function buildResolution(evidence: RouteEvidence, candidates: string[], selected: string | null, reason: string): RouteResolution {
+  return {
+    outcome: evidence.outcome,
+    ...(evidence.verification ? { verification: evidence.verification } : {}),
+    ...(evidence.action ? { action: evidence.action } : {}),
+    ...(evidence.work ? { work: evidence.work } : {}),
+    candidates,
+    selected,
+    reason,
+  };
+}
+
+export function resolveRoute(routeMap: SkillRouteMap, evidence: RouteEvidence): RouteResolution {
+  const candidates = [...routeMap[evidence.outcome]];
+  if (candidates.length === 0) {
+    return buildResolution(evidence, candidates, null, `No route candidates declared for outcome \"${evidence.outcome}\".`);
+  }
+
+  if (evidence.target && candidates.includes(evidence.target)) {
+    return buildResolution(evidence, candidates, evidence.target, `Selected \"${evidence.target}\" from output evidence.`);
+  }
+
+  if (evidence.action === "fixable" || evidence.work === "implement") {
+    const builderCandidate = findCandidate(candidates, "builder");
+    if (builderCandidate) {
+      return buildResolution(evidence, candidates, builderCandidate, `Selected \"${builderCandidate}\" for fixable implementation work.`);
+    }
+  }
+
+  if (evidence.verification === "unverified") {
+    const gauntletCandidate = findCandidate(candidates, "gauntlet");
+    if (gauntletCandidate) {
+      return buildResolution(evidence, candidates, gauntletCandidate, `Selected \"${gauntletCandidate}\" because work is still unverified.`);
+    }
+  }
+
+  if (evidence.work === "verify") {
+    const gauntletCandidate = findCandidate(candidates, "gauntlet");
+    if (gauntletCandidate) {
+      return buildResolution(evidence, candidates, gauntletCandidate, `Selected \"${gauntletCandidate}\" for verification work.`);
+    }
+  }
+
+  if (evidence.work === "ship" && evidence.verification === "verified" && evidence.action === "done") {
+    const shipCandidate = findCandidate(candidates, "ship");
+    if (shipCandidate) {
+      return buildResolution(evidence, candidates, shipCandidate, `Selected \"${shipCandidate}\" for verified ship-ready work.`);
+    }
+  }
+
+  return buildResolution(evidence, candidates, candidates[0], `Selected first declared route for outcome \"${evidence.outcome}\".`);
+}