hivemind-context-governance 1.3.0

package/src/hooks/compaction.ts

@@ -0,0 +1,104 @@
+/**
+ * Compaction Hook — Preserves hierarchy context across LLM compaction.
+ *
+ * Reads current brain state hierarchy and injects it into
+ * post-compaction context via output.context.push().
+ *
+ * P3: try/catch — never break compaction
+ * Budget-capped ≤500 tokens (~2000 chars)
+ */
+
+import type { Logger } from "../lib/logging.js"
+import { createStateManager } from "../lib/persistence.js"
+
+/** Budget in characters (~500 tokens at ~4 chars/token) */
+const INJECTION_BUDGET_CHARS = 2000
+
+/**
+ * Creates the compaction hook.
+ *
+ * Hook factory pattern: captured logger + directory.
+ */
+export function createCompactionHook(log: Logger, directory: string) {
+  const stateManager = createStateManager(directory)
+
+  return async (
+    _input: { sessionID: string },
+    output: { context: string[] }
+  ): Promise<void> => {
+    try {
+      const state = await stateManager.load()
+      if (!state) {
+        await log.debug("Compaction: no brain state to preserve")
+        return
+      }
+
+      const lines: string[] = []
+      lines.push("=== HiveMind Context (post-compaction) ===")
+      lines.push("")
+
+      // Session info
+      lines.push(
+        `Session: ${state.session.id} | Status: ${state.session.governance_status} | Mode: ${state.session.mode}`
+      )
+      lines.push("")
+
+      // Hierarchy — the most important context to preserve
+      lines.push("## Current Hierarchy")
+      if (state.hierarchy.trajectory) {
+        lines.push(`Trajectory: ${state.hierarchy.trajectory}`)
+      }
+      if (state.hierarchy.tactic) {
+        lines.push(`Tactic: ${state.hierarchy.tactic}`)
+      }
+      if (state.hierarchy.action) {
+        lines.push(`Action: ${state.hierarchy.action}`)
+      }
+      if (
+        !state.hierarchy.trajectory &&
+        !state.hierarchy.tactic &&
+        !state.hierarchy.action
+      ) {
+        lines.push("No hierarchy set. Use map_context to set focus.")
+      }
+      lines.push("")
+
+      // Metrics
+      lines.push(
+        `Turns: ${state.metrics.turn_count} | Drift: ${state.metrics.drift_score}/100 | Files: ${state.metrics.files_touched.length}`
+      )
+
+      if (state.metrics.files_touched.length > 0) {
+        const maxFiles = 10
+        const shown = state.metrics.files_touched.slice(0, maxFiles)
+        lines.push(`Files: ${shown.join(", ")}`)
+        if (state.metrics.files_touched.length > maxFiles) {
+          lines.push(
+            `  ... and ${state.metrics.files_touched.length - maxFiles} more`
+          )
+        }
+      }
+
+      lines.push("")
+      lines.push("=== End HiveMind Context ===")
+
+      // Budget enforcement
+      let context = lines.join("\n")
+      if (context.length > INJECTION_BUDGET_CHARS) {
+        context =
+          context.slice(0, INJECTION_BUDGET_CHARS - 30) +
+          "\n=== End HiveMind Context ==="
+        await log.warn(
+          `Compaction injection truncated: ${lines.join("\n").length} → ${context.length} chars`
+        )
+      }
+
+      output.context.push(context)
+
+      await log.debug(`Compaction: injected ${context.length} chars`)
+    } catch (error) {
+      // P3: Never break compaction — this is critical
+      await log.error(`Compaction hook error: ${error}`)
+    }
+  }
+}

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Hook barrel exports — HiveMind governance hooks
+ */
+
+export { createToolGateHook } from "./tool-gate.js"
+export type { ToolGateResult } from "./tool-gate.js"
+export { createSessionLifecycleHook } from "./session-lifecycle.js"
+export { createCompactionHook } from "./compaction.js"

package/src/hooks/session-lifecycle.ts

@@ -0,0 +1,133 @@
+/**
+ * Session Lifecycle Hook — Initialize/load brain state on session events.
+ *
+ * Handles:
+ *   - Session start: load existing state or create fresh
+ *   - System prompt injection: current hierarchy + governance status
+ *
+ * P3: try/catch — never break session lifecycle
+ * P5: Config cached in closure
+ */
+
+import type { Logger } from "../lib/logging.js"
+import type { HiveMindConfig } from "../schemas/config.js"
+import { generateAgentBehaviorPrompt } from "../schemas/config.js"
+import { createStateManager } from "../lib/persistence.js"
+import {
+  createBrainState,
+  generateSessionId,
+} from "../schemas/brain-state.js"
+import { initializePlanningDirectory } from "../lib/planning-fs.js"
+
+/**
+ * Creates the session lifecycle hook (system prompt transform).
+ *
+ * Injects current session context into the system prompt:
+ *   - Hierarchy state (trajectory/tactic/action)
+ *   - Governance status (LOCKED/OPEN)
+ *   - Session metrics (drift score, turn count)
+ *
+ * Budget: ≤250 tokens (~1000 chars). ADD, not REPLACE.
+ */
+export function createSessionLifecycleHook(
+  log: Logger,
+  directory: string,
+  config: HiveMindConfig
+) {
+  const stateManager = createStateManager(directory)
+  const BUDGET_CHARS = 1000
+
+  return async (
+    input: { sessionID?: string },
+    output: { system: string[] }
+  ): Promise<void> => {
+    try {
+      if (!input.sessionID) return
+
+      // Load or create brain state
+      let state = await stateManager.load()
+      if (!state) {
+        // First session — initialize
+        await initializePlanningDirectory(directory)
+        const sessionId = generateSessionId()
+        state = createBrainState(sessionId, config)
+        await stateManager.save(state)
+      }
+
+      const lines: string[] = []
+      lines.push("<hivemind-governance>")
+
+      // Session status
+      lines.push(
+        `Session: ${state.session.governance_status} | Mode: ${state.session.mode} | Governance: ${state.session.governance_mode}`
+      )
+
+      // Hierarchy context
+      if (state.hierarchy.trajectory) {
+        lines.push(`Trajectory: ${state.hierarchy.trajectory}`)
+      }
+      if (state.hierarchy.tactic) {
+        lines.push(`Tactic: ${state.hierarchy.tactic}`)
+      }
+      if (state.hierarchy.action) {
+        lines.push(`Action: ${state.hierarchy.action}`)
+      }
+
+      // No hierarchy = prompt to declare intent
+      if (
+        !state.hierarchy.trajectory &&
+        !state.hierarchy.tactic &&
+        !state.hierarchy.action
+      ) {
+        if (config.governance_mode === "strict") {
+          lines.push(
+            "No intent declared. Use declare_intent to unlock the session before writing."
+          )
+        } else {
+          lines.push(
+            "Tip: Use declare_intent to set your work focus for better tracking."
+          )
+        }
+      }
+
+      // Metrics summary
+      lines.push(
+        `Turns: ${state.metrics.turn_count} | Drift: ${state.metrics.drift_score}/100 | Files: ${state.metrics.files_touched.length}`
+      )
+
+      // Drift warning
+      if (state.metrics.drift_score < 50) {
+        lines.push(
+          "⚠ High drift detected. Use map_context to re-focus."
+        )
+      }
+
+      lines.push("</hivemind-governance>")
+
+      // Inject mandatory agent behavior configuration
+      const agentConfigPrompt = generateAgentBehaviorPrompt(config.agent_behavior)
+      lines.push("")
+      lines.push(agentConfigPrompt)
+
+      // Budget enforcement
+      let injection = lines.join("\n")
+      if (injection.length > BUDGET_CHARS) {
+        injection =
+          injection.slice(0, BUDGET_CHARS - 30) +
+          "\n</agent-configuration>"
+        await log.warn(
+          `System injection truncated: ${lines.join("\n").length} → ${injection.length} chars`
+        )
+      }
+
+      output.system.push(injection)
+
+      await log.debug(
+        `Session lifecycle: injected ${injection.length} chars`
+      )
+    } catch (error) {
+      // P3: Never break session lifecycle
+      await log.error(`Session lifecycle hook error: ${error}`)
+    }
+  }
+}

package/src/hooks/tool-gate.ts

@@ -0,0 +1,205 @@
+/**
+ * Tool Gate Hook — Configurable governance enforcement.
+ *
+ * Intercepts tool calls and applies governance based on mode:
+ *   - strict: blocks writes until declare_intent called
+ *   - assisted: warns but allows
+ *   - permissive: silently allows, tracks for metrics
+ *
+ * P3: try/catch — never break tool execution
+ * P5: Config cached in closure — single disk read on first call
+ */
+
+import type { Logger } from "../lib/logging.js"
+import type { HiveMindConfig } from "../schemas/config.js"
+import {
+  isSessionLocked,
+  incrementTurnCount,
+  shouldTriggerDriftWarning,
+  addFileTouched,
+  calculateDriftScore,
+  setComplexityNudgeShown,
+} from "../schemas/brain-state.js"
+import { createStateManager } from "../lib/persistence.js"
+import { checkComplexity } from "../lib/complexity.js"
+
+/** Tools that are always allowed regardless of governance state */
+const EXEMPT_TOOLS = new Set([
+  "declare_intent",
+  "map_context",
+  "compact_session",
+  "read",
+  "grep",
+  "glob",
+  "find",
+  "list",
+  "search",
+])
+
+/** Write/edit tools that governance should gate */
+const WRITE_TOOLS = new Set([
+  "write",
+  "edit",
+  "create",
+  "delete",
+  "rename",
+  "move",
+  "patch",
+])
+
+function isExemptTool(toolName: string): boolean {
+  // Check full name match
+  if (EXEMPT_TOOLS.has(toolName)) return true
+  // Check if tool name starts with an exempt prefix
+  for (const exempt of EXEMPT_TOOLS) {
+    if (toolName.startsWith(exempt)) return true
+  }
+  return false
+}
+
+function isWriteTool(toolName: string): boolean {
+  for (const w of WRITE_TOOLS) {
+    if (toolName.includes(w)) return true
+  }
+  return false
+}
+
+export interface ToolGateResult {
+  allowed: boolean
+  error?: string
+  warning?: string
+}
+
+/**
+ * Creates the tool gate hook.
+ *
+ * Hook factory pattern — captures config + logger + directory.
+ */
+export function createToolGateHook(
+  log: Logger,
+  directory: string,
+  config: HiveMindConfig
+) {
+  const stateManager = createStateManager(directory)
+
+  return async (input: {
+    sessionID: string
+    tool: string
+  }): Promise<ToolGateResult> => {
+    try {
+      const { tool: toolName } = input
+
+      // Always allow exempt tools (governance tools + read-only)
+      if (isExemptTool(toolName)) {
+        return { allowed: true }
+      }
+
+      // Load brain state
+      let state = await stateManager.load()
+
+      // No state = no session initialized yet
+      if (!state) {
+        switch (config.governance_mode) {
+          case "strict":
+            return {
+              allowed: false,
+              error:
+                "SESSION NOT INITIALIZED. Use 'declare_intent' to start a session.",
+            }
+          case "assisted":
+            await log.warn(
+              `Tool "${toolName}" called without session. Consider using declare_intent.`
+            )
+            return {
+              allowed: true,
+              warning: "No session initialized. Consider calling declare_intent.",
+            }
+          case "permissive":
+            return { allowed: true }
+        }
+      }
+
+      // Session is locked — governance gate
+      if (state && isSessionLocked(state)) {
+        switch (config.governance_mode) {
+          case "strict":
+            if (isWriteTool(toolName)) {
+              return {
+                allowed: false,
+                error:
+                  "SESSION LOCKED. Use 'declare_intent' to unlock before writing.",
+              }
+            }
+            return { allowed: true }
+          case "assisted":
+            if (isWriteTool(toolName)) {
+              await log.warn(
+                `Write tool "${toolName}" used while session locked.`
+              )
+              return {
+                allowed: true,
+                warning:
+                  "Session locked. Declare your intent for better tracking.",
+              }
+            }
+            return { allowed: true }
+          case "permissive":
+            return { allowed: true }
+        }
+      }
+
+      // Session is open — track activity
+      if (state) {
+        state = incrementTurnCount(state)
+
+        // Track file touches for write tools (tool name used as proxy)
+        if (isWriteTool(toolName)) {
+          state = addFileTouched(state, `[via ${toolName}]`)
+        }
+
+        // Update drift score
+        state.metrics.drift_score = calculateDriftScore(state)
+
+        // Save updated state
+        await stateManager.save(state)
+
+        // Check drift warning
+        if (
+          shouldTriggerDriftWarning(
+            state,
+            config.max_turns_before_warning
+          )
+        ) {
+          await log.warn(
+            `Drift warning: ${state.metrics.turn_count} turns, score: ${state.metrics.drift_score}/100. Consider using map_context to re-focus.`
+          )
+
+          if (config.governance_mode !== "permissive") {
+            return {
+              allowed: true,
+              warning: `Drift detected (${state.metrics.drift_score}/100). Use map_context to re-focus.`,
+            }
+          }
+        }
+
+        // Check complexity and show nudge (once per session)
+        const complexityCheck = checkComplexity(state)
+        if (complexityCheck.isComplex && !state.complexity_nudge_shown) {
+          await log.warn(
+            `[Nudge] ${complexityCheck.message}`
+          )
+          
+          // Mark nudge as shown
+          state = setComplexityNudgeShown(state)
+          await stateManager.save(state)
+        }
+      }
+
+      return { allowed: true }
+    } catch (error) {
+      // P3: Never break tool execution
+      await log.error(`Tool gate error: ${error}`)
+      return { allowed: true }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,206 @@
+/**
+ * HiveMind Context Governance — OpenCode Plugin Entry Point
+ *
+ * Context-aware governance layer that prevents drift and manages
+ * session state across lifecycles. 3 tools, 3 hooks, configurable modes.
+ *
+ * CRITICAL: NO console.log anywhere — breaks TUI rendering.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin"
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import { createLogger } from "./lib/logging.js"
+import { loadConfig } from "./lib/persistence.js"
+import {
+  createToolGateHook,
+  createSessionLifecycleHook,
+  createCompactionHook,
+} from "./hooks/index.js"
+import {
+  createDeclareIntentTool,
+  createMapContextTool,
+  createCompactSessionTool,
+  createSelfRateTool,
+} from "./tools/index.js"
+import { createStateManager } from "./lib/persistence.js"
+import { trackToolCall, addSentimentSignals } from "./schemas/brain-state.js"
+import { detectSentiment } from "./lib/sentiment.js"
+import { checkRefreshTrigger } from "./lib/context-refresh.js"
+
+/**
+ * Plugin factory — hook factory pattern with captured state.
+ *
+ * GUARD: If .opencode/planning/ doesn't exist, the plugin was not initialized.
+ * Return empty hooks to avoid zombie directory creation.
+ * The user must run `hivemind init` first.
+ */
+const hivemind: Plugin = async ({ directory }) => {
+  // Init guard: skip if not initialized
+  const planningDir = join(directory, ".opencode", "planning")
+  if (!existsSync(planningDir)) {
+    return {}
+  }
+
+  const log = await createLogger(
+    join(directory, ".opencode", "planning", "logs"),
+    "hivemind-core"
+  )
+
+  await log.info(`HiveMind loaded for ${directory}`)
+
+  // Load config
+  const config = await loadConfig(directory)
+
+  // Create hook instances
+  const toolGateHook = createToolGateHook(log, directory, config)
+  const sessionLifecycleHook = createSessionLifecycleHook(
+    log,
+    directory,
+    config
+  )
+  const compactionHook = createCompactionHook(log, directory)
+
+  // Create tool instances with directory bound via closure
+  const declare_intent = createDeclareIntentTool(directory)
+  const map_context = createMapContextTool(directory)
+  const compact_session = createCompactSessionTool(directory)
+  const self_rate = createSelfRateTool(directory)
+
+  return {
+    /**
+     * Session lifecycle events.
+     */
+    event: async ({ event }) => {
+      try {
+        await log.info(`event: ${event.type}`)
+      } catch {
+        // P3: Never crash on event handling
+      }
+    },
+
+    /**
+     * Tool gate — configurable governance enforcement.
+     * Logs warnings/errors based on governance mode.
+     * Uses soft enforcement — log, don't hard-block.
+     */
+    "tool.execute.before": async (input) => {
+      const result = await toolGateHook({
+        sessionID: input.sessionID,
+        tool: input.tool,
+      })
+
+      if (!result.allowed) {
+        await log.warn(
+          `GOVERNANCE BLOCK: ${result.error ?? "Operation blocked."} (tool: ${input.tool})`
+        )
+      }
+
+      if (result.warning) {
+        await log.warn(result.warning)
+      }
+    },
+
+    /**
+     * Tool execution tracking — auto-rating on completion.
+     * Tracks successful tool calls for auto-health calculation.
+     */
+    "tool.execute.after": async (_input) => {
+      try {
+        const stateManager = createStateManager(directory)
+        let state = await stateManager.load()
+        
+        if (state) {
+          // Track successful tool call
+          state = trackToolCall(state, true)
+          await stateManager.save(state)
+          
+          // Log health score periodically (every 10 calls)
+          if (state.metrics.total_tool_calls % 10 === 0) {
+            await log.info(
+              `[AutoHealth] Score: ${state.metrics.auto_health_score}/100 (${state.metrics.successful_tool_calls}/${state.metrics.total_tool_calls} successful)`
+            )
+          }
+        }
+      } catch {
+        // P3: Never crash on tracking
+      }
+    },
+
+    /**
+     * System prompt — injects hierarchy + governance status.
+     * Budget: ≤250 tokens. ADD, not REPLACE.
+     */
+    "experimental.chat.system.transform": async (input, output) => {
+      await sessionLifecycleHook(input, output)
+    },
+
+    /**
+     * Chat message hook — sentiment detection on user messages.
+     * Detects negative signals (frustration, confusion) and updates drift score.
+     */
+    "chat.message": async (_input, output) => {
+      try {
+        // Extract text from user message parts
+        const messageText = output.parts
+          .filter((p: any) => p.type === "text")
+          .map((p: any) => p.text ?? p.content ?? "")
+          .join(" ")
+
+        if (!messageText) return
+
+        const stateManager = createStateManager(directory)
+        let state = await stateManager.load()
+
+        if (state) {
+          const signals = detectSentiment(
+            messageText,
+            state.metrics.turn_count,
+            "user"
+          )
+
+          if (signals.length > 0) {
+            state = addSentimentSignals(state, signals)
+            await stateManager.save(state)
+
+            await log.info(
+              `[Sentiment] Detected ${signals.length} signals: ${signals.map((s) => s.type).join(", ")}`
+            )
+
+            // Check if refresh trigger threshold reached
+            const refreshCheck = checkRefreshTrigger(state)
+            if (refreshCheck.shouldRefresh) {
+              await log.warn(refreshCheck.message)
+            }
+          }
+        }
+      } catch {
+        // P3: Never crash on sentiment detection
+      }
+    },
+
+    /**
+     * Compaction — preserves hierarchy context across LLM compaction.
+     * Budget: ≤500 tokens.
+     */
+    "experimental.session.compacting": async (input, output) => {
+      await compactionHook(input, output)
+    },
+
+    /**
+     * 4 lifecycle tools:
+     *   declare_intent — unlock session, set mode/focus
+     *   map_context — update hierarchy level
+     *   compact_session — archive + reset
+     *   self_rate — agent self-assessment
+     */
+    tool: {
+      declare_intent,
+      map_context,
+      compact_session,
+      self_rate,
+    },
+  }
+}
+
+export default hivemind