onto-mcp 0.4.11 → 0.4.13

package/dist/core-runtime/effort-calibration-reconstruct.js

@@ -0,0 +1,47 @@
+/**
+ * Reconstruct effort-calibration adapter (P3). Distills a reconstruct
+ * golden-fixture quality-gate result into the pipeline-agnostic gate signal the
+ * sweep aggregator consumes.
+ *
+ * Reconstruct quality is golden-fixture-anchored and pipeline-WIDE: a sweep run
+ * pins one effort knob — the global semantic-author effort (the "author" stage)
+ * or the answer-support judge effort (the "judge" stage) — and measures the
+ * whole-run golden gate, attributing the result to that stage. The "gate" is the
+ * golden gate's overall pass; "quality" is a continuous 0..1 "finding 양·질"
+ * proxy synthesized from the gate's three optimization axes:
+ *   - Q1 expected-concept recall (양·질 of the authored seed),
+ *   - Q2 competency-question support rate, and
+ *   - Q3 dropped-question health (fraction of authored questions still assessed;
+ *     the runtime batches instead of dropping, so this is normally 1.0).
+ * Each axis is a 0..1 health fraction; equal-weight mean keeps the score on the
+ * same scale as the review adapter's check-pass fraction. The binary pass/fail
+ * stays owned by `passed`; this score only feeds the frontier's plateau search.
+ *
+ * A run that produced no quality verdict — `rejected` (missing telemetry
+ * provenance) or `not_applicable` (mock realization incompatible with the
+ * fixture) — yields passed=null and qualityScore=null, mirroring review's
+ * unjudged treatment: non-passing in the quorum and contributing no quality.
+ *
+ * Pure — no live LLM and no IO; aggregation and report assembly live in
+ * `effort-calibration-sweep.ts`.
+ */
+/** Q3 as a 0..1 health fraction: share of authored questions still assessed. */
+function q3Health(q3) {
+    const authored = q3.authored_question_count;
+    if (authored <= 0)
+        return 1; // no questions to drop → vacuously healthy
+    const kept = authored - q3.dropped_question_count;
+    return Math.max(0, Math.min(1, kept / authored));
+}
+/** Distill the calibration gate signal from a reconstruct golden gate result. */
+export function reconstructRunGateSignal(gate) {
+    // passed/failed are the only quality verdicts; rejected/not_applicable mean no
+    // verdict was produced (provenance reject or mock-incompatible fixture) → null.
+    const passed = gate.status === "passed" ? true : gate.status === "failed" ? false : null;
+    // q1/q2/q3 are populated together (passed/failed) or absent together
+    // (rejected/not_applicable); a verdict without metrics leaves quality null.
+    const qualityScore = gate.q1 && gate.q2 && gate.q3
+        ? (gate.q1.recall + gate.q2.support_rate + q3Health(gate.q3)) / 3
+        : null;
+    return { passed, qualityScore };
+}

package/dist/core-runtime/effort-calibration-review.js

@@ -0,0 +1,22 @@
+/**
+ * Review effort-calibration adapter (P2). Distills a review unit-sweep run's
+ * whole-review semantic quality gate into the pipeline-agnostic gate signal the
+ * sweep aggregator consumes.
+ *
+ * Review quality is review-WIDE and fixture-anchored: the unit-sweep varies one
+ * LLM unit's effort over a fixed base effort and measures the whole-review
+ * semantic quality gate, attributing the result to that unit. So the swept
+ * review unit is the "stage", the "gate" is the gate's overall pass, and
+ * "quality" is the fraction of the 12-check gate that passed (a continuous 0..1
+ * "finding 양·질" proxy). Pure — no live LLM and no IO; aggregation and report
+ * assembly live in `effort-calibration-sweep.ts`.
+ */
+/** Distill the calibration gate signal from a full semantic-quality-gate result. */
+export function reviewRunGateSignal(gate) {
+    const passed = gate.status === "not_applicable" ? null : gate.status === "passed";
+    const total = gate.checks.length;
+    const qualityScore = total
+        ? gate.checks.filter((c) => c.status === "passed").length / total
+        : null;
+    return { passed, qualityScore };
+}

package/dist/core-runtime/effort-calibration-sweep.js

@@ -0,0 +1,110 @@
+/**
+ * Effort-calibration sweep aggregation — pipeline-agnostic.
+ *
+ * A sweep run is one (swept stage, candidate effort) trial whose result has been
+ * distilled to a gate signal by a pipeline-specific adapter (review or
+ * reconstruct). This module owns the part that does NOT depend on the pipeline:
+ * grouping runs into per-stage per-effort buckets, aggregating each bucket into
+ * the `EffortSample` series the frontier classifier consumes, and assembling the
+ * per-model report. The pipeline adapters own only the gate-signal distillation
+ * (their gate result types differ); the frontier classifier owns the decision.
+ *
+ * Pure — no live LLM and no IO. The sweep harness (scripts/) supplies the runs
+ * and writes the report artifact.
+ */
+import { classifyEffortCalibration, } from "./effort-frontier.js";
+const mean = (xs) => xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+const stdev = (xs) => {
+    if (xs.length < 2)
+        return 0;
+    const m = mean(xs);
+    return Math.sqrt(mean(xs.map((x) => (x - m) ** 2)));
+};
+const meanCost = (costs) => {
+    if (costs.length === 0)
+        return undefined;
+    const avg = (pick) => {
+        const vals = costs
+            .map(pick)
+            .filter((v) => typeof v === "number");
+        return vals.length ? mean(vals) : undefined;
+    };
+    const promptChars = avg((c) => c.promptChars);
+    const outputChars = avg((c) => c.outputChars);
+    const providerTokens = avg((c) => c.providerTokens);
+    const durationMs = avg((c) => c.durationMs);
+    const out = {};
+    if (promptChars !== undefined)
+        out.promptChars = promptChars;
+    if (outputChars !== undefined)
+        out.outputChars = outputChars;
+    if (providerTokens !== undefined)
+        out.providerTokens = providerTokens;
+    if (durationMs !== undefined)
+        out.durationMs = durationMs;
+    return out;
+};
+/**
+ * Aggregate sweep runs into per-stage EffortSample series, each ordered
+ * ascending by `effortOrder` (efforts absent from the order are dropped — no
+ * silent reordering). Stages are sorted by id for a deterministic report.
+ *
+ * Unjudged (passed === null) runs count as NON-passing in gatePassRate: an
+ * effort can only clear the quorum if every run produced a passing verdict, so a
+ * bucket that mixes a pass with an unjudged/mock run is downgraded rather than
+ * given a free pass (the denominator is the full run count, matching `runs`).
+ * Quality is averaged only over runs whose gate produced a score.
+ */
+export function aggregateEffortSweep(runs, effortOrder) {
+    const rank = new Map(effortOrder.map((e, i) => [e, i]));
+    const byStage = new Map();
+    for (const r of runs) {
+        if (!rank.has(r.effort))
+            continue; // effort not in canonical order → drop
+        let byEffort = byStage.get(r.stage);
+        if (!byEffort) {
+            byEffort = new Map();
+            byStage.set(r.stage, byEffort);
+        }
+        const list = byEffort.get(r.effort) ?? [];
+        list.push(r);
+        byEffort.set(r.effort, list);
+    }
+    const stages = [...byStage.entries()].map(([stage, byEffort]) => {
+        const samples = [...byEffort.entries()].map(([effort, group]) => {
+            // Denominator is the full run count: unjudged (passed === null) runs are
+            // non-passing so missing scored evidence cannot overstate viability.
+            const passedRuns = group.filter((r) => r.gate.passed === true).length;
+            const gatePassRate = group.length ? passedRuns / group.length : 0;
+            const qualities = group
+                .map((r) => r.gate.qualityScore)
+                .filter((q) => typeof q === "number");
+            const cost = meanCost(group
+                .map((r) => r.cost)
+                .filter((c) => c !== undefined));
+            return {
+                effort,
+                gatePassRate,
+                quality: mean(qualities),
+                qualityStdev: stdev(qualities),
+                runs: group.length,
+                ...(cost ? { cost } : {}),
+            };
+        });
+        samples.sort((a, b) => rank.get(a.effort) - rank.get(b.effort));
+        return { stage, samples };
+    });
+    stages.sort((a, b) => (a.stage < b.stage ? -1 : a.stage > b.stage ? 1 : 0));
+    return stages;
+}
+/** Build a per-model effort-calibration report from sweep runs (pure). */
+export function buildEffortCalibrationReport(args) {
+    return classifyEffortCalibration({
+        pipeline: args.pipeline,
+        provider: args.provider,
+        model: args.model,
+        route: args.route,
+        thresholds: args.thresholds,
+        stages: aggregateEffortSweep(args.runs, args.effortOrder),
+    });
+}

package/dist/core-runtime/effort-frontier.js

@@ -0,0 +1,134 @@
+/**
+ * Effort frontier calibration — pure, deterministic core.
+ *
+ * For each LLM stage of a pipeline (review or reconstruct), given a series of
+ * per-effort aggregated samples (one per effort level, aggregated over N runs),
+ * classify the reasoning-effort frontier:
+ *
+ *   - minViableEffort    — the lowest effort whose gate passes (>= passQuorum of
+ *                          runs). Below it the stage fails.
+ *   - effectiveMaxEffort — the lowest gate-passing effort beyond which no higher
+ *                          effort improves quality by more than plateauThreshold
+ *                          (the knee of the cost/quality curve). Above it more
+ *                          effort buys ~nothing.
+ *   - recommendedEffort  — effectiveMaxEffort: the cheapest effort at the quality
+ *                          plateau that still passes the gate.
+ *
+ * Pipeline-agnostic: callers supply already-aggregated samples (quality is a
+ * pipeline-defined "finding 양·질" metric, higher = better) in ascending effort
+ * order. No live LLM calls and no I/O — fully unit-testable. The benchmark/sweep
+ * harnesses (scripts/) produce the samples; this module decides the frontier and
+ * assembles the per-model calibration record that is re-run per new model.
+ */
+const DEFAULT_PASS_QUORUM = 1;
+// Tolerance for the plateau comparison. Quality deltas from averaged 0..1
+// metrics carry float noise (e.g. 0.90 - 0.85 === 0.050000000000000044), so a
+// gain mathematically equal to the threshold must NOT count as an improvement —
+// the contract treats gains at or below the threshold as a plateau.
+const QUALITY_EPSILON = 1e-9;
+const curveOf = (samples) => samples.map((s) => ({
+    effort: s.effort,
+    gatePassRate: s.gatePassRate,
+    quality: s.quality,
+    qualityStdev: s.qualityStdev,
+    runs: s.runs,
+    ...(s.cost ? { cost: s.cost } : {}),
+}));
+/**
+ * Classify the effort frontier for one stage. `samples` must be in ascending
+ * effort order (cheapest first); the caller owns the effort ordering.
+ */
+export function classifyStageFrontier(stage, samples, thresholds) {
+    const passQuorum = thresholds.passQuorum ?? DEFAULT_PASS_QUORUM;
+    const plateau = thresholds.plateauThreshold;
+    const curve = curveOf(samples);
+    if (samples.length === 0) {
+        return {
+            stage,
+            minViableEffort: null,
+            effectiveMaxEffort: null,
+            recommendedEffort: null,
+            plateauReached: false,
+            rationale: "no samples provided",
+            curve,
+        };
+    }
+    // min viable: the lowest effort whose gate clears the quorum.
+    const minViableIdx = samples.findIndex((s) => s.gatePassRate >= passQuorum);
+    if (minViableIdx === -1) {
+        return {
+            stage,
+            minViableEffort: null,
+            effectiveMaxEffort: null,
+            recommendedEffort: null,
+            plateauReached: false,
+            rationale: `gate never reaches passQuorum=${passQuorum} at any tested effort`,
+            curve,
+        };
+    }
+    // candidates: gate-passing efforts at or above min viable, ascending. (A
+    // higher effort can dip below the quorum, e.g. overthinking; such efforts are
+    // not viable recommendations and are excluded from the plateau search.)
+    const candidates = samples
+        .slice(minViableIdx)
+        .filter((s) => s.gatePassRate >= passQuorum);
+    // effective max: the lowest candidate whose quality is not beaten by more than
+    // the plateau threshold by ANY higher candidate (checking all higher ones, not
+    // just the adjacent, makes this robust to non-monotonic noise). The highest
+    // candidate satisfies this vacuously, so a result always exists.
+    let effIdx = candidates.length - 1;
+    for (let i = 0; i < candidates.length; i++) {
+        const base = candidates[i].quality;
+        const beatenLater = candidates
+            .slice(i + 1)
+            .some((c) => c.quality - base > plateau + QUALITY_EPSILON);
+        if (!beatenLater) {
+            effIdx = i;
+            break;
+        }
+    }
+    const minViable = samples[minViableIdx].effort;
+    const effective = candidates[effIdx].effort;
+    const highestViable = candidates[candidates.length - 1].effort;
+    const plateauReached = candidates.length > 1 && effective !== highestViable;
+    let rationale;
+    if (candidates.length === 1) {
+        rationale = `only "${minViable}" is viable in the tested range; plateau indeterminate`;
+    }
+    else if (plateauReached) {
+        rationale = `gate first passes at "${minViable}"; quality plateaus at "${effective}" (no higher effort gains >${plateau})`;
+    }
+    else {
+        rationale = `gate first passes at "${minViable}"; quality still climbing at the top of the viable range "${highestViable}" — plateau not captured; re-run with higher effort if available`;
+    }
+    return {
+        stage,
+        minViableEffort: minViable,
+        effectiveMaxEffort: effective,
+        recommendedEffort: effective,
+        plateauReached,
+        rationale,
+        curve,
+    };
+}
+/**
+ * Assemble a per-model calibration record from per-stage sample series. The
+ * caller (harness) stamps identity/time metadata when serializing the artifact;
+ * this function stays deterministic (no clock, no I/O).
+ */
+export function classifyEffortCalibration(args) {
+    return {
+        pipeline: args.pipeline,
+        provider: args.provider,
+        model: args.model,
+        route: args.route,
+        // Persist the *effective* thresholds (resolve the default quorum) so a
+        // serialized record is self-describing — a reader/replay can tell an
+        // all-runs quorum from a relaxed one without knowing this module's default.
+        thresholds: {
+            passQuorum: args.thresholds.passQuorum ?? DEFAULT_PASS_QUORUM,
+            plateauThreshold: args.thresholds.plateauThreshold,
+        },
+        stages: args.stages.map((s) => classifyStageFrontier(s.stage, s.samples, args.thresholds)),
+    };
+}

package/dist/core-runtime/llm/claude-bin.js

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Resolve the Claude Code CLI binary path, accommodating per-user install
+ * locations. Anthropic OAuth review/reconstruct workers spawn this binary, and
+ * its location varies by machine and install method — and a host like Claude
+ * Desktop may launch the server with a minimal `PATH` that does not include the
+ * user's `claude`. So a bare `spawn("claude")` is not reliable across users.
+ *
+ * Resolution order (first hit wins):
+ *   1. `ONTO_CLAUDE_BIN` — explicit operator override (absolute path or name).
+ *   2. `claude` discoverable on `PATH` (as an executable file — shell aliases
+ *      and functions are never consulted because spawn does not use them).
+ *   3. Common Claude Code install locations (native installer, older local
+ *      install, Homebrew).
+ *   4. The literal `"claude"` — so `spawn` fails with the existing actionable
+ *      ENOENT message ("Claude Code CLI not found … set ONTO_CLAUDE_BIN") rather
+ *      than this resolver inventing a different error.
+ *
+ * Pure function of `env`: resolution is a handful of `stat`/`access` syscalls and
+ * each call site invokes it at most once per spawn (or once at module load), so
+ * it is NOT cached — a cache keyed on nothing would return a stale path when a
+ * later call passes a different `env.PATH` (the injected `env` would silently
+ * stop controlling discovery). The same applies to the codex OAuth direct route
+ * (`callCodexCli` still spawns a bare `"codex"`); extending this resolver to
+ * codex is a symmetric, deferred follow-up.
+ */
+function isExecutableFile(candidate) {
+    try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return fs.statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** `claude` resolvable as an executable file on `PATH` (not a shell alias). */
+function findClaudeOnPath(env) {
+    const rawPath = env.PATH ?? env.Path ?? "";
+    for (const dir of rawPath.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, "claude");
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Common Claude Code install locations, checked when PATH lookup misses. */
+function commonInstallLocations() {
+    const home = os.homedir();
+    return [
+        path.join(home, ".local", "bin", "claude"), // native installer symlink
+        path.join(home, ".claude", "local", "claude"), // older local install
+        "/opt/homebrew/bin/claude", // Homebrew (Apple silicon)
+        "/usr/local/bin/claude", // Homebrew (Intel) / manual
+    ];
+}
+export function resolveClaudeBin(env = process.env) {
+    const override = env.ONTO_CLAUDE_BIN?.trim();
+    if (override)
+        return override;
+    const onPath = findClaudeOnPath(env);
+    if (onPath)
+        return onPath;
+    for (const location of commonInstallLocations()) {
+        if (isExecutableFile(location))
+            return location;
+    }
+    // Not found — return the bare name so spawn ENOENT carries the actionable
+    // "set ONTO_CLAUDE_BIN" guidance.
+    // POSIX-scoped: the bundle targets macOS/Linux (manifest compatibility.platforms
+    // = darwin/linux) and discovers a `claude` binary (no Windows `claude.exe` /
+    // %LOCALAPPDATA% lookup). Windows is out of scope here.
+    return "claude";
+}