openhermes 4.3.0 → 4.9.2

package/harness/skills/oh-skills-list/SKILL.md

@@ -1,11 +1,7 @@
 ---
 name: oh-skills-list
-description: "List all available oh-* skills with descriptions"
+description: "Use when the user wants to see available OH skills. Lists all oh-* skills with descriptions."
 tier: 2
-triggers:
-  - "list skills"
-  - "show skills"
-  - "what skills"
 route:
   pass: done
   fail: surface
@@ -14,27 +10,18 @@ route:
 
 # oh-skills-list
 
-## When to Use
-To discover what skills are available. Lists every skill with its name, description, and category.
+List all available oh-* skills with tier and description.
 
-## Output
-Markdown table of skills:
+## Steps
 
-| Skill | Description | Category |
-|-------|-------------|----------|
-| oh-plan | Strategy + architecture review | Orchestration |
-| oh-qa | Full QA workflow | Quality |
-| ... | ... | ... |
-
-## Anti-patterns
-- Listing "all available" but missing recently installed skills
-- Showing skill file paths instead of human-readable descriptions
-- Not categorising skills (flat list is hard to scan)
+1. Gather all oh-* skills from the harness
+2. Format as a table: Skill | Tier | Purpose
+3. Output the table to the user
 
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → [done — read-only report] |
-| fail | → [surface issue to user] |
-| blocker | → surface to user |
+| pass | → done |
+| fail | → surface |
+| blocker | → surface |

package/harness/skills/oh-triage/DEEP.md

@@ -0,0 +1,23 @@
+# oh-triage — Deep Reference
+
+## When to Use
+
+New issues or backlog review. Drives through triage state machine.
+
+## States
+
+1. Needs triage (new, unclassified)
+2. Needs info (waiting on reporter)
+3. Ready for agent (well-specified)
+4. Ready for human (needs judgment/access)
+5. Wontfix (declined with reason)
+
+## Anti-patterns
+
+- Issues stuck in "needs triage"
+- Triaging without reading full issue
+- Wontfix without explanation
+
+## Reference
+
+**Example:** New issues appear with needs-triage label. Read issue, classify as bug/feature/enhancement, assess severity, assign state (ready-for-agent / ready-for-human / needs-info).

package/harness/skills/oh-triage/SKILL.md

@@ -1,11 +1,7 @@
 ---
 name: oh-triage
-description: "Issue triage state machine — classify, prioritise, assign"
+description: "Use when new issues need triage — classify, prioritise, and assign through the triage state machine."
 tier: 2
-triggers:
-  - "triage this issue"
-  - "classify this issue"
-  - "triage the backlog"
 route:
   pass:
     - oh-issue
@@ -16,32 +12,20 @@ route:
 
 # oh-triage
 
-## When to Use
-When new issues come in, or when reviewing the issue backlog. Drives issues through a triage state machine.
+Classify, prioritise, and assign new issues through the triage state machine.
 
-## States
-1. **Needs triage** — new issue, unclassified
-2. **Needs info** — waiting on reporter for clarification
-3. **Ready for agent** — well-specified, can be picked up
-4. **Ready for human** — needs human judgment or access
-5. **Wontfix** — declined with reason
+## Steps
 
-## Workflow
-1. Read new issues (label: `needs-triage`)
+1. Read issues with `needs-triage` label
 2. Classify: bug / feature / enhancement / question
 3. Assess severity and priority
-4. Assign to appropriate state and owner
+4. Assign state and owner
 5. Add triage metadata labels
 
-## Anti-patterns
-- Leaving issues in "needs triage" indefinitely
-- Triaging without reading the full issue
-- Wontfix without explanation (leaves reporter unhappy)
-
 ## Routing
 
 | Outcome | Route |
 |---------|-------|
-| pass | → oh-issue (publish triaged issues) or oh-handoff (pass to agent) |
-| fail | → oh-expert (clarify ambiguous issue) |
-| blocker | → surface to user |
+| pass | → oh-issue or oh-handoff |
+| fail | → oh-expert |
+| blocker | → surface |

package/harness/skills/oh-worktree/DEEP.md

@@ -0,0 +1,169 @@
+# oh-worktree — Deep Reference
+
+## When to Use
+
+Starting feature work that needs isolation from the current workspace. Ensures work happens in an isolated workspace. Prefers native worktree tools. Falls back to manual git worktrees only when no native tool is available.
+
+**Core principle:** Detect existing isolation first. Use native tools. Fall back to git. Never fight the harness.
+
+**Example:** User says "set up worktree for feature-x." Run detection → create worktree → install deps → verify baseline tests pass. Report ready.
+
+## Phases
+
+### Step 0: Detect Existing Isolation
+
+**Before creating anything, check if you are already in an isolated workspace.**
+
+```bash
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null && cd "$(git rev-parse --git-dir)" && pwd -P)
+GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null && cd "$(git rev-parse --git-common-dir)" && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
+
+```bash
+git rev-parse --show-superproject-working-tree 2>/dev/null
+```
+
+If this returns a path, you're in a submodule — treat as normal repo.
+
+**If `GIT_DIR != GIT_COMMON` (and not a submodule):** Already in a linked worktree. Skip to Step 3. Do NOT create another worktree.
+
+- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
+- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
+
+**If `GIT_DIR == GIT_COMMON` (or in a submodule):** Normal repo checkout. Ask for consent before creating a worktree:
+
+> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
+
+Honor any declared preference without asking. If declined, work in place and skip to Step 3.
+
+### Step 1: Create Isolated Workspace
+
+Two mechanisms. Try in order.
+
+#### 1a. Native Worktree Tools (preferred)
+
+If a native worktree tool exists (e.g., `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag), use it and skip to Step 3. Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when a native tool exists creates phantom state the harness cannot see or manage.
+
+Only proceed to Step 1b if no native tool is available.
+
+#### 1b. Git Worktree Fallback
+
+Only if Step 1a does not apply.
+
+##### Directory Selection
+
+Follow this priority. Explicit user preference always beats observed state.
+
+1. Check instructions for a declared worktree directory preference. If specified, use it without asking.
+2. Check for an existing project-local worktree directory:
+   ```bash
+   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+   ls -d worktrees 2>/dev/null      # Alternative
+   ```
+   If found, use it. If both exist, `.worktrees` wins.
+3. Check for an existing global directory:
+   ```bash
+   project=$(basename "$(git rev-parse --show-toplevel)")
+   ls -d ~/.config/opencode/worktrees/$project 2>/dev/null
+   ```
+   If found, use it (backward compatibility).
+4. If no other guidance, default to `.worktrees/` at the project root.
+
+##### Safety Verification (project-local directories only)
+
+**Must verify directory is ignored before creating worktree:**
+
+```bash
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+If NOT ignored, add to `.gitignore` and commit the change before proceeding.
+
+Why critical: Prevents accidentally committing worktree contents to the repository. Global directories (`~/.config/opencode/worktrees/`) need no verification.
+
+##### Create the Worktree
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+# project-local: path="$LOCATION/$BRANCH_NAME"
+# global: path="~/.config/opencode/worktrees/$project/$BRANCH_NAME"
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), report the sandbox blocked worktree creation and work in the current directory instead. Then run setup and baseline tests in place.
+
+### Step 3: Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+if [ -f package.json ]; then npm install; fi
+if [ -f Cargo.toml ]; then cargo build; fi
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### Step 4: Verify Clean Baseline
+
+Run tests to ensure workspace starts clean using the project-appropriate command (`npm test` / `cargo test` / `pytest` / `go test ./...`).
+
+- Tests pass: Report ready.
+- Tests fail: Report failures, ask whether to proceed or investigate.
+
+#### Report
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Already in linked worktree | Skip creation (Step 0) |
+| In a submodule | Treat as normal repo (Step 0 guard) |
+| Native worktree tool available | Use it (Step 1a) |
+| No native tool | Git worktree fallback (Step 1b) |
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check instruction file, then default `.worktrees/` |
+| Global path exists | Use it (backward compat) |
+| Directory not ignored | Add to .gitignore + commit |
+| Permission error on create | Sandbox fallback, work in place |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Anti-patterns
+
+- **Fighting the harness:** Using `git worktree add` when the platform already provides isolation. Fix: Step 0 detects existing isolation; Step 1a defers to native tools.
+- **Skipping detection:** Creating a nested worktree inside an existing one. Fix: Always run Step 0 before creating anything.
+- **Skipping ignore verification:** Worktree contents get tracked, pollute git status. Fix: Always use `git check-ignore` before creating a project-local worktree.
+- **Assuming directory location:** Creates inconsistency, violates project conventions. Fix: Follow priority: existing > global legacy > instruction file > default.
+- **Proceeding with failing tests:** Cannot distinguish new bugs from pre-existing issues. Fix: Report failures, get explicit permission to proceed.
+- **Jumping to git fallback:** Skipping Step 1a and going straight to `git worktree add` when a native tool exists. This is the most common mistake.
+
+## Red Flags
+
+**Never:**
+- Create a worktree when Step 0 detects existing isolation
+- Use `git worktree add` when a native worktree tool is available
+- Skip Step 1a by jumping straight to Step 1b's git commands
+- Create a worktree without verifying it is ignored (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without asking
+
+**Always:**
+- Run Step 0 detection first
+- Prefer native tools over git fallback
+- Follow directory priority: existing > global legacy > instruction file > default
+- Verify directory is ignored for project-local paths
+- Auto-detect and run project setup
+- Verify clean test baseline

package/harness/skills/oh-worktree/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: oh-worktree
+description: "Use when starting feature work that needs isolation from the current workspace or before executing implementation plans. Manages workspace isolation via git worktrees."
+tier: 3
+route:
+  pass: oh-manifest
+  fail: surface
+  blocker: surface
+---
+
+# oh-worktree
+
+Create isolated workspaces via git worktrees for safe feature development.
+
+## Steps
+
+1. Detect existing isolation — check if already in a linked worktree
+2. Check submodule status to avoid false worktree detection
+3. Ask for user consent if not already isolated
+4. Prefer native worktree tools over git fallback
+5. Select worktree directory following priority: existing > global legacy > instruction file > default
+6. Verify directory is git-ignored for project-local paths
+7. Auto-detect and run project setup (npm install, cargo build, etc.)
+8. Verify clean test baseline and report ready
+
+## Routing
+
+| Outcome | Route |
+|---------|-------|
+| pass | → oh-manifest |
+| fail | → surface |
+| blocker | → surface |

package/lib/harness-resolver.ts

@@ -9,12 +9,12 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const PKG_DIR = path.resolve(__dirname, "..")
 
 const REQUIRED_HARNESS_FILES: ReadonlyArray<readonly string[]> = [
-  ["codex", "CONSTITUTION.md"],
-  ["instructions", "RUNTIME.md"],
+  ["codex", "CHARTER.md"],
+  ["codex", "AUTOPILOT.md"],
   ["skills", "oh-planner", "SKILL.md"],
 ]
 
-function ancestorDirs(start: string, limit = 6): string[] {
+function ancestorDirs(start: string, limit = 3): string[] {
   const dirs: string[] = []
   let current = path.resolve(start)
   for (let i = 0; i < limit; i++) {
@@ -26,17 +26,15 @@ function ancestorDirs(start: string, limit = 6): string[] {
   return dirs
 }
 
-function buildHarnessCandidates(currentDir: string, execPath: string, cwd: string): string[] {
-  const roots = [path.resolve(currentDir, "harness")]
-  const seen = new Set(roots)
+function buildHarnessCandidates(currentDir: string, cwd: string): string[] {
+  const roots: string[] = []
+  const seen = new Set<string>()
 
-  const anchors = [path.dirname(execPath), path.dirname(path.dirname(execPath)), cwd]
-  for (const anchor of anchors) {
+  for (const anchor of [currentDir, cwd]) {
     for (const dir of ancestorDirs(anchor)) {
       for (const root of [
         path.join(dir, "harness"),
         path.join(dir, "node_modules", "openhermes", "harness"),
-        path.join(dir, "bin", "node_modules", "openhermes", "harness"),
       ]) {
         const normalized = path.normalize(root)
         if (seen.has(normalized)) continue
@@ -64,7 +62,7 @@ export function resolveHarnessRoot({
   cwd?: string
   candidateRoots?: string[]
 } = {}): string {
-  const roots = candidateRoots ?? buildHarnessCandidates(currentDir, execPath, cwd)
+  const roots = candidateRoots ?? buildHarnessCandidates(currentDir, cwd)
   for (const root of roots) {
     if (hasRequiredHarnessFiles(root)) return root
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openhermes",
-  "version": "4.3.0",
-  "description": "OpenCode-native orchestration for packaged skills, commands, and agents.",
+  "version": "4.9.2",
+  "description": "Autonomous agent orchestration for OpenCode.",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -9,7 +9,8 @@
   },
   "main": "./index.ts",
   "dependencies": {
-    "@opencode-ai/plugin": "1.14.46"
+    "@opencode-ai/plugin": "1.15.0",
+    "gpt-tokenizer": "^3.4.0"
   },
   "exports": {
     ".": "./index.ts",
@@ -22,6 +23,7 @@
     "ETHOS.md",
     "CONTEXT.md",
     "lib/",
+    "scripts/",
     "harness/codex/",
     "harness/instructions/",
     "harness/skills/",

package/scripts/count-tokens.mjs

@@ -0,0 +1,158 @@
+/**
+ * Exact token counting using gpt-tokenizer.
+ * Counts every SKILL.md, bootstrap doc, AGENTS.md, and instructions.
+ */
+import { encode } from "gpt-tokenizer";
+import fs from "fs";
+import path from "path";
+
+const HOME = process.env.USERPROFILE || process.env.HOME;
+const ROOT = path.resolve("Q:/PROJECTS/PERSONAL/openhermes-pkg");
+
+const categories = {
+  "OH Bootstrap Docs (on disk, NOT injected)": [
+    path.join(ROOT, "harness/codex/AUTOPILOT.md"),
+    path.join(ROOT, "harness/codex/CHARTER.md"),
+    path.join(ROOT, "harness/instructions/SHELL.md"),
+    path.join(ROOT, "CONTEXT.md"),
+    path.join(ROOT, "ETHOS.md"),
+  ],
+  "OH Agent Prompt (injected as system prompt)": [
+    path.join(ROOT, "harness/agents/openhermes.md"),
+  ],
+  "OH Built-in Skills (31, registered)": [],
+  "User Skills (.agents/skills) — on disk, NOT registered": [],
+  "User Skills (.config/opencode/skills) — on disk, NOT registered": [],
+  "Instructions": [
+    path.join(ROOT, "AGENTS.md"),
+    path.join(HOME, ".config/opencode/AGENTS.md"),
+  ],
+};
+
+// Discover OH built-in skills
+const skillsDir = path.join(ROOT, "harness/skills");
+for (const entry of fs.readdirSync(skillsDir)) {
+  const skPath = path.join(skillsDir, entry, "SKILL.md");
+  if (fs.existsSync(skPath)) categories["OH Built-in Skills (31, registered)"].push(skPath);
+}
+
+// Discover user skills
+const userDirs = [
+  path.join(HOME, ".agents/skills"),
+  path.join(HOME, ".config/opencode/skills"),
+];
+for (const dir of userDirs) {
+  const key = dir.includes(".agents")
+    ? "User Skills (.agents/skills) — on disk, NOT registered"
+    : "User Skills (.config/opencode/skills) — on disk, NOT registered";
+  if (fs.existsSync(dir)) {
+    for (const entry of fs.readdirSync(dir)) {
+      const skPath = path.join(dir, entry, "SKILL.md");
+      if (fs.existsSync(skPath)) categories[key].push(skPath);
+    }
+  }
+}
+
+// Extract frontmatter description
+function extractDescription(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return { description: "", body: content };
+    const fm = match[1];
+    const descLine = fm.split("\n").find(l => l.trim().startsWith("description:"));
+    if (!descLine) return { description: "", body: content.slice(match[0].length) };
+    const desc = descLine.slice(descLine.indexOf(":") + 1).trim().replace(/^['"]|['"]$/g, "");
+    return { description: desc, body: content.slice(match[0].length) };
+  } catch { return { description: "", body: "" }; }
+}
+
+// Build what the available_skills XML block looks like (OH built-in skills only)
+function buildAvailableSkillsXml(includeUserSkills = false) {
+  const parts = ['<available_skills>'];
+  const allDirs = [path.join(ROOT, "harness/skills")];
+  if (includeUserSkills) {
+    allDirs.push(
+      path.join(HOME, ".agents/skills"),
+      path.join(HOME, ".config/opencode/skills"),
+    );
+  }
+  for (const dir of allDirs) {
+    if (!fs.existsSync(dir)) continue;
+    for (const entry of fs.readdirSync(dir).sort()) {
+      const skPath = path.join(dir, entry, "SKILL.md");
+      if (!fs.existsSync(skPath)) continue;
+      const { description } = extractDescription(skPath);
+      parts.push(`  <skill>`);
+      parts.push(`    <name>${entry}</name>`);
+      parts.push(`    <description>${description}</description>`);
+      parts.push(`    <location>file:///${skPath.replace(/\\/g, '/')}</location>`);
+      parts.push(`  </skill>`);
+    }
+  }
+  parts.push('</available_skills>');
+  return parts.join('\n');
+}
+
+// Count everything
+console.log("=".repeat(80));
+console.log("EXACT TOKEN COUNTS (gpt-tokenizer)");
+console.log("=".repeat(80));
+
+let grandTotal = 0;
+
+for (const [category, files] of Object.entries(categories)) {
+  console.log(`\n--- ${category} ---`);
+  let catTotal = 0;
+  for (const file of files) {
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, "utf8");
+    const tokens = encode(content).length;
+    const name = path.basename(path.dirname(file)) !== "skills"
+      ? path.basename(file)
+      : path.basename(path.dirname(file));
+    console.log(`  ${name.padEnd(40)} ${String(tokens).padStart(6)} tokens  (${content.length.toLocaleString()} bytes)`);
+    catTotal += tokens;
+  }
+  console.log(`  ${"-".repeat(50)}`);
+  console.log(`  TOTAL: ${catTotal} tokens`);
+  grandTotal += catTotal;
+}
+
+// Available skills XML cost (OH built-in only — user skills no longer registered)
+console.log(`\n--- available_skills XML Block (OH only, 31 skills) ---`);
+const xmlContent = buildAvailableSkillsXml(false);
+const xmlTokens = encode(xmlContent).length;
+console.log(`  Total: ${xmlTokens} tokens  (${xmlContent.length.toLocaleString()} bytes)`);
+
+console.log(`\n--- available_skills XML Block (ALL 61 skills, for comparison) ---`);
+const xmlContentAll = buildAvailableSkillsXml(true);
+const xmlTokensAll = encode(xmlContentAll).length;
+console.log(`  Total: ${xmlTokensAll} tokens  (${xmlContentAll.length.toLocaleString()} bytes)`);
+
+grandTotal += xmlTokens;
+
+// System prompt components
+const instructionsTotal = categories["Instructions"].reduce((s, f) => {
+  if (!fs.existsSync(f)) return s;
+  return s + encode(fs.readFileSync(f, "utf8")).length;
+}, 0);
+const agentPromptTotal = categories["OH Agent Prompt (injected as system prompt)"].reduce((s, f) => {
+  if (!fs.existsSync(f)) return s;
+  return s + encode(fs.readFileSync(f, "utf8")).length;
+}, 0);
+
+console.log(`\n${"=".repeat(80)}`);
+console.log(`TOTAL ALL SKILL FILES: ${categories["OH Built-in Skills (31, registered)"].reduce((s, f) => s + encode(fs.readFileSync(f, "utf8")).length, 0)} tokens`);
+console.log(`TOTAL USER SKILL FILES: ${categories["User Skills (.agents/skills) — on disk, NOT registered"].reduce((s, f) => s + encode(fs.readFileSync(f, "utf8")).length, 0)} tokens`);
+console.log(`TOTAL CONFIG SKILLS: ${categories["User Skills (.config/opencode/skills) — on disk, NOT registered"].reduce((s, f) => s + encode(fs.readFileSync(f, "utf8")).length, 0)} tokens`);
+console.log(`TOTAL INSTRUCTIONS: ${instructionsTotal} tokens`);
+console.log(`AGENT PROMPT (openhermes.md): ${agentPromptTotal} tokens`);
+console.log(`available_skills XML (ALL 61 skills, registered): ${xmlTokensAll} tokens`);
+console.log(`\nBOOTSTRAP INJECTION: REMOVED (was 4,503 via transform hook)`);
+console.log(`ROUTING INVENTORY: REMOVED (was ~902 via buildRoutingInventory())`);
+console.log(`\nPER-TURN SYSTEM PROMPT COST: ${instructionsTotal + xmlTokensAll + agentPromptTotal} tokens`);
+console.log(`  (instructions ${instructionsTotal} + available_skills ${xmlTokensAll} + agent prompt ${agentPromptTotal})`);
+console.log(`PRE-REFACTOR COST: ${instructionsTotal + xmlTokensAll + 4503 + 902} tokens`);
+console.log(`SAVINGS: ${(instructionsTotal + xmlTokensAll + 4503 + 902) - (instructionsTotal + xmlTokensAll + agentPromptTotal)} tokens per turn`);
+console.log("=".repeat(80));