Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

5.9 KB
Raw Blame
/**
 * The hook observer: a small LOCAL model that flags harness divergences the
 * declarative rules do not yet encode.
 *
 * Built on the services/vision-proxy.ts contract — hard timeout, `null` on any
 * failure, never throws, never blocks the request it advises on. If the local
 * daemon is down, the model is missing, the JSON is malformed, or the call times
 * out, the observer simply contributes nothing that turn.
 *
 * MODEL SELECTION IS DISCOVERED, NOT PINNED. The config may name a model; if it
 * does not, the smallest installed non-embedding Ollama model is used. No model
 * id is hardcoded anywhere in this file — a pinned default would rot the moment
 * the user's local library changed.
 */

import { log } from "../../logger.js";
import { fetchOllamaModels, ollamaBaseUrl } from "../../providers/ollama-discovery.js";
import type { HooksConfig } from "../config.js";
import type { ObserverDigest } from "./digest.js";

const DEFAULT_TIMEOUT_MS = 1_500;

/** The slice of the config the observer reads (`hooks.observer`). */
export type ObserverConfig = Pick<HooksConfig, "observer">;

export interface ObserverVerdict {
  /** A rule id from the digest's vocabulary, or null for "nothing to report". */
  ruleId: string | null;
  confidence: number;
  note?: string;
}

const SYSTEM_PROMPT = `You audit an AI coding agent for violations of Claude Code's conventions.
You receive a JSON digest: the tools available, detected harness state, and the tool call the agent proposes.
Decide whether the proposed call violates one of the rules listed in ruleVocabulary.

Reply with ONLY a JSON object, no prose:
{"ruleId": "<id from ruleVocabulary, or null>", "confidence": <0-1>, "note": "<short reason>"}

Return ruleId null unless you are confident. A false positive is worse than a miss.`;

/**
 * Floor below which a reported size cannot be a real set of local weights.
 *
 * Ollama lists CLOUD-hosted models alongside local ones, and a cloud entry is a
 * stub: `gemma4:31b-cloud` reports 312 BYTES. "Smallest wins" therefore picked a
 * 31B model served over the network, which promptly blew the observer's timeout
 * — measured live, 2026-08-02. The observer's whole premise is a fast local
 * model, so a stub must never win.
 */
const MIN_LOCAL_MODEL_BYTES = 50 * 1024 * 1024;

/** Reject cloud-hosted entries by both name and implausible size. */
function isGenuinelyLocal(model: { name: string; size?: number }): boolean {
  if (/[-:]cloud$/i.test(model.name)) return false;
  return (model.size ?? 0) >= MIN_LOCAL_MODEL_BYTES;
}

/** Resolved once per process — discovery costs an HTTP round trip. */
let cachedModel: string | null | undefined;

async function resolveObserverModel(config: ObserverConfig): Promise<string | null> {
  if (config.observer?.model) return config.observer.model;
  if (cachedModel !== undefined) return cachedModel;

  try {
    const models = await fetchOllamaModels({ enrichCapabilities: false });
    const usable = models.filter((m) => !m.isEmbeddingModel && isGenuinelyLocal(m));
    if (usable.length === 0) {
      log("[hooks:observer] No local Ollama models found — observer disabled for this run");
      cachedModel = null;
      return null;
    }
    // Smallest wins: the observer runs alongside a live request, so it has to be
    // cheap. A model with no reported size sorts last rather than winning by 0.
    usable.sort(
      (a, b) => (a.size ?? Number.MAX_SAFE_INTEGER) - (b.size ?? Number.MAX_SAFE_INTEGER)
    );
    cachedModel = usable[0].name;
    log(`[hooks:observer] Using discovered local model: ${cachedModel}`);
    return cachedModel;
  } catch (err) {
    log(`[hooks:observer] Model discovery failed, observer disabled: ${err}`);
    cachedModel = null;
    return null;
  }
}

/** Test seam: forget the discovered model so the next call re-resolves. */
export function resetObserverModelCache(): void {
  cachedModel = undefined;
}

/**
 * Ask the observer about a digest.
 *
 * @returns a verdict, or null when the observer is unavailable/unsure/malformed.
 */
export async function observe(
  digest: ObserverDigest,
  config: ObserverConfig
): Promise<ObserverVerdict | null> {
  const mode = config.observer?.mode ?? "suggest";
  if (config.observer?.enabled !== true || mode === "off") return null;

  const model = await resolveObserverModel(config);
  if (!model) return null;

  const timeoutMs = config.observer?.timeoutMs ?? DEFAULT_TIMEOUT_MS;

  try {
    const response = await fetch(`${ollamaBaseUrl()}/api/chat`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      signal: AbortSignal.timeout(timeoutMs),
      body: JSON.stringify({
        model,
        stream: false,
        format: "json",
        options: { temperature: 0 },
        messages: [
          { role: "system", content: SYSTEM_PROMPT },
          { role: "user", content: JSON.stringify(digest) },
        ],
      }),
    });
    if (!response.ok) {
      log(`[hooks:observer] HTTP ${response.status} — skipping`);
      return null;
    }

    const body: any = await response.json();
    const content = body?.message?.content;
    if (typeof content !== "string") return null;

    const parsed = JSON.parse(content);
    const ruleId = typeof parsed?.ruleId === "string" ? parsed.ruleId : null;

    // An id outside the vocabulary is a hallucination. Drop it rather than let
    // an invented rule name reach the engine or the divergence log.
    if (ruleId && !digest.ruleVocabulary.includes(ruleId)) {
      log(`[hooks:observer] Discarding unknown ruleId "${ruleId}"`);
      return null;
    }

    return {
      ruleId,
      confidence: typeof parsed?.confidence === "number" ? parsed.confidence : 0,
      note: typeof parsed?.note === "string" ? parsed.note : undefined,
    };
  } catch (err) {
    // Timeouts are the expected failure here, not an exceptional one.
    log(`[hooks:observer] Skipped: ${err instanceof Error ? err.message : err}`);
    return null;
  }
}