@litfamily/lithermes 1.0.4 → 1.0.6

package/src/lib/check.js

@@ -1,8 +1,8 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
-const { configHasLitHermes, inspectHermesCapabilities, readConfig } = require("./config");
-const { detectHermesRuntimeRepo, detectHermesVersion, ensureHermesHome, inspectHermesHostCapabilities, LitHermesError } = require("./hermesDiscovery");
+const { configHasLitHermes, inspectHermesCapabilities, readConfig, readExternalSkillDirsConfig } = require("./config");
+const { detectHermesRuntimeRepo, detectHermesVersion, ensureHermesHome, expandHome, inspectHermesHostCapabilities, LitHermesError } = require("./hermesDiscovery");
 const { formatManagedRoute } = require("./modelRoutePolicy");
 const { inspectPythonCache } = require("./files");
 const { assetRoot, pluginDest } = require("./install");
@@ -112,6 +112,75 @@ function loadedStatusMatchesOrigin(output, expectedPluginPath) {
   }
 }
 
+function isRegularSkillFile(file) {
+  try {
+    return fs.lstatSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// Bounded, non-symlink-following scan for `<HERMES_HOME>/skills/**/<id>/SKILL.md`.
+// Real local-skill trees are shallow, so a small depth/entry cap keeps this cheap
+// while still catching a collision a couple of category folders deep.
+function collectLocalSkillShadows(hermesHome, skillIds, { maxDepth = 3, maxEntries = 2000 } = {}) {
+  const remaining = new Set(skillIds);
+  const found = new Map();
+  let visited = 0;
+  function walk(dir, depth) {
+    if (!remaining.size || depth > maxDepth || visited >= maxEntries) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!remaining.size || visited >= maxEntries) return;
+      visited += 1;
+      if (!entry.isDirectory()) continue;
+      const full = path.join(dir, entry.name);
+      if (remaining.has(entry.name)) {
+        const skillFile = path.join(full, "SKILL.md");
+        if (isRegularSkillFile(skillFile)) {
+          found.set(entry.name, skillFile);
+          remaining.delete(entry.name);
+          continue;
+        }
+      }
+      walk(full, depth + 1);
+    }
+  }
+  walk(path.join(hermesHome, "skills"), 0);
+  return found;
+}
+
+// Hermes resolves a bare skill name (not the `lithermes:<name>` explicit-load form)
+// against `skills.external_dirs` and local `<HERMES_HOME>/skills`; a same-named entry
+// there is picked instead of the LitHermes plugin copy. This is advisory: it never
+// changes doctor's pass/fail status, only surfaces the collision.
+function detectSkillShadows({ configText, hermesHome, skillIds = requiredSkills }) {
+  const externalDirs = readExternalSkillDirsConfig(configText)
+    .map((dir) => path.resolve(expandHome(dir)));
+  const localShadows = collectLocalSkillShadows(hermesHome, skillIds);
+  const warnings = [];
+  for (const id of skillIds) {
+    const externalDir = externalDirs.find((dir) => isRegularSkillFile(path.join(dir, id, "SKILL.md")));
+    if (externalDir) {
+      warnings.push({ id, path: path.join(externalDir, id, "SKILL.md"), source: "skills.external_dirs" });
+      continue;
+    }
+    const localPath = localShadows.get(id);
+    if (localPath) warnings.push({ id, path: localPath, source: "local skills" });
+  }
+  return warnings;
+}
+
+function formatSkillShadowWarning(shadow) {
+  return `WARNING: skill "${shadow.id}" bare name resolves to ${shadow.path} (${shadow.source}); `
+    + `use lithermes:${shadow.id} to load LitHermes's copy, or remove/rename the other copy.`;
+}
+
 function checkLitHermes(flags = {}) {
   const { hermesHome, hermesRepo } = ensureHermesHome(flags);
   const pluginPath = pluginDest(hermesHome);
@@ -187,6 +256,7 @@ function doctorLitHermes(flags = {}) {
 	const unsafeRecursion = recursion.status === "unavailable" && recursion.reason.startsWith("nested delegation");
 	const unsafeModelRoute = modelSafety.status === "blocked";
   const runtime = capabilities.runtime;
+  const skillShadows = detectSkillShadows({ configText, hermesHome });
   const lines = [
     `plugin discovery: ${installedPass && configOk ? "PASS" : "PATCH_AVAILABLE"}`,
     `bundled source: ${bundledPass ? "PASS" : "FAIL"}`,
@@ -198,6 +268,8 @@ function doctorLitHermes(flags = {}) {
     `installed payload: ${installedPass ? "PASS" : "FAIL"}`,
     `enabled config: ${configOk ? "PASS" : "PARTIAL"}`,
     `loaded plugin: ${loaded.status} (${loaded.reason})`,
+    `skill shadow check: ${skillShadows.length ? "WARNING" : "PASS"}`,
+    ...skillShadows.map(formatSkillShadowWarning),
     `auto-compaction: ${auto.status}${auto.reason ? ` (${auto.reason})` : ""}`,
 		`concurrency: ${concurrency.status}${concurrency.status === "hard" ? ` (per batch ${concurrency.limit}; async batches ${concurrency.asyncBatchLimit}; potential children ${concurrency.potentialChildCeiling})` : ` (${concurrency.reason})`}`,
 		`recursion: ${recursion.status}${recursion.status === "hard" ? recursion.flatBy === "depth" ? ` (depth ${recursion.limit}, flat)` : ` (configured depth ${recursion.limit}, flat via orchestrator kill switch)` : ` (${recursion.reason})`}`,
@@ -222,6 +294,7 @@ module.exports = {
   checkGatewaySource,
   checkLitHermes,
   checkTuiSource,
+  detectSkillShadows,
   doctorLitHermes,
   enabledUserJsonIncludesPlugin,
   loadedStatusMatchesOrigin,

package/src/lib/config.js

@@ -1,5 +1,6 @@
 const fs = require("node:fs");
 const path = require("node:path");
+const { parseDocument } = require("yaml");
 const { writeFileAtomic } = require("./files");
 const modelConfig = require("./modelConfig");
 
@@ -205,6 +206,27 @@ function clearOutputStyleConfig(text) {
   return `${updated.replace(/\n*$/, "")}\n`;
 }
 
+// Hermes `skills.external_dirs` (config.yaml key, default []): bare-name skill
+// resolution searches these directories, so a same-named directory there can shadow
+// a LitHermes plugin skill (which is only reachable unambiguously as `lithermes:<name>`).
+// Malformed YAML fails closed to an empty list rather than throwing during doctor.
+function readExternalSkillDirsConfig(text) {
+  const str = String(text || "");
+  if (!str.trim()) return [];
+  try {
+    const document = parseDocument(str, { strict: true, uniqueKeys: true });
+    if (document.errors.length) return [];
+    const node = document.getIn(["skills", "external_dirs"], true);
+    const value = node && typeof node.toJS === "function" ? node.toJS(document) : node;
+    if (!Array.isArray(value)) return [];
+    return value
+      .filter((entry) => typeof entry === "string" && entry.trim())
+      .map((entry) => entry.trim());
+  } catch {
+    return [];
+  }
+}
+
 function writeConfig(hermesHome, text) {
   fs.mkdirSync(hermesHome, { recursive: true });
   writeFileAtomic(configPath(hermesHome), text, "utf8");
@@ -220,6 +242,7 @@ module.exports = {
   enableLitHermesConfig,
   readConfig,
   readDisplaySkinConfig,
+  readExternalSkillDirsConfig,
   readOutputStyleConfig,
   readTuiAgentsNudgeConfig,
   setDisplaySkinConfig,

package/src/lib/install.js

@@ -17,6 +17,7 @@ const { assertStateParent, assertPluginParent, defaultHermesHome, defaultHermesR
 const { NOT_PROBED_HOST_VERSION } = require("./modelConfigBoundary");
 const { patchInstalledHermes, rollbackPatches } = require("./patch");
 const {
+  ASTRA_MODEL,
   formatManagedRoute,
   managedRequest,
   missingCredentialWarning,
@@ -344,7 +345,7 @@ function installLitHermes(flags = {}) {
     );
   }
   if (dryRun) {
-    const selectedModel = modelPlan.request?.model || "gpt-6-astra";
+    const selectedModel = modelPlan.request?.model || ASTRA_MODEL;
     const selectedEffort = modelPlan.request?.effort || "xhigh";
     return {
       message: [

package/src/lib/modelConfig.js

@@ -6,6 +6,7 @@ const { OPENAI_PROVIDER, RESPONSES_MODE, classifyHostVersion,
 const {
   ASTRA_MODEL,
   MANAGED_PROVIDER_MODELS,
+  MODEL_IDS,
   applyManagedRoute,
   customChildTransportReason,
   inspectEffectiveRouteSafety,
@@ -17,8 +18,6 @@ const {
   unavailableTuiRouteVisibility,
 } = require("./modelRoutePolicy");
 
-const MODELS = new Set(["gpt-6-astra", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]);
-
 // The route every "configured" verdict is measured against: explicit installer
 // options win; otherwise the document's own route when it is a catalog route;
 // otherwise today's shipped default.
@@ -45,6 +44,12 @@ function expectedRoute(options = {}, document = null) {
 const SAFE_CONTEXT_LENGTH = 372000;
 const SAFE_COMPRESSION_THRESHOLD = 0.9;
 const SAFE_AUTO_COMPACTION_LIMIT = SAFE_CONTEXT_LENGTH * SAFE_COMPRESSION_THRESHOLD;
+const LEGACY_CONTEXT_MODELS = new Set([
+  "gpt-5.6",
+  "gpt-5.6-sol",
+  "gpt-5.6-terra",
+  "gpt-5.6-luna",
+]);
 const MANAGED_SAMPLING_KEYS = ["temperature", "top_p", "top_logprobs"];
 
 function hasValue(document, path) {
@@ -156,7 +161,7 @@ function classificationFromDocument(document, fresh) {
   if (provider === OPENAI_PROVIDER && (dispatch === "gpt-5.4" || dispatch === "gpt-5.5")) {
     return { class: "managed_legacy", originalDispatchId };
   }
-  if (provider === OPENAI_PROVIDER && MODELS.has(dispatch)) {
+  if (provider === OPENAI_PROVIDER && MODEL_IDS.has(dispatch)) {
     return { class: "existing_managed", originalDispatchId };
   }
   if (MANAGED_PROVIDER_MODELS[provider]?.has(dispatch)) {
@@ -364,10 +369,9 @@ function planModelConfig(text, options = {}) {
   }
   const document = boundary.document;
   applyManagedRoute(document, route);
-  // The verified legacy context/compression defaults belong to legacy model
-  // resets only. Astra has no host-published limit evidence, so an Astra reset
-  // preserves explicit values and leaves missing values absent.
-  if (options.reconfigure && route.model !== ASTRA_MODEL && route.childModel !== ASTRA_MODEL) {
+  // The verified context/compression defaults apply only to explicit GPT-5.6
+  // model resets. GPT-6 model routes have no published evidence for these limits.
+  if (options.reconfigure && LEGACY_CONTEXT_MODELS.has(route.model)) {
     document.setIn(["model", "context_length"], SAFE_CONTEXT_LENGTH);
     document.setIn(["compression", "threshold"], SAFE_COMPRESSION_THRESHOLD);
   }

package/src/lib/modelRoutePolicy.js

@@ -1,38 +1,77 @@
 const ASTRA_MODEL = "gpt-6-astra";
-const ASTRA_EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"]);
+const GPT6_LEAD_EFFORTS = new Set(["low", "medium", "high", "xhigh", "max", "ultra"]);
+const ASTRA_EFFORTS = GPT6_LEAD_EFFORTS;
 const PARENT_MODEL = ASTRA_MODEL;
 const PARENT_EFFORT = "xhigh";
-const CHILD_MODEL = "gpt-5.6-luna";
+const SOL_MODEL = "gpt-6-sol";
+const CHILD_MODEL = "gpt-6-luna";
+const LEGACY_SOL_MODEL = "gpt-5.6-sol";
+const LEGACY_CHILD_MODEL = "gpt-5.6-luna";
 const CHILD_EFFORT = "max";
-const LUNA_EFFORTS = new Set(["high", "max"]);
+const GPT6_LUNA_EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"]);
+const LEGACY_LUNA_EFFORTS = new Set(["high", "max"]);
+const LUNA_EFFORTS = LEGACY_LUNA_EFFORTS;
+const LUNA_MODELS = new Set([CHILD_MODEL, LEGACY_CHILD_MODEL]);
 const TERRA_MODEL = "gpt-5.6-terra";
 const TERRA_EFFORTS = new Set(["high", "xhigh", "max"]);
+const LEGACY_SOL_EFFORTS = new Set(["high", "xhigh"]);
+const MODEL_EFFORTS = new Map([
+  [ASTRA_MODEL, GPT6_LEAD_EFFORTS],
+  [SOL_MODEL, GPT6_LEAD_EFFORTS],
+  [CHILD_MODEL, GPT6_LUNA_EFFORTS],
+  [LEGACY_SOL_MODEL, LEGACY_SOL_EFFORTS],
+  [LEGACY_CHILD_MODEL, LEGACY_LUNA_EFFORTS],
+  ["gpt-5.6", new Set(["high"])],
+  [TERRA_MODEL, TERRA_EFFORTS],
+]);
 const CHILD_TRANSPORT_KEYS = ["provider", "base_url", "api_mode"];
 const { OPENAI_PROVIDER: OPENAI_PROVIDER_ID } = require("./modelConfigBoundary");
 const XAI_PROVIDER_ID = "xai";
 // Installer choice catalog (plans/references/installer-choice-contract.md, LitHermes row).
-// OpenAI rows: Astra exposes exactly the five Responses efforts; the existing Sol,
-// Luna, and general GPT-5.6 rows remain below it and Luna+xhigh is never listed. xAI rows: the
-// reasoning-capable models of the Hermes 0.19 static xAI catalog
+// OpenAI rows follow each model's listed effort set, including selectable legacy
+// GPT-5.6 routes. xAI rows use the reasoning-capable models of the Hermes 0.19 catalog
 // (hermes_cli/models.py `_XAI_STATIC_FALLBACK`), newest first, with the Hermes
 // reasoning_effort vocabulary (hermes_cli/config.py delegation.reasoning_effort).
 const ROUTE_CATALOG = {
   [OPENAI_PROVIDER_ID]: {
     credentialEnv: null,
-    label: "OpenAI OAuth Responses (Astra + GPT-5.6)",
+    label: "OpenAI OAuth Responses (Astra + Sol + Luna)",
     rows: [
-      ...["low", "medium", "high", "xhigh", "max"].map((effort) => ({
+      ...["low", "medium", "high", "xhigh", "max", "ultra"].map((effort) => ({
         effort,
         model: ASTRA_MODEL,
-        note: effort === "max"
+        note: effort === "ultra"
           ? "deepest Astra reasoning"
           : effort === PARENT_EFFORT
             ? "recommended lead"
             : "Astra Responses effort",
       })),
-      { effort: PARENT_EFFORT, model: "gpt-5.6-sol", note: "existing Sol lead route" },
-      { effort: CHILD_EFFORT, model: CHILD_MODEL, note: "balanced (recommended helper)" },
-      { effort: "high", model: CHILD_MODEL, note: "balanced, lighter effort" },
+      ...["low", "medium", "high", "xhigh", "max", "ultra"].map((effort) => ({
+        effort,
+        model: SOL_MODEL,
+        note: effort === PARENT_EFFORT ? "coding lead alternative" : "Sol Responses effort",
+      })),
+      ...["low", "medium", "high", "xhigh", "max"].map((effort) => ({
+        effort,
+        model: CHILD_MODEL,
+        note: effort === CHILD_EFFORT
+          ? "balanced (recommended helper)"
+          : effort === "high"
+            ? "balanced, lighter effort"
+            : "Luna Responses effort",
+      })),
+      ...["high", "xhigh"].map((effort) => ({
+        effort,
+        model: LEGACY_SOL_MODEL,
+        note: "previous-generation Sol lead route",
+      })),
+      ...["high", "xhigh", "max"].map((effort) => ({
+        effort,
+        model: TERRA_MODEL,
+        note: "previous-generation Terra route",
+      })),
+      { effort: CHILD_EFFORT, model: LEGACY_CHILD_MODEL, note: "previous-generation balanced helper" },
+      { effort: "high", model: LEGACY_CHILD_MODEL, note: "previous-generation lighter helper" },
       { effort: "high", model: "gpt-5.6", note: "general model" },
     ],
     lead: { effort: PARENT_EFFORT, model: PARENT_MODEL },
@@ -55,6 +94,10 @@ const PROVIDER_IDS = Object.keys(ROUTE_CATALOG);
 const MANAGED_PROVIDER_MODELS = Object.fromEntries(
   PROVIDER_IDS.map((id) => [id, new Set(ROUTE_CATALOG[id].rows.map((row) => row.model))]),
 );
+const MODEL_IDS = new Set([
+  ...MANAGED_PROVIDER_MODELS[OPENAI_PROVIDER_ID],
+  TERRA_MODEL,
+]);
 const MANAGED_PROVIDERS = new Set(PROVIDER_IDS);
 const UNSAFE_ROUTE_CODE = "LITHERMES_UNSAFE_MODEL_ROUTE";
 const REVIEWER_ROUTE_NAME = String.fromCharCode(109, 111, 109, 117, 115);
@@ -83,42 +126,32 @@ function inspectEffectiveRouteSafety(document, expectedProvider) {
   const managedRoutes = routes.filter((route) => route.provider === expectedProvider);
   for (const route of managedRoutes) {
     if (transportReason && route.route === "global_child") continue;
-    if (route.model === ASTRA_MODEL && !ASTRA_EFFORTS.has(route.effort)) {
-      return {
-        classificationClass: "astra_effort_unsupported",
-        code: UNSAFE_ROUTE_CODE,
-        observedSource: `${route.route} model, effort, and provider config`,
-        reason: `${route.route} Astra effort is unsupported or missing; choose one of: ${[...ASTRA_EFFORTS].join(", ")}`,
-        route: route.route,
-        status: "blocked",
-      };
-    }
-    if (route.model === CHILD_MODEL && route.effort === "xhigh") {
-      return {
-        classificationClass: "conflicting_luna_xhigh",
-        code: UNSAFE_ROUTE_CODE,
-        observedSource: `${route.route} model, effort, and provider config`,
-        reason: `${route.route} Luna xhigh is a forbidden pair (Luna runs at high or max)`,
-        route: route.route,
-        status: "blocked",
-      };
-    }
-    if (route.model === CHILD_MODEL && !LUNA_EFFORTS.has(route.effort)) {
-      return {
-        classificationClass: "luna_effort_below_high",
-        code: UNSAFE_ROUTE_CODE,
-        observedSource: `${route.route} model, effort, and provider config`,
-        reason: `${route.route} Luna effort is below high or missing`,
-        route: route.route,
-        status: "blocked",
-      };
-    }
-    if (route.model === TERRA_MODEL && !TERRA_EFFORTS.has(route.effort)) {
+    const modelEfforts = MODEL_EFFORTS.get(route.model);
+    if (modelEfforts && !modelEfforts.has(route.effort)) {
+      const isAstra = route.model === ASTRA_MODEL;
+      const isLuna = LUNA_MODELS.has(route.model);
+      const isLegacyLunaXhigh = route.model === LEGACY_CHILD_MODEL && route.effort === "xhigh";
       return {
-        classificationClass: "terra_effort_below_high",
+        classificationClass: isAstra
+          ? "astra_effort_unsupported"
+          : isLegacyLunaXhigh
+            ? "conflicting_luna_xhigh"
+            : isLuna
+              ? "luna_effort_below_high"
+              : route.model === TERRA_MODEL
+                ? "terra_effort_below_high"
+                : "model_effort_unsupported",
         code: UNSAFE_ROUTE_CODE,
         observedSource: `${route.route} model, effort, and provider config`,
-        reason: `${route.route} TERRA effort is below high or missing`,
+        reason: isAstra
+          ? `${route.route} Astra effort is unsupported or missing; choose one of: ${[...modelEfforts].join(", ")}`
+          : isLegacyLunaXhigh
+            ? `${route.route} Luna xhigh is a forbidden pair (legacy Luna runs at high or max)`
+            : isLuna
+              ? `${route.route} Luna effort is unsupported; choose one of: ${[...modelEfforts].join(", ")}`
+              : route.model === TERRA_MODEL
+                ? `${route.route} TERRA effort is below high or missing`
+                : `${route.route} ${route.model} effort is unsupported or missing; choose one of: ${[...modelEfforts].join(", ")}`,
         route: route.route,
         status: "blocked",
       };
@@ -140,7 +173,7 @@ function inspectEffectiveRouteSafety(document, expectedProvider) {
   }
   return {
     observedSource: "parent and global delegation model policy",
-    reason: "no effective under-effort Luna or TERRA route is configured",
+    reason: "no effective model and effort pair outside the model catalog is configured",
     status: "safe",
   };
 }
@@ -162,8 +195,8 @@ function resolveRow(provider, role, model, effort) {
   const hasModel = model !== undefined;
   const hasEffort = effort !== undefined;
   const resolvedModel = hasModel ? String(model) : preset.model;
-  if (resolvedModel === CHILD_MODEL && hasEffort && effort === "xhigh") {
-    throw new Error(`${role} route ${CHILD_MODEL} xhigh is a forbidden pair; Luna runs at high or max`);
+  if (resolvedModel === LEGACY_CHILD_MODEL && hasEffort && effort === "xhigh") {
+    throw new Error(`${role} route ${resolvedModel} xhigh is a forbidden pair; legacy Luna runs at high or max`);
   }
   const rowsForModel = catalog.rows.filter((row) => row.model === resolvedModel);
   if (!rowsForModel.length) {
@@ -244,10 +277,10 @@ function inspectManagedRoute(document, expectedProvider, route = managedRequest(
     && childModel === route.childModel
     && childEffort === route.childEffort;
   const legacyConfigured = parentProvider === expectedProvider
-    && parentModel === "gpt-5.6-luna"
+    && parentModel === LEGACY_CHILD_MODEL
     && parentEffort === "max"
-    && childModel === CHILD_MODEL
-    && LUNA_EFFORTS.has(childEffort);
+    && childModel === LEGACY_CHILD_MODEL
+    && LEGACY_LUNA_EFFORTS.has(childEffort);
   if (!configured && !legacyConfigured) {
     return {
       status: "unavailable",
@@ -359,8 +392,18 @@ function formatManagedRoute(route) {
 module.exports = {
   ASTRA_EFFORTS,
   ASTRA_MODEL,
+  CHILD_MODEL,
+  GPT6_LEAD_EFFORTS,
+  GPT6_LUNA_EFFORTS,
+  LEGACY_LUNA_EFFORTS,
+  LEGACY_CHILD_MODEL,
+  LEGACY_SOL_MODEL,
+  LUNA_EFFORTS,
+  LUNA_MODELS,
   MANAGED_PROVIDER_MODELS,
+  MODEL_IDS,
   OPENAI_PROVIDER_ID,
+  SOL_MODEL,
   PROVIDER_IDS,
   ROUTE_CATALOG,
   XAI_PROVIDER_ID,

package/src/lib/skillPayload.js

@@ -16,7 +16,7 @@ const MAX_PAYLOAD_TOTAL_BYTES = 16 * 1024 * 1024;
 const requiredSkills = [
   "lit-burnoff-file", "autoconference", "autoresearch", "browser-drive", "comment-checker", "debugging",
   "deep-interview",
-  "frontend-ui-ux", "lit-commit", "lit-crucible", "lit-init",
+  "frontend-ui-ux", "readme-studio", "lit-commit", "lit-crucible", "lit-init",
   "lit-korean", "lit-comprehend", "lit-handoff", "lit-plan", "lit-recap",
   "lit-scientific-visualization", "litgoal", "litresearch", "litwork", "lsp",
   "lsp-setup", "lit-code", "refactor", "lit-burnoff", "review-work",