heyspex 0.1.0 → 0.2.1

package/scripts/claude-hooks/_intent-classifier-semantic.mjs

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+// HeySpex Intent Classifier — SEMANTIC layer.
+//
+// The Intent Classifier has two layers ([[HS-UJVA-EPIC-KKMO-autonomous-skill-routing-context]]):
+//   1. LEXICAL (fast path) — the per-rule regex patterns in the guardrail registry.
+//      A regex hit fires instantly and never waits on this module.
+//   2. SEMANTIC — on a regex MISS, resolve intent WITHOUT a second, separate model.
+//      DEFAULT (mode: self_check, [[HS-M4PN-TASK]]): the router deterministically
+//      injects a SELF-CHECK instruction and lets the agent already running the session
+//      judge intent as part of its own turn — no network, no fleet machine, works for
+//      every user. The self-check block is built in _intent-classifier-router.mjs;
+//      this module is the OPT-IN model fallback for anyone who still wants it.
+//      Why the semantic layer exists at all (regex alone is not enough):
+//      [[intent-classifier-injected-content]] — 9/10 paraphrased improvement-idea
+//      phrasings missed before the patterns were broadened, and paraphrase drift
+//      never ends.
+//
+// OPT-IN MODEL FALLBACK (mode: model): classifyIntent() below classifies the prompt
+// with a fast LOCAL model (Ollama) and returns { behavior, confidence } so the caller
+// can fire above a threshold. This is the ORIGINAL mechanism, now DEMOTED to an
+// explicit opt-in — it is NEVER on the default path, so no reachable endpoint is
+// required for the semantic layer to function ([[HS-M4PN-TASK]] AC2).
+//
+// HARD FAIL-SAFE CONTRACT (hook house rules): this module NEVER throws, NEVER
+// hangs past its timeout, and on ANY problem (endpoint down, timeout, bad JSON,
+// unexpected shape) returns { behavior: null, confidence: 0 } so the calling hook
+// proceeds exactly as if the semantic layer did not exist. Dependency-free:
+// Node stdlib + global fetch only (hooks run on a fresh clone with no npm install).
+//
+// Config (.heyspex/config.yaml → agent_behaviors.intent_classifier.*), all optional.
+// The file is read from the VAULT root (the loader's `defaultConfigRoot()`), not this
+// checkout — [[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]:
+//   semantic_enabled: true|false   (default true — turns Layer 2 on/off entirely)
+//   mode: self_check|model         (default self_check — deterministic injection;
+//                                    `model` opts into the Ollama fallback below)
+//   endpoint:  Ollama base URL     (default http://192.168.1.252:11434 — mode:model only)
+//   model:     model name          (default qwen3:8b — mode:model only)
+//   timeout_ms: request budget     (default 2500 — the hook's overall budget is 5s)
+//   min_confidence: fire threshold (default 0.7 — consumed by the calling hook)
+// Env overrides (kill switch first):
+//   HEYSPEX_INTENT_SEMANTIC_OFF=1      hard off (disables Layer 2 entirely)
+//   HEYSPEX_INTENT_SEMANTIC_MODE=self_check|model
+//   HEYSPEX_INTENT_ENDPOINT / HEYSPEX_INTENT_MODEL /
+//   HEYSPEX_INTENT_TIMEOUT_MS / HEYSPEX_INTENT_MIN_CONFIDENCE
+//
+// Self-test without a session (exercises the opt-in model fallback):
+//   node scripts/claude-hooks/_intent-classifier-semantic.mjs --ping
+//   node scripts/claude-hooks/_intent-classifier-semantic.mjs --classify "some prompt"
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { readConfigLeafRaw } from './_guardrail-loader.mjs';
+import { defaultConfigRoot } from '../../spexharness/src/config-root.mjs';
+
+// The CODE checkout — where `.heyspex/intent-classifier-history.jsonl` (an event
+// log, a code-repo artifact) is appended. NOT where config.yaml is read from: the
+// config reads below default to the vault root via `defaultConfigRoot()`
+// ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]).
+export const DEFAULT_REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+);
+
+// Semantic-layer modes ([[HS-M4PN-TASK]]):
+//   'self_check' — DEFAULT. On a regex miss the router injects a deterministic
+//                  self-check instruction; the session's own agent judges intent.
+//                  No network, no fleet machine.
+//   'model'      — OPT-IN fallback. classifyIntent() calls the local Ollama endpoint.
+export const SEMANTIC_MODES = Object.freeze(['self_check', 'model']);
+
+export const DEFAULTS = Object.freeze({
+  semanticEnabled: true,
+  semanticMode: 'self_check',
+  endpoint: 'http://192.168.1.252:11434',
+  model: 'qwen3:8b',
+  timeoutMs: 2500,
+  minConfidence: 0.7,
+});
+
+// The behavior catalog the classifier chooses from. Descriptions are the actual
+// classification instructions, so keep them about the USER'S INTENT, not the
+// system's response. Any hook can pass its own list; this shared catalog keeps
+// capture-trigger and research-trigger consistent if both adopt the semantic layer.
+export const KNOWN_BEHAVIORS = Object.freeze([
+  {
+    key: 'capture_on_idea',
+    description:
+      'The user is sharing a raw idea, suggestion, observation, or improvement thought — a brain-dump about something that could exist or be better — rather than giving a direct work order, asking a question about existing work, or continuing work already in progress.',
+  },
+  {
+    key: 'research_before_decision',
+    description:
+      'The user is declining to make a design or architecture decision themselves and is asking for research, best practices, or an expert recommendation instead (e.g. "not a decision I should have to make", "don\'t reinvent the wheel").',
+  },
+  {
+    key: 'settings_intent',
+    description:
+      'The user wants to READ or CHANGE a HeySpex workflow setting / agent behavior — enable or disable a behavior (auto-capture, the research trigger, the intent classifier), turn something on or off, set/lower/raise a threshold or value (confidence, timeout), or ask what a setting is currently. About the configuration itself, NOT a request to do the underlying work. (e.g. "turn off auto-capture", "lower the classifier confidence to 0.6", "is auto-capture on", "make it stop capturing everything").',
+  },
+  {
+    key: 'defer_intent',
+    description:
+      'The user wants to DEFER, POSTPONE, or SCHEDULE a follow-up to a later time — "come back to this later", "remind me in a week", "park/table this until X is done", "schedule this for next week", "not now — later, after the migration". About WHEN to revisit something, not a request to do it now.',
+  },
+  {
+    key: 'handoff_intent',
+    description:
+      'The user asks for a hand-off prompt, doc, notes or resume context for the NEXT agent or session ("give me a handoff prompt for the next agent", "hand this off", "what should the next session know"). About producing the hand-off artifact, NOT about loading one (a lane code like GQ5R or `hs handoff load`) and not ordinary work.',
+  },
+]);
+
+function num(raw, fallback) {
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+function clamp01(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v)) return 0;
+  return Math.max(0, Math.min(1, v));
+}
+
+/**
+ * Resolve the semantic-layer config: env override → .heyspex/config.yaml →
+ * shipped defaults. FAIL-SAFE: any unreadable value falls back to its default.
+ * `repoRoot` is the directory holding `.heyspex/config.yaml` — defaults to the
+ * vault root; an explicit argument (tests, fixtures) always wins.
+ */
+export function readIntentClassifierConfig(repoRoot = defaultConfigRoot()) {
+  const cfg = { ...DEFAULTS };
+  try {
+    if (process.env.HEYSPEX_INTENT_SEMANTIC_OFF === '1') cfg.semanticEnabled = false;
+    else {
+      const enabled = readConfigLeafRaw('agent_behaviors.intent_classifier.semantic_enabled', repoRoot);
+      if (enabled !== undefined) cfg.semanticEnabled = enabled.trim().toLowerCase() !== 'false';
+    }
+    // Mode: env override → config → default 'self_check'. Any unrecognized value
+    // falls back to the deterministic default rather than silently enabling the model.
+    const modeRaw =
+      process.env.HEYSPEX_INTENT_SEMANTIC_MODE ||
+      unquote(readConfigLeafRaw('agent_behaviors.intent_classifier.mode', repoRoot));
+    if (typeof modeRaw === 'string') {
+      const m = modeRaw.trim().toLowerCase();
+      if (SEMANTIC_MODES.includes(m)) cfg.semanticMode = m;
+    }
+    const endpoint =
+      process.env.HEYSPEX_INTENT_ENDPOINT ||
+      unquote(readConfigLeafRaw('agent_behaviors.intent_classifier.endpoint', repoRoot));
+    if (endpoint && /^https?:\/\//.test(endpoint)) cfg.endpoint = endpoint.replace(/\/+$/, '');
+    const model =
+      process.env.HEYSPEX_INTENT_MODEL ||
+      unquote(readConfigLeafRaw('agent_behaviors.intent_classifier.model', repoRoot));
+    if (model) cfg.model = model;
+    cfg.timeoutMs = num(
+      process.env.HEYSPEX_INTENT_TIMEOUT_MS ??
+        readConfigLeafRaw('agent_behaviors.intent_classifier.timeout_ms', repoRoot),
+      DEFAULTS.timeoutMs,
+    );
+    const minConf = Number(
+      process.env.HEYSPEX_INTENT_MIN_CONFIDENCE ??
+        readConfigLeafRaw('agent_behaviors.intent_classifier.min_confidence', repoRoot),
+    );
+    if (Number.isFinite(minConf) && minConf > 0 && minConf <= 1) cfg.minConfidence = minConf;
+  } catch {
+    return { ...DEFAULTS };
+  }
+  return cfg;
+}
+
+function unquote(raw) {
+  if (typeof raw !== 'string') return undefined;
+  const v = raw.trim();
+  const m = v.match(/^"(.*)"$/) || v.match(/^'(.*)'$/);
+  return m ? m[1] : v || undefined;
+}
+
+function buildSystemPrompt(behaviors) {
+  const rows = behaviors
+    .map((b) => `- ${b.key}: ${b.description}`)
+    .join('\n');
+  return (
+    'You classify ONE user message from a coding-agent session into exactly one behavior key, or "none" ' +
+    'when no behavior applies. Behaviors:\n' +
+    rows +
+    '\n- none: a direct work order, a question about existing work, a bug report to fix now, small talk, or anything else.\n' +
+    'Reply with STRICT JSON only, no prose: {"behavior":"<one key above or none>","confidence":<number 0..1>}'
+  );
+}
+
+/**
+ * Classify a prompt into one of the given behaviors via the local Ollama endpoint.
+ *
+ * @param {string} prompt              the user's message
+ * @param {{key:string, description:string}[]} behaviors  candidate behaviors (defaults to KNOWN_BEHAVIORS)
+ * @param {object} [opts]              { endpoint, model, timeoutMs, repoRoot } — omitted values come from config
+ * @returns {Promise<{behavior: string|null, confidence: number, latencyMs?: number, error?: string}>}
+ *   behavior is null when nothing matched OR anything failed (fail-safe).
+ */
+export async function classifyIntent(prompt, behaviors = KNOWN_BEHAVIORS, opts = {}) {
+  const none = { behavior: null, confidence: 0 };
+  try {
+    if (typeof prompt !== 'string' || !prompt.trim()) return none;
+    const list = Array.isArray(behaviors) && behaviors.length ? behaviors : KNOWN_BEHAVIORS;
+    const cfg = readIntentClassifierConfig(opts.repoRoot ?? defaultConfigRoot());
+    const endpoint = opts.endpoint ?? cfg.endpoint;
+    const model = opts.model ?? cfg.model;
+    const timeoutMs = num(opts.timeoutMs, cfg.timeoutMs);
+
+    // Very short prompts carry no classifiable intent; very long ones are truncated
+    // to keep the local model inside the latency budget.
+    const text = prompt.trim().slice(0, 2000);
+    if (text.length < 12) return none;
+
+    // Optional call counter (proof/observability): when HEYSPEX_INTENT_CALL_LOG names
+    // a file, append one byte per model call so a test can assert exactly ≤1 call per
+    // prompt. Fail-safe: never let instrumentation break the classifier.
+    if (process.env.HEYSPEX_INTENT_CALL_LOG) {
+      try {
+        fs.appendFileSync(process.env.HEYSPEX_INTENT_CALL_LOG, `${new Date().toISOString()} ${model}\n`);
+      } catch {
+        /* ignore */
+      }
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const t0 = Date.now();
+    let res;
+    try {
+      res = await fetch(`${endpoint}/api/chat`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        signal: controller.signal,
+        body: JSON.stringify({
+          model,
+          stream: false,
+          format: 'json',
+          think: false, // qwen3: skip the reasoning preamble; harmless no-op elsewhere
+          keep_alive: '30m', // keep the classifier warm between prompts
+          options: { temperature: 0, num_predict: 120 },
+          messages: [
+            { role: 'system', content: buildSystemPrompt(list) },
+            { role: 'user', content: text },
+          ],
+        }),
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const latencyMs = Date.now() - t0;
+    if (!res || !res.ok) return { ...none, latencyMs, error: `http_${res?.status ?? 'no_response'}` };
+
+    const payload = await res.json().catch(() => null);
+    const content = payload?.message?.content;
+    if (typeof content !== 'string' || !content.trim()) return { ...none, latencyMs, error: 'empty_response' };
+
+    let parsed;
+    try {
+      parsed = JSON.parse(content);
+    } catch {
+      // Defensive: some models wrap JSON in text — try the first {...} span.
+      const m = content.match(/\{[\s\S]*\}/);
+      if (!m) return { ...none, latencyMs, error: 'unparseable_response' };
+      try {
+        parsed = JSON.parse(m[0]);
+      } catch {
+        return { ...none, latencyMs, error: 'unparseable_response' };
+      }
+    }
+
+    const rawBehavior = typeof parsed?.behavior === 'string' ? parsed.behavior.trim() : '';
+    const confidence = clamp01(parsed?.confidence);
+    const valid = list.some((b) => b.key === rawBehavior);
+    if (!valid || rawBehavior === 'none') return { behavior: null, confidence, latencyMs };
+    return { behavior: rawBehavior, confidence, latencyMs };
+  } catch (err) {
+    const error = err?.name === 'AbortError' ? 'timeout' : 'unreachable';
+    return { ...none, error };
+  }
+}
+
+/**
+ * Append one classifier-decision row to .heyspex/intent-classifier-history.jsonl.
+ * Called by the hooks for FIRES (either layer), semantic NEAR-MISSES (matched
+ * behavior below threshold), and semantic ERRORS — never for the ordinary
+ * regex-miss/no-match case, so the log stays small. FAIL-SAFE: never throws.
+ */
+export function appendClassifierEvent(row, repoRoot = DEFAULT_REPO_ROOT) {
+  try {
+    const full = {
+      timestamp: new Date().toISOString(),
+      event_kind: 'intent_classifier.decision',
+      ...row,
+    };
+    fs.appendFileSync(
+      path.join(repoRoot, '.heyspex', 'intent-classifier-history.jsonl'),
+      JSON.stringify(full) + '\n',
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── self-test CLI (no session required) ─────────────────────────────────────
+
+async function ping() {
+  const cfg = readIntentClassifierConfig();
+  const out = { config: cfg, reachable: false, version: null, classify: null };
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), cfg.timeoutMs);
+    const res = await fetch(`${cfg.endpoint}/api/version`, { signal: controller.signal });
+    clearTimeout(timer);
+    if (res.ok) {
+      out.reachable = true;
+      out.version = (await res.json().catch(() => null))?.version ?? null;
+    }
+  } catch {
+    /* stays unreachable */
+  }
+  if (out.reachable) {
+    out.classify = await classifyIntent(
+      "it'd be smart to let the app notice ideas on its own",
+      KNOWN_BEHAVIORS,
+    );
+  }
+  process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+  process.exit(out.reachable && out.classify?.behavior === 'capture_on_idea' ? 0 : 1);
+}
+
+async function classifyCli(text) {
+  const result = await classifyIntent(text, KNOWN_BEHAVIORS);
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  process.exit(0);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  if (process.argv.includes('--ping')) {
+    ping();
+  } else {
+    const idx = process.argv.indexOf('--classify');
+    if (idx !== -1 && process.argv[idx + 1]) {
+      classifyCli(process.argv[idx + 1]);
+    } else if (process.argv.length > 2) {
+      process.stdout.write(
+        'Usage: node _intent-classifier-semantic.mjs --ping | --classify "<text>"\n',
+      );
+      process.exit(2);
+    }
+  }
+}