peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/reviewer/model-family.d.ts

@@ -0,0 +1,18 @@
+export type ModelFamilyDerivation = {
+    modelId: string;
+    modelFamily: string;
+    source: 'rule' | 'fallback-hash';
+};
+/**
+ * Resolve a modelId to its provider-family bucket. Pure, deterministic,
+ * and total (returns `unknown-<slug>` for unrecognised ids). The slug
+ * is the first 8 hex chars of the sha256 of the lowercased modelId —
+ * stable across processes and stable across minor version bumps.
+ */
+export declare function deriveModelFamily(modelId: string): ModelFamilyDerivation;
+/**
+ * Convenience: returns only the family string. Use `deriveModelFamily`
+ * when the caller also wants to know whether a rule matched or whether
+ * the fallback path was taken.
+ */
+export declare function modelFamily(modelId: string): string;

package/dist/services/reviewer/model-family.js

@@ -0,0 +1,70 @@
+/**
+ * model-family.ts — derive `modelFamily` from a `modelId` for the G4
+ * third-party reviewer. AC-4.4 requires that
+ * `third-party-review.json.modelFamily !== karpathy-review.json.modelFamily`,
+ * so the family bucket must be stable, provider-distinguishing, and
+ * version-tolerant (e.g. `claude-opus-4-8` and `claude-haiku-4-5` both
+ * bucket to `claude`, while `gpt-4o-mini` and `gpt-3.5-turbo` bucket
+ * separately).
+ *
+ * Karpathy §2 — minimum code that solves the problem. We pattern-match
+ * on a small set of well-known vendor prefixes. Anything that does not
+ * match falls into an `unknown-<slug>` bucket so the family remains
+ * distinct-by-default (two unknown models still hash to different
+ * families).
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Stable prefix-ordered rules. First match wins. Order matters: more
+ * specific prefixes (e.g. `bedrock/.../claude-...`) MUST precede the
+ * generic family rule they overlap with (e.g. `claude`), otherwise the
+ * generic rule shadows them.
+ */
+const RULES = [
+    // Anthropic (incl. bedrock-hosted anthropic) — most specific first.
+    { family: 'claude', test: (m) => /^(claude|anthropic\.)/i.test(m) || /^anthropic\.claude-/i.test(m) || /^us\.anthropic\./i.test(m) || /^bedrock\/.+\/claude-/i.test(m) },
+    // OpenAI / o-series — order: most specific prefix first.
+    { family: 'gpt-5', test: (m) => /^gpt-5/i.test(m) },
+    { family: 'gpt-4o', test: (m) => /^gpt-4o/i.test(m) },
+    { family: 'gpt-4', test: (m) => /^gpt-4/i.test(m) },
+    { family: 'gpt-3.5', test: (m) => /^gpt-3\.5/i.test(m) },
+    { family: 'o1', test: (m) => /^o1/i.test(m) },
+    { family: 'o3', test: (m) => /^o3/i.test(m) },
+    { family: 'azure-openai', test: (m) => /azure/i.test(m) && /openai|gpt/i.test(m) },
+    // Vertex / Bedrock non-anthropic — MUST precede generic llama/mistral rules.
+    { family: 'bedrock-llama', test: (m) => /bedrock/i.test(m) && /llama/i.test(m) },
+    { family: 'bedrock-mistral', test: (m) => /bedrock/i.test(m) && /mistral/i.test(m) },
+    // Local / ollama families.
+    { family: 'llama', test: (m) => /llama/i.test(m) },
+    { family: 'mistral', test: (m) => /mistral|mixtral/i.test(m) },
+    { family: 'qwen', test: (m) => /qwen/i.test(m) },
+    { family: 'deepseek', test: (m) => /deepseek/i.test(m) },
+    { family: 'gemini', test: (m) => /gemini/i.test(m) }
+];
+/**
+ * Resolve a modelId to its provider-family bucket. Pure, deterministic,
+ * and total (returns `unknown-<slug>` for unrecognised ids). The slug
+ * is the first 8 hex chars of the sha256 of the lowercased modelId —
+ * stable across processes and stable across minor version bumps.
+ */
+export function deriveModelFamily(modelId) {
+    const trimmed = modelId.trim();
+    if (trimmed.length === 0) {
+        return { modelId, modelFamily: 'unknown-empty', source: 'fallback-hash' };
+    }
+    for (const rule of RULES) {
+        if (rule.test(trimmed)) {
+            return { modelId, modelFamily: rule.family, source: 'rule' };
+        }
+    }
+    const slug = createHash('sha256').update(trimmed.toLowerCase()).digest('hex').slice(0, 8);
+    return { modelId, modelFamily: `unknown-${slug}`, source: 'fallback-hash' };
+}
+/**
+ * Convenience: returns only the family string. Use `deriveModelFamily`
+ * when the caller also wants to know whether a rule matched or whether
+ * the fallback path was taken.
+ */
+export function modelFamily(modelId) {
+    return deriveModelFamily(modelId).modelFamily;
+}

package/dist/services/reviewer/providers/anthropic.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderCallInput, ProviderCallResult } from './ollama.js';
+export declare function callAnthropic(input: ProviderCallInput): Promise<ProviderCallResult>;

package/dist/services/reviewer/providers/anthropic.js

@@ -0,0 +1,61 @@
+const ANTHROPIC_ENDPOINT = 'https://api.anthropic.com/v1/messages';
+const ANTHROPIC_VERSION = '2023-06-08';
+const REQUEST_TIMEOUT_MS = 30_000;
+const DEFAULT_API_KEY_ENV = 'ANTHROPIC_API_KEY';
+const MAX_TOKENS = 1024;
+export async function callAnthropic(input) {
+    const start = Date.now();
+    const envVar = input.provider.apiKeyEnv ?? DEFAULT_API_KEY_ENV;
+    const apiKey = process.env[envVar];
+    if (!apiKey) {
+        return { ok: false, error: `missing env ${envVar}`, latencyMs: Date.now() - start };
+    }
+    const fetchImpl = input.fetchImpl ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    const signal = input.signal ?? controller.signal;
+    try {
+        const res = await fetchImpl(ANTHROPIC_ENDPOINT, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-api-key': apiKey,
+                'anthropic-version': ANTHROPIC_VERSION
+            },
+            body: JSON.stringify({
+                model: input.provider.model,
+                max_tokens: MAX_TOKENS,
+                messages: [{ role: 'user', content: input.prompt }]
+            }),
+            signal
+        });
+        if (!res.ok) {
+            const detail = await safeReadError(res);
+            return { ok: false, error: `anthropic http ${res.status}: ${detail}`, latencyMs: Date.now() - start };
+        }
+        const json = (await res.json());
+        const textBlock = (json.content ?? []).find((b) => b.type === 'text' && typeof b.text === 'string');
+        const text = typeof textBlock?.text === 'string' ? textBlock.text : '';
+        return { ok: true, modelId: input.provider.model, text, latencyMs: Date.now() - start };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `anthropic ${err instanceof Error ? err.message : String(err)}`,
+            latencyMs: Date.now() - start
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function safeReadError(res) {
+    try {
+        const body = (await res.json());
+        const msg = body.error?.message;
+        return typeof msg === 'string' ? msg.slice(0, 200) : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/services/reviewer/providers/ollama.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ollama provider — local ollama daemon at `endpoint` (default
+ * http://localhost:11434). Uses ollama's `/api/chat` endpoint which is
+ * OpenAI-compatible at the message-shape level. Pure fetch + JSON —
+ * no SDK, per A4 prohibition on heavy deps.
+ */
+import type { ReviewerProviderConfig } from '../reviewer-config.js';
+export type ProviderCallInput = {
+    provider: ReviewerProviderConfig;
+    prompt: string;
+    /** Caller injects fetch for testability. Defaults to globalThis.fetch. */
+    fetchImpl?: typeof fetch | undefined;
+    /** AbortSignal for timeout control (callers should set one). */
+    signal?: AbortSignal | undefined;
+};
+export type ProviderCallResult = {
+    ok: true;
+    modelId: string;
+    text: string;
+    latencyMs: number;
+} | {
+    ok: false;
+    error: string;
+    latencyMs: number;
+};
+export declare function callOllama(input: ProviderCallInput): Promise<ProviderCallResult>;

package/dist/services/reviewer/providers/ollama.js

@@ -0,0 +1,38 @@
+const DEFAULT_OLLAMA_ENDPOINT = 'http://localhost:11434';
+const REQUEST_TIMEOUT_MS = 30_000;
+export async function callOllama(input) {
+    const start = Date.now();
+    const endpoint = (input.provider.endpoint ?? DEFAULT_OLLAMA_ENDPOINT).replace(/\/$/, '');
+    const fetchImpl = input.fetchImpl ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    const signal = input.signal ?? controller.signal;
+    try {
+        const res = await fetchImpl(`${endpoint}/api/chat`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                model: input.provider.model,
+                stream: false,
+                messages: [{ role: 'user', content: input.prompt }]
+            }),
+            signal
+        });
+        if (!res.ok) {
+            return { ok: false, error: `ollama http ${res.status}`, latencyMs: Date.now() - start };
+        }
+        const json = (await res.json());
+        const text = typeof json.message?.content === 'string' ? json.message.content : '';
+        return { ok: true, modelId: input.provider.model, text, latencyMs: Date.now() - start };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `ollama ${err instanceof Error ? err.message : String(err)}`,
+            latencyMs: Date.now() - start
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/services/reviewer/providers/openai.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderCallInput, ProviderCallResult } from './ollama.js';
+export declare function callOpenAI(input: ProviderCallInput): Promise<ProviderCallResult>;

package/dist/services/reviewer/providers/openai.js

@@ -0,0 +1,63 @@
+const DEFAULT_ENDPOINT = 'https://api.openai.com/v1/chat/completions';
+const DEFAULT_API_KEY_ENV = 'OPENAI_API_KEY';
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_TOKENS = 1024;
+const TEMPERATURE = 0;
+export async function callOpenAI(input) {
+    const start = Date.now();
+    const envVar = input.provider.apiKeyEnv ?? DEFAULT_API_KEY_ENV;
+    const apiKey = process.env[envVar];
+    if (!apiKey) {
+        return { ok: false, error: `missing env ${envVar}`, latencyMs: Date.now() - start };
+    }
+    const endpoint = input.provider.endpoint ?? DEFAULT_ENDPOINT;
+    const fetchImpl = input.fetchImpl ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    const signal = input.signal ?? controller.signal;
+    try {
+        const res = await fetchImpl(endpoint, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${apiKey}`
+            },
+            body: JSON.stringify({
+                model: input.provider.model,
+                max_tokens: MAX_TOKENS,
+                temperature: TEMPERATURE,
+                messages: [{ role: 'user', content: input.prompt }]
+            }),
+            signal
+        });
+        if (!res.ok) {
+            const detail = await safeReadError(res);
+            return { ok: false, error: `openai http ${res.status}: ${detail}`, latencyMs: Date.now() - start };
+        }
+        const json = (await res.json());
+        const text = typeof json.choices?.[0]?.message?.content === 'string'
+            ? json.choices[0].message.content
+            : '';
+        return { ok: true, modelId: input.provider.model, text, latencyMs: Date.now() - start };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `openai ${err instanceof Error ? err.message : String(err)}`,
+            latencyMs: Date.now() - start
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function safeReadError(res) {
+    try {
+        const body = (await res.json());
+        const msg = body.error?.message;
+        return typeof msg === 'string' ? msg.slice(0, 200) : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/services/reviewer/reviewer-config.d.ts

@@ -0,0 +1,34 @@
+export type ReviewerProviderName = 'ollama' | 'anthropic' | 'openai' | 'bedrock' | 'azure';
+export type ReviewerProviderConfig = {
+    name: ReviewerProviderName | string;
+    model: string;
+    endpoint?: string | undefined;
+    apiKeyEnv?: string | undefined;
+};
+export type ReviewerSelectionMode = 'round-robin' | 'hash' | 'random';
+export type ReviewerFallbackMode = 'skip' | 'error';
+export type ReviewerConfig = {
+    providers: ReadonlyArray<ReviewerProviderConfig>;
+    selection: ReviewerSelectionMode;
+    rdProviderName: string | null;
+    requireDistinctModelFamily: boolean;
+    fallbackOnError: ReviewerFallbackMode;
+    schemaPath: string;
+};
+export type ReviewerConfigStatus = {
+    ok: true;
+    config: ReviewerConfig;
+} | {
+    ok: false;
+    reason: 'no-reviewer-config';
+};
+export declare function defaultReviewerConfigPath(): string;
+/**
+ * Read + parse `~/.peaks/config.json` (or override path) and return the
+ * `reviewer` section if present. NEVER throws on missing file — returns
+ * `{ ok: false, reason: 'no-reviewer-config' }` instead so the CLI can
+ * record the skip reason in the envelope.
+ */
+export declare function loadReviewerConfig(options?: {
+    path?: string;
+}): ReviewerConfigStatus;

package/dist/services/reviewer/reviewer-config.js

@@ -0,0 +1,100 @@
+/**
+ * reviewer-config.ts — load the `reviewer` section from
+ * `~/.peaks/config.json`. AC-4.1 mandates:
+ *   - providers[] (>=2 entries; ollama / anthropic / openai supported)
+ *   - selection: 'round-robin' | 'hash(rid)' | 'random'
+ *   - rdProviderName: string | null
+ *   - requireDistinctModelFamily: boolean (default true)
+ *   - fallbackOnError: 'skip' | 'error'
+ *   - schemaPath: string (default 'schemas/reviewer-envelope.schema.json')
+ *
+ * Missing section => the reviewer is OFF (transition still passes; envelope
+ * records `skipped: no-reviewer-config`). The CLI never silently prompts for
+ * API keys; missing env vars surface as `providerUnavailable` and the
+ * fallbackOnError policy decides whether to skip or throw.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const VALID_SELECTION = ['round-robin', 'hash', 'random'];
+const VALID_FALLBACK = ['skip', 'error'];
+export function defaultReviewerConfigPath() {
+    return join(homedir(), '.peaks', 'config.json');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Read + parse `~/.peaks/config.json` (or override path) and return the
+ * `reviewer` section if present. NEVER throws on missing file — returns
+ * `{ ok: false, reason: 'no-reviewer-config' }` instead so the CLI can
+ * record the skip reason in the envelope.
+ */
+export function loadReviewerConfig(options = {}) {
+    const path = options.path ?? defaultReviewerConfigPath();
+    if (!existsSync(path)) {
+        return { ok: false, reason: 'no-reviewer-config' };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return { ok: false, reason: 'no-reviewer-config' };
+    }
+    if (!isRecord(raw))
+        return { ok: false, reason: 'no-reviewer-config' };
+    const reviewer = raw['reviewer'];
+    if (!isRecord(reviewer))
+        return { ok: false, reason: 'no-reviewer-config' };
+    const providersRaw = reviewer['providers'];
+    if (!Array.isArray(providersRaw) || providersRaw.length < 2) {
+        // A4.1 explicitly requires >=2 providers; with <2 we treat the
+        // section as absent so the reviewer is skipped cleanly.
+        return { ok: false, reason: 'no-reviewer-config' };
+    }
+    const providers = [];
+    for (const entry of providersRaw) {
+        if (!isRecord(entry))
+            continue;
+        const name = entry['name'];
+        const model = entry['model'];
+        if (typeof name !== 'string' || typeof model !== 'string')
+            continue;
+        providers.push({
+            name,
+            model,
+            endpoint: typeof entry['endpoint'] === 'string' ? entry['endpoint'] : undefined,
+            apiKeyEnv: typeof entry['apiKeyEnv'] === 'string' ? entry['apiKeyEnv'] : undefined
+        });
+    }
+    if (providers.length < 2)
+        return { ok: false, reason: 'no-reviewer-config' };
+    const selectionRaw = reviewer['selection'];
+    const selection = typeof selectionRaw === 'string' && VALID_SELECTION.includes(selectionRaw)
+        ? selectionRaw
+        : 'round-robin';
+    const fallbackRaw = reviewer['fallbackOnError'];
+    const fallbackOnError = typeof fallbackRaw === 'string' && VALID_FALLBACK.includes(fallbackRaw)
+        ? fallbackRaw
+        : 'skip';
+    const rdProviderNameRaw = reviewer['rdProviderName'];
+    const rdProviderName = rdProviderNameRaw === null || typeof rdProviderNameRaw === 'string' ? rdProviderNameRaw : null;
+    const requireDistinct = reviewer['requireDistinctModelFamily'];
+    const requireDistinctModelFamily = typeof requireDistinct === 'boolean' ? requireDistinct : true;
+    const schemaPathRaw = reviewer['schemaPath'];
+    const schemaPath = typeof schemaPathRaw === 'string' && schemaPathRaw.length > 0
+        ? schemaPathRaw
+        : 'schemas/reviewer-envelope.schema.json';
+    return {
+        ok: true,
+        config: {
+            providers,
+            selection,
+            rdProviderName,
+            requireDistinctModelFamily,
+            fallbackOnError,
+            schemaPath
+        }
+    };
+}

package/dist/services/reviewer/reviewer-service.d.ts

@@ -0,0 +1,56 @@
+import { type SelectionState } from './selection-strategies.js';
+export type ReviewerViolation = {
+    kind: string;
+    file: string;
+    line: number;
+    hint: string;
+};
+export type ReviewerEnvelope = {
+    reviewerId: string;
+    modelId: string;
+    modelFamily: string;
+    passed: boolean;
+    violations: ReviewerViolation[];
+    gateAction: 'block' | 'allow' | 'warn';
+    reason: string;
+};
+export type ReviewerRunInput = {
+    rid: string;
+    /** Slice context blob fed to the prompt. Plain text — no PII (A1.5). */
+    context: string;
+    /** Optional override of the selection-mode state for cross-slice round-robin. */
+    state?: SelectionState;
+    /** Optional injected fetch (testability). */
+    fetchImpl?: typeof fetch;
+    /** Optional injected rng (random mode tests). */
+    rng?: () => number;
+};
+export type ReviewerRunOutput = {
+    ok: true;
+    envelope: ReviewerEnvelope;
+    nextState: SelectionState;
+} | {
+    ok: false;
+    reason: 'no-reviewer-config';
+    envelope: ReviewerEnvelope;
+};
+export declare const REVIEWER_ID = "third-party-reviewer-v2.14.0";
+/**
+ * Validate a parsed JSON value against the ReviewerEnvelope contract
+ * (mirrors `schemas/reviewer-envelope.schema.json`). Returns the
+ * normalized envelope on success, or null when the input is malformed.
+ */
+export declare function validateReviewerEnvelope(value: unknown): ReviewerEnvelope | null;
+/**
+ * Try to extract the first JSON object from an LLM text response.
+ * Many LLMs wrap JSON in ```json fences or surrounding prose; we
+ * tolerate both. Returns null when no JSON object is present.
+ */
+export declare function extractFirstJsonObject(text: string): unknown | null;
+export declare function runReviewer(input: ReviewerRunInput): Promise<ReviewerRunOutput>;
+/**
+ * Compute the distinctness verdict: returns true when the third-party
+ * reviewer's modelFamily differs from the karpathy reviewer's. AC-4.4
+ * mandates this is a CI gate — equality fails the build.
+ */
+export declare function distinctFromKarpathy(thirdPartyFamily: string, karpathyFamily: string): boolean;