openhermes 4.11.2 → 4.12.1

package/harness/lib/hooks/types.ts

@@ -8,14 +8,62 @@ export enum HookPhase {
   LATE = 2,
 }
 
-export interface HookContext {
+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;
+  };
+
+  _memorySyncCount?: number;
+  _recoveryAttempt?: 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
@@ -34,7 +82,7 @@ export interface PreToolUseHook {
   metadata: HookMetadata;
   execute(
     context: HookContext,
-  ): Promise<{ result: HookResult; modifiedContext?: Partial<HookContext> }>;
+  ): Promise<{ result: HookResult; modifiedContext?: HookContextPatch }>;
 }
 
 export interface PostToolUseHook {

package/harness/lib/memory/memory-manager.ts

@@ -18,7 +18,7 @@ import type {
 // ---------------------------------------------------------------------------
 
 export class MemoryManager {
-  private static instance: MemoryManager;
+  private static instance: MemoryManager | null = null;
 
   private entries: Map<MemoryLevel, MemoryEntry[]> = new Map();
   private config: MemoryConfig;
@@ -46,7 +46,7 @@ export class MemoryManager {
 
   /** Reset singleton — used in tests for isolation. */
   static resetInstance(): void {
-    MemoryManager.instance = null as unknown as MemoryManager;
+    MemoryManager.instance = null;
   }
 
   // -----------------------------------------------------------------------

package/harness/lib/memory/memory.test.ts

@@ -410,12 +410,6 @@ describe("PlanStore", () => {
     assert.ok(content.includes("Do something"));
   });
 
-  // ---- 21: getMerged returns empty for now --------------------------------
-
-  it("getMerged returns empty for now", async () => {
-    const result = await PlanStore.getMerged("session-1");
-    assert.deepEqual(result, []);
-  });
 });
 
 // ---------------------------------------------------------------------------

package/harness/lib/memory/plan-store.ts

@@ -231,27 +231,7 @@ export class PlanStore {
     }
   }
 
-  /**
-   * Merge parent context entries for child sessions.
-   * Returns all entries from both parent and current session context.
-   */
-  static async getMerged(
-    sessionId: string,
-    parentSessionId?: string,
-  ): Promise<MemoryEntry[]> {
-    const all: MemoryEntry[] = [];
-
-    // For now, this is a placeholder that returns empty — real merging
-    // requires the caller to provide plan paths. This stub hooks into
-    // the intended architecture without dictating I/O strategy.
-    if (parentSessionId) {
-      // In a real implementation, we would look up the parent session's
-      // plan file and merge its memory entries with the child's.
-    }
-
-    return all;
-  }
-}
+}
 
 // ---------------------------------------------------------------------------
 // Internal parsing helpers

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}\".`);
+}

package/harness/lib/routing/routing.test.ts

@@ -0,0 +1,195 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { consumeRouteGuidance, parseSkillFrontmatter, resolveRoute } from "./index.ts";
+
+describe("routing frontmatter", () => {
+  it("parses scalar route values", () => {
+    const parsed = parseSkillFrontmatter(`---
+name: oh-test
+route:
+  pass: oh-builder
+  fail: oh-review
+  blocker: surface
+---`);
+
+    assert.ok(parsed);
+    assert.deepEqual(parsed.route, {
+      pass: ["oh-builder"],
+      fail: ["oh-review"],
+      blocker: ["surface"],
+    });
+  });
+
+  it("parses yaml route lists", () => {
+    const parsed = parseSkillFrontmatter(`---
+name: oh-test
+route:
+  pass:
+    - oh-gauntlet
+    - oh-ship
+  fail:
+    - oh-builder
+  blocker: surface
+---`);
+
+    assert.ok(parsed);
+    assert.deepEqual(parsed.route, {
+      pass: ["oh-gauntlet", "oh-ship"],
+      fail: ["oh-builder"],
+      blocker: ["surface"],
+    });
+  });
+
+  it("parses inline route arrays", () => {
+    const parsed = parseSkillFrontmatter(`---
+name: oh-test
+route:
+  pass: [oh-gauntlet, oh-ship]
+  fail: [surface, oh-expert]
+  blocker: surface
+---`);
+
+    assert.ok(parsed);
+    assert.deepEqual(parsed.route, {
+      pass: ["oh-gauntlet", "oh-ship"],
+      fail: ["surface", "oh-expert"],
+      blocker: ["surface"],
+    });
+  });
+});
+
+describe("resolveRoute", () => {
+  const route = {
+    pass: ["oh-gauntlet", "oh-ship"],
+    fail: ["oh-builder"],
+    blocker: ["surface"],
+  };
+
+  it("defaults to the first candidate for an outcome", () => {
+    const resolved = resolveRoute(route, { outcome: "pass" });
+    assert.deepEqual(resolved, {
+      outcome: "pass",
+      candidates: ["oh-gauntlet", "oh-ship"],
+      selected: "oh-gauntlet",
+      reason: 'Selected first declared route for outcome "pass".',
+    });
+  });
+
+  it("prefers an evidence target when it matches a candidate", () => {
+    const resolved = resolveRoute(route, { outcome: "pass", target: "oh-ship" });
+    assert.deepEqual(resolved, {
+      outcome: "pass",
+      candidates: ["oh-gauntlet", "oh-ship"],
+      selected: "oh-ship",
+      reason: 'Selected "oh-ship" from output evidence.',
+    });
+  });
+
+  it("prefers oh-ship for verified done ship work", () => {
+    const resolved = resolveRoute(route, {
+      outcome: "pass",
+      verification: "verified",
+      action: "done",
+      work: "ship",
+    });
+
+    assert.deepEqual(resolved, {
+      outcome: "pass",
+      verification: "verified",
+      action: "done",
+      work: "ship",
+      candidates: ["oh-gauntlet", "oh-ship"],
+      selected: "oh-ship",
+      reason: 'Selected "oh-ship" for verified ship-ready work.',
+    });
+  });
+
+  it("prefers oh-gauntlet for unverified work", () => {
+    const resolved = resolveRoute(route, {
+      outcome: "pass",
+      verification: "unverified",
+      action: "done",
+      work: "ship",
+    });
+
+    assert.deepEqual(resolved, {
+      outcome: "pass",
+      verification: "unverified",
+      action: "done",
+      work: "ship",
+      candidates: ["oh-gauntlet", "oh-ship"],
+      selected: "oh-gauntlet",
+      reason: 'Selected "oh-gauntlet" because work is still unverified.',
+    });
+  });
+
+  it("prefers oh-gauntlet for verify work", () => {
+    const resolved = resolveRoute(route, {
+      outcome: "pass",
+      verification: "verified",
+      action: "done",
+      work: "verify",
+    });
+
+    assert.deepEqual(resolved, {
+      outcome: "pass",
+      verification: "verified",
+      action: "done",
+      work: "verify",
+      candidates: ["oh-gauntlet", "oh-ship"],
+      selected: "oh-gauntlet",
+      reason: 'Selected "oh-gauntlet" for verification work.',
+    });
+  });
+
+  it("prefers oh-builder for fixable implementation work", () => {
+    const resolved = resolveRoute({
+      pass: ["oh-gauntlet", "oh-ship", "oh-builder"],
+      fail: ["oh-builder"],
+      blocker: ["surface"],
+    }, {
+      outcome: "pass",
+      verification: "verified",
+      action: "fixable",
+      work: "implement",
+    });
+
+    assert.deepEqual(resolved, {
+      outcome: "pass",
+      verification: "verified",
+      action: "fixable",
+      work: "implement",
+      candidates: ["oh-gauntlet", "oh-ship", "oh-builder"],
+      selected: "oh-builder",
+      reason: 'Selected "oh-builder" for fixable implementation work.',
+    });
+  });
+});
+
+describe("consumeRouteGuidance", () => {
+  it("promotes a selected route into an explicit next-route instruction", () => {
+    const consumed = consumeRouteGuidance([
+      "Review complete",
+      'ROUTE_GUIDANCE: {"outcome":"pass","candidates":["oh-gauntlet","oh-ship"],"selected":"oh-ship","reason":"Selected \\\"oh-ship\\\" from output evidence."}',
+    ].join("\n"));
+
+    assert.equal(consumed.selected, "oh-ship");
+    assert.match(consumed.output, /NEXT_ROUTE: oh-ship/);
+  });
+
+  it("leaves output unchanged when no route guidance is present", () => {
+    const output = "plain output";
+    const consumed = consumeRouteGuidance(output);
+
+    assert.equal(consumed.selected, null);
+    assert.equal(consumed.output, output);
+  });
+
+  it("ignores malformed route guidance safely", () => {
+    const output = 'Review complete\nROUTE_GUIDANCE: {"selected":42}';
+    const consumed = consumeRouteGuidance(output);
+
+    assert.equal(consumed.selected, null);
+    assert.equal(consumed.output, output);
+  });
+});