efaimo 0.1.0 → 0.1.2

package/dist/targets/clientConfigs.d.ts

@@ -7,6 +7,13 @@ export interface ClientServerEntry {
 }
 export interface ClientConfigResult {
     entries: ClientServerEntry[];
+    /**
+     * Config files that came from the CURRENT DIRECTORY rather than the user
+     * config. Every command in these was written by whoever wrote the
+     * repository you are standing in, and --client spawns them. The CLI warns
+     * about these by name before it executes anything.
+     */
+    fromCwd: string[];
     /** Config files that were found and parsed. */
     sources: string[];
     /** Paths that were checked but absent. */

package/dist/targets/clientConfigs.js

@@ -27,7 +27,7 @@ export function loadClientServers(client, cwd = process.cwd()) {
         default:
             throw new Error(`unknown client "${client}" (supported: ${SUPPORTED_CLIENTS.join(", ")})`);
     }
-    const result = { entries: [], sources: [], missing: [] };
+    const result = { entries: [], sources: [], missing: [], fromCwd: [] };
     const seen = new Set();
     for (const { file, pick } of candidates) {
         if (!fs.existsSync(file)) {
@@ -48,6 +48,9 @@ export function loadClientServers(client, cwd = process.cwd()) {
             continue;
         }
         result.sources.push(file);
+        // Project-scoped config is the untrusted kind: it ships with a repo.
+        if (file.startsWith(cwd))
+            result.fromCwd.push(file);
         for (const [name, valueRaw] of Object.entries(servers)) {
             if (seen.has(name))
                 continue;

package/dist/testing/anthropicRunner.js

@@ -13,6 +13,8 @@ export function anthropicRunner(apiKey) {
             },
             body: JSON.stringify({
                 model: req.model,
+                // 0 for the judge, 1 for the subject. See RunnerRequest.deterministic.
+                temperature: req.deterministic ? 0 : 1,
                 max_tokens: 1024,
                 ...(req.system ? { system: req.system } : {}),
                 messages: [{ role: "user", content: req.user }],

package/dist/testing/harness.d.ts

@@ -18,10 +18,24 @@ export interface RunnerRequest {
     system?: string;
     user: string;
     model: string;
+    /**
+     * Sample deterministically. Set for the JUDGE, never for the subject.
+     * Neither runner set a temperature, so both defaulted to 1.0 and a "strict
+     * grader" asked for one word was being sampled: the same answer could be
+     * graded PASS on one trial and FAIL on the next, and that variance lands in
+     * the measurement as if it came from the skill. The subject arm keeps
+     * temperature 1 on purpose, because the thing being measured is how the
+     * model behaves normally.
+     */
+    deterministic?: boolean;
 }
 export type Runner = (req: RunnerRequest) => Promise<string>;
 export interface ArmResult {
     trials: number;
+    /** Trials the judge actually answered PASS or FAIL on. */
+    scored: number;
+    /** Trials whose judge verdict was neither; excluded from passRate. */
+    unparseable: number;
     passes: number;
     passRate: number;
 }
@@ -33,6 +47,13 @@ export interface TestReport {
     withoutSkill: ArmResult;
     /** withSkill.passRate - withoutSkill.passRate, in percentage points. */
     deltaPoints: number;
+    /** Two-sided Fisher exact p on the 2x2 of scored trials. */
+    p: number;
+    /** 95% interval on the delta, in percentage points (Newcombe). */
+    ci: {
+        lo: number;
+        hi: number;
+    };
     verdict: "helps" | "hurts" | "no measurable effect" | "inconclusive";
     notes: string[];
 }
@@ -42,4 +63,5 @@ export declare function armSystems(scenario: Scenario): {
     withoutSkill: string | undefined;
     withSkill: string;
 };
+export declare function withRetry(runner: Runner, tries?: number, baseDelayMs?: number): Runner;
 export declare function runScenario(scenario: Scenario, runner: Runner): Promise<TestReport>;

package/dist/testing/harness.js

@@ -1,3 +1,4 @@
+import { fisherExactTwoSided, deltaInterval } from "./stats.js";
 import fs from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
@@ -24,7 +25,10 @@ export function parseScenario(file) {
     const skill = set.skills[0];
     if (!skill)
         throw new Error(`${file}: no SKILL.md found at '${skillRel}'`);
-    const trials = Math.min(50, Math.max(1, Math.round(num(doc.trials) ?? 5)));
+    // Default 20, not 5. At 5 per arm a total separation (5/5 vs 0/5) is the ONLY
+    // outcome that reaches p < 0.05, so every partial result is uninterpretable
+    // and the old default guaranteed a verdict nobody could stand behind.
+    const trials = Math.min(50, Math.max(1, Math.round(num(doc.trials) ?? 20)));
     return {
         name,
         skillPath,
@@ -47,42 +51,121 @@ export function armSystems(scenario) {
     const withSkill = `You have access to the following skill. Use it if relevant.\n\n<skill name="${scenario.skillName}">\n${scenario.skillBody}\n</skill>`;
     return { withoutSkill: undefined, withSkill };
 }
+// PASS, FAIL, or neither. "Neither" used to be counted as FAIL: the old test
+// was `/pass/i.test(out) && !/fail/i.test(out)`, so a refusal, an API
+// error string, or a hedge like "passes on X but fails on Y" all became a
+// failed trial. Those are not evidence about the skill, and quietly scoring
+// them against whichever arm produced them biases the result.
 async function judgeOne(runner, scenario, answer) {
     const out = await runner({
         system: JUDGE_SYSTEM,
         user: `TASK:\n${scenario.task}\n\nRUBRIC:\n${scenario.judge}\n\nASSISTANT ANSWER:\n${answer}\n\nVerdict (PASS or FAIL):`,
         model: scenario.model,
+        deterministic: true,
     });
-    return /\bpass\b/i.test(out) && !/\bfail\b/i.test(out);
+    const saysPass = /\bpass(ed|es)?\b/i.test(out);
+    const saysFail = /\bfail(ed|s|ure)?\b/i.test(out);
+    if (saysPass && !saysFail)
+        return "pass";
+    if (saysFail && !saysPass)
+        return "fail";
+    return "unparseable";
+}
+// A live run makes trials * 2 arms * 2 (answer + judge) API calls. One
+// transient 429 or 5xx among them used to throw and discard every trial already
+// paid for. Retry the transient failures with backoff; a non-429 4xx (bad key,
+// unknown model) is a real error and is not retried.
+function isTransient(err) {
+    const m = String(err?.message ?? err);
+    return (/\b(429|500|502|503|504)\b/.test(m) ||
+        /timeout|ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|fetch failed|network/i.test(m));
+}
+export function withRetry(runner, tries = 4, baseDelayMs = 500) {
+    return async (req) => {
+        let lastErr;
+        for (let attempt = 0; attempt < tries; attempt++) {
+            try {
+                return await runner(req);
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt === tries - 1 || !isTransient(e))
+                    throw e;
+                await new Promise((r) => setTimeout(r, baseDelayMs * 2 ** attempt));
+            }
+        }
+        throw lastErr;
+    };
 }
 async function runArm(runner, scenario, system) {
     let passes = 0;
+    let unparseable = 0;
     for (let i = 0; i < scenario.trials; i++) {
         const answer = await runner({ system, user: scenario.task, model: scenario.model });
-        if (await judgeOne(runner, scenario, answer))
+        const v = await judgeOne(runner, scenario, answer);
+        if (v === "pass")
             passes++;
+        else if (v === "unparseable")
+            unparseable++;
     }
-    return { trials: scenario.trials, passes, passRate: (passes / scenario.trials) * 100 };
+    // Scored trials exclude the ones the judge did not answer, so the rate is a
+    // rate over evidence rather than over attempts.
+    const scored = scenario.trials - unparseable;
+    return {
+        trials: scenario.trials,
+        scored,
+        unparseable,
+        passes,
+        passRate: scored > 0 ? (passes / scored) * 100 : 0,
+    };
 }
 export async function runScenario(scenario, runner) {
     const systems = armSystems(scenario);
-    const withoutSkill = await runArm(runner, scenario, systems.withoutSkill);
-    const withSkill = await runArm(runner, scenario, systems.withSkill);
+    // Wrap once so both the subject answers and the judge calls survive a
+    // transient blip instead of throwing away the whole (paid-for) scenario.
+    const r = withRetry(runner);
+    const withoutSkill = await runArm(r, scenario, systems.withoutSkill);
+    const withSkill = await runArm(r, scenario, systems.withSkill);
     const deltaPoints = Math.round((withSkill.passRate - withoutSkill.passRate) * 10) / 10;
+    // The verdict is a significance test, not a threshold on the gap.
+    //
+    // It used to be `>= +15 points helps, <= -15 hurts`, with 5 trials per arm
+    // as the default. At that size 5/5 against 4/5 is +20 points and a two-sided
+    // Fisher p of 1.0000: the least significant result obtainable, reported as a
+    // finding, and `hurts` set exit code 1. The +-15 band sits inside the noise
+    // floor at every trial count below roughly 25 per arm, so the threshold was
+    // measuring sample size more than it was measuring the skill.
+    const p = fisherExactTwoSided(withSkill.passes, withSkill.scored, withoutSkill.passes, withoutSkill.scored);
+    const ci = deltaInterval(withSkill.passes, withSkill.scored, withoutSkill.passes, withoutSkill.scored);
+    // With no scoreable trial in an arm the pass rate and its interval are
+    // 0/0 = NaN; say so plainly instead of printing "NaN to NaN points".
+    const bothScored = withSkill.scored > 0 && withoutSkill.scored > 0;
     const notes = [
-        `${scenario.trials} trials per arm; probabilistic. Treat small deltas as noise and raise trials for confidence.`,
+        bothScored
+            ? `${scenario.trials} trials per arm. Two-sided Fisher exact p = ${p < 0.0001 ? "<0.0001" : p.toFixed(4)}; ` +
+                `95% interval on the delta ${ci.lo >= 0 ? "+" : ""}${ci.lo} to ${ci.hi >= 0 ? "+" : ""}${ci.hi} points.`
+            : `${scenario.trials} trials per arm. An arm produced no scoreable trial, so no p-value or delta interval can be computed.`,
     ];
+    const unscored = withSkill.unparseable + withoutSkill.unparseable;
+    if (unscored) {
+        notes.push(`${unscored} trial(s) produced a judge verdict that was neither PASS nor FAIL and are excluded from the rates, not counted as failures.`);
+    }
     let verdict;
-    if (scenario.trials < 5) {
+    if (withSkill.scored === 0 || withoutSkill.scored === 0) {
         verdict = "inconclusive";
-        notes.push("fewer than 5 trials: not enough signal to conclude.");
+        notes.push("an arm produced no scoreable trial; there is nothing to compare.");
     }
-    else if (deltaPoints >= 15)
+    else if (p >= 0.05) {
+        verdict = "no measurable effect";
+        if (Math.abs(deltaPoints) >= 15) {
+            notes.push(`the ${deltaPoints >= 0 ? "+" : ""}${deltaPoints} point gap is not significant at this sample size (p = ${p.toFixed(4)}). ` +
+                `Raise trials rather than reading the gap.`);
+        }
+    }
+    else if (deltaPoints > 0)
         verdict = "helps";
-    else if (deltaPoints <= -15)
-        verdict = "hurts";
     else
-        verdict = "no measurable effect";
+        verdict = "hurts";
     return {
         scenario: scenario.name,
         skill: scenario.skillName,
@@ -90,6 +173,8 @@ export async function runScenario(scenario, runner) {
         withSkill,
         withoutSkill,
         deltaPoints,
+        p,
+        ci,
         verdict,
         notes,
     };

package/dist/testing/openaiRunner.js

@@ -8,13 +8,27 @@ export function openaiRunner(apiKey) {
         if (req.system)
             messages.push({ role: "system", content: req.system });
         messages.push({ role: "user", content: req.user });
+        // o-series reasoning models (o1, o3, o4, ...) reject any non-default
+        // temperature with a 400, and a chat-sized 1024 cap starves them: their
+        // hidden reasoning tokens count against max_completion_tokens, so a small
+        // cap can return empty content. So omit temperature and give them headroom.
+        const isReasoning = /^o[0-9]/i.test(req.model);
+        const body = {
+            model: req.model,
+            messages,
+            max_completion_tokens: isReasoning ? 8192 : 1024,
+        };
+        // temperature: 0 for the judge, 1 for the subject (see
+        // RunnerRequest.deterministic), but only where the model accepts it.
+        if (!isReasoning)
+            body.temperature = req.deterministic ? 0 : 1;
         const res = await fetch("https://api.openai.com/v1/chat/completions", {
             method: "POST",
             headers: {
                 "content-type": "application/json",
                 authorization: `Bearer ${apiKey}`,
             },
-            body: JSON.stringify({ model: req.model, messages, max_completion_tokens: 1024 }),
+            body: JSON.stringify(body),
             redirect: "error",
             signal: AbortSignal.timeout(60000),
         });

package/dist/testing/stats.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Two-sided Fisher exact test on
+ *   [withPass, withFail]
+ *   [withoutPass, withoutFail]
+ *
+ * Sums the probability of every table at least as extreme as the observed one,
+ * which is the standard two-sided construction and needs no normal
+ * approximation.
+ */
+export declare function fisherExactTwoSided(withPass: number, withTrials: number, withoutPass: number, withoutTrials: number): number;
+/**
+ * Wilson score interval for one proportion. Chosen over the normal-approximation
+ * interval because that one produces a zero-width interval at 0/n and n/n,
+ * which is exactly where these runs land (8/8 and 0/8 both occur in the two
+ * committed example runs).
+ */
+export declare function wilson(passes: number, trials: number, z?: number): {
+    lo: number;
+    hi: number;
+};
+/**
+ * Interval on the DIFFERENCE of two proportions, in percentage points, by the
+ * Newcombe method: combine each arm's Wilson interval. Reported so a reader can
+ * see how wide the uncertainty actually is instead of inferring it from a
+ * point estimate.
+ */
+export declare function deltaInterval(withPass: number, withTrials: number, withoutPass: number, withoutTrials: number): {
+    lo: number;
+    hi: number;
+};

package/dist/testing/stats.js

@@ -0,0 +1,89 @@
+// The statistics behind an `efaimo test` verdict.
+//
+// The verdict used to be a bare threshold on the difference in pass rates:
+// >= +15 points "helps", <= -15 "hurts", exit code 1 on "hurts". With the
+// default 5 trials per arm, 5/5 against 4/5 is +20 points and would have been
+// reported as "helps" with a two-sided Fisher p of 1.0000 - the least
+// significant result the test can produce, labelled as a finding. At 8 trials
+// per arm the 95% interval on a difference of proportions is roughly +-49
+// points wide, so the whole +-15 band sits inside the noise for every trial
+// count the tool supports below about 25 per arm.
+//
+// A tool whose argument is that people publish numbers they cannot support
+// should not do that itself. So the verdict is now gated on a p-value, the
+// interval is reported, and both are printed rather than hidden.
+//
+// Fisher's exact test, not chi-squared: the counts here are single digits, and
+// chi-squared's approximation is not trustworthy at that size.
+/** ln(n!) via lgamma, so the 2x2 table math stays exact enough at small n. */
+function lnFactorial(n) {
+    let s = 0;
+    for (let i = 2; i <= n; i++)
+        s += Math.log(i);
+    return s;
+}
+/** Probability of exactly this 2x2 table under the hypergeometric null. */
+function lnHypergeom(a, b, c, d) {
+    const n = a + b + c + d;
+    return (lnFactorial(a + b) + lnFactorial(c + d) + lnFactorial(a + c) + lnFactorial(b + d) -
+        lnFactorial(n) - lnFactorial(a) - lnFactorial(b) - lnFactorial(c) - lnFactorial(d));
+}
+/**
+ * Two-sided Fisher exact test on
+ *   [withPass, withFail]
+ *   [withoutPass, withoutFail]
+ *
+ * Sums the probability of every table at least as extreme as the observed one,
+ * which is the standard two-sided construction and needs no normal
+ * approximation.
+ */
+export function fisherExactTwoSided(withPass, withTrials, withoutPass, withoutTrials) {
+    const a = withPass, b = withTrials - withPass;
+    const c = withoutPass, d = withoutTrials - withoutPass;
+    if (withTrials <= 0 || withoutTrials <= 0)
+        return 1;
+    const obs = lnHypergeom(a, b, c, d);
+    const rowTop = a + b, rowBot = c + d, colPass = a + c;
+    const lo = Math.max(0, colPass - rowBot);
+    const hi = Math.min(rowTop, colPass);
+    // A tiny epsilon so floating point does not drop the observed table itself.
+    const EPS = 1e-9;
+    let p = 0;
+    for (let x = lo; x <= hi; x++) {
+        const l = lnHypergeom(x, rowTop - x, colPass - x, rowBot - (colPass - x));
+        if (l <= obs + EPS)
+            p += Math.exp(l);
+    }
+    return Math.min(1, p);
+}
+/**
+ * Wilson score interval for one proportion. Chosen over the normal-approximation
+ * interval because that one produces a zero-width interval at 0/n and n/n,
+ * which is exactly where these runs land (8/8 and 0/8 both occur in the two
+ * committed example runs).
+ */
+export function wilson(passes, trials, z = 1.96) {
+    if (trials <= 0)
+        return { lo: 0, hi: 1 };
+    const p = passes / trials;
+    const z2 = z * z;
+    const denom = 1 + z2 / trials;
+    const centre = p + z2 / (2 * trials);
+    const half = z * Math.sqrt((p * (1 - p)) / trials + z2 / (4 * trials * trials));
+    return { lo: Math.max(0, (centre - half) / denom), hi: Math.min(1, (centre + half) / denom) };
+}
+/**
+ * Interval on the DIFFERENCE of two proportions, in percentage points, by the
+ * Newcombe method: combine each arm's Wilson interval. Reported so a reader can
+ * see how wide the uncertainty actually is instead of inferring it from a
+ * point estimate.
+ */
+export function deltaInterval(withPass, withTrials, withoutPass, withoutTrials) {
+    const w = wilson(withPass, withTrials);
+    const o = wilson(withoutPass, withoutTrials);
+    const p1 = withPass / withTrials, p2 = withoutPass / withoutTrials;
+    const d = p1 - p2;
+    const lo = d - Math.sqrt((p1 - w.lo) ** 2 + (o.hi - p2) ** 2);
+    const hi = d + Math.sqrt((w.hi - p1) ** 2 + (p2 - o.lo) ** 2);
+    return { lo: Math.round(Math.max(-1, lo) * 1000) / 10, hi: Math.round(Math.min(1, hi) * 1000) / 10 };
+}

package/dist/util/dotenv.d.ts

@@ -9,4 +9,12 @@
  * secrets are not forwarded to spawned MCP servers: minimalChildEnv() passes an
  * allowlist that excludes API keys.
  */
-export declare function loadDotEnv(dir?: string): string[];
+/**
+ * The only keys this loader may set. It used to set ANY key found in a .env in
+ * the CURRENT DIRECTORY, which means a repository you cloned could inject
+ * NODE_TLS_REJECT_UNAUTHORIZED=0 and silently disable certificate verification
+ * for every later HTTPS call, including the ones carrying your API key. The
+ * file header already said only two keys were wanted; this enforces it.
+ */
+export declare const ALLOWED: Set<string>;
+export declare function loadDotEnv(dir?: string, allowed?: ReadonlySet<string>): string[];

package/dist/util/dotenv.js

@@ -11,7 +11,15 @@ import { resolve } from "node:path";
  * secrets are not forwarded to spawned MCP servers: minimalChildEnv() passes an
  * allowlist that excludes API keys.
  */
-export function loadDotEnv(dir = process.cwd()) {
+/**
+ * The only keys this loader may set. It used to set ANY key found in a .env in
+ * the CURRENT DIRECTORY, which means a repository you cloned could inject
+ * NODE_TLS_REJECT_UNAUTHORIZED=0 and silently disable certificate verification
+ * for every later HTTPS call, including the ones carrying your API key. The
+ * file header already said only two keys were wanted; this enforces it.
+ */
+export const ALLOWED = new Set(["ANTHROPIC_API_KEY", "OPENAI_API_KEY"]);
+export function loadDotEnv(dir = process.cwd(), allowed = ALLOWED) {
     let text;
     try {
         text = readFileSync(resolve(dir, ".env"), "utf8");
@@ -32,6 +40,8 @@ export function loadDotEnv(dir = process.cwd()) {
         const key = line.slice(0, eq).trim();
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
             continue;
+        if (!allowed.has(key))
+            continue;
         if (process.env[key] !== undefined)
             continue;
         let val = line.slice(eq + 1).trim();

package/dist/util/safeText.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Strip terminal control characters from text that originated outside efaimo.
+ * Tab and newline survive because layout depends on them; everything else that
+ * can move a cursor, clear a line, or address the terminal is removed.
+ */
+export declare function safeText(s: string): string;
+/** Same, for a value that may be undefined. */
+export declare function safeTextOpt(s: string | undefined): string | undefined;

package/dist/util/safeText.js

@@ -0,0 +1,48 @@
+// Text that came from the thing being audited must not be able to drive the
+// terminal it is reported in.
+//
+// Tool names, titles, descriptions, server instructions, stderr tails and
+// repo-scan excerpts all originate with the target. They were interpolated
+// into stdout raw, so a hostile server could emit ESC[1A ESC[2K inside a tool
+// name and rewrite the grade line printed above its own finding: the auditor
+// reads "grade A (100), 0 errors" while the finding that contradicts it is
+// erased. OSC 8 forges a hyperlink; OSC 52 writes the reader's clipboard.
+// `--no-color` did not help, because that only suppresses the colours efaimo
+// itself adds.
+//
+// This matters out of proportion to its severity. An auditing tool whose
+// verdict can be rewritten by the thing it audits has a credibility problem
+// before it has a security one, and the HTTP transport is exactly where a user
+// expects no code execution and therefore no consequences.
+//
+// Applied at the RENDER boundary, never on ingestion: escape bytes in a
+// description are real bytes that a model would receive and really do cost
+// tokens, so `weigh` has to keep counting them. What must not happen is that
+// they reach a terminal as control codes.
+//
+// JSON output needs no pass here: JSON.stringify already encodes control
+// characters as  escape sequences, which are inert text.
+// C0 except tab and newline, DEL, and the C1 block. C1 is included because a
+// lone 0x9B is CSI in a terminal that decodes single-byte C1, which is the
+// same attack without an ESC byte to grep for.
+// Built from code points rather than written as literals so this file does not
+// itself contain the bytes it exists to remove; the same reason gates.mjs next
+// door builds its dash class with String.fromCharCode.
+const CONTROLS = new RegExp("[" +
+    "\\u0000-\\u0008" + // C0 up to backspace (tab 0x09 and newline 0x0A kept)
+    "\\u000B-\\u001F" + // vertical tab through unit separator, ESC included
+    "\\u007F" + // DEL
+    "\\u0080-\\u009F" + // C1, single-byte CSI/OSC among them
+    "]", "g");
+/**
+ * Strip terminal control characters from text that originated outside efaimo.
+ * Tab and newline survive because layout depends on them; everything else that
+ * can move a cursor, clear a line, or address the terminal is removed.
+ */
+export function safeText(s) {
+    return s.replace(CONTROLS, "");
+}
+/** Same, for a value that may be undefined. */
+export function safeTextOpt(s) {
+    return s === undefined ? undefined : safeText(s);
+}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Kept in sync with package.json by test/meta.test.ts. */
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.2";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Kept in sync with package.json by test/meta.test.ts. */
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.2";

package/dist/weigh/weigh.js

@@ -69,7 +69,9 @@ export async function weighSkills(set) {
         let refFileTokens = 0;
         let refFileCount = 0;
         for (const ref of skill.referencedPaths) {
-            if (!ref.exists || isBinaryPath(ref.resolved))
+            // Never read outside the skill root. S106 warns about these, but only
+            // after weigh had already opened the file and counted its tokens.
+            if (ref.escapes || !ref.exists || isBinaryPath(ref.resolved))
                 continue;
             const text = readTextSafe(ref.resolved);
             if (text === undefined)

package/dist/weigh/window.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The context window a token count is reported as a share of.
+ *
+ * There is no single correct denominator: it is a property of the model the
+ * host happens to be running, not of the server being measured. Every current
+ * frontier Claude model (Fable 5, Opus 5, Opus 4.8/4.7/4.6, Sonnet 5, Sonnet
+ * 4.6) is 1M; Haiku 4.5 is 200K, as are many non-Claude and local models, where the
+ * same tool definitions cost 5x the share shown here.
+ *
+ * So the share is always printed with the window it was computed against, and
+ * `--window` lets the caller name their own. The absolute token count is the
+ * number efaimo actually stands behind; this is a readability aid on top of it.
+ *
+ * Note that no rule grades on this share -- E128's thresholds are absolute
+ * token counts, so changing the window never moves a grade.
+ */
+export declare const DEFAULT_CONTEXT_WINDOW = 1000000;
+export declare function setContextWindow(tokens: number): void;
+export declare function getContextWindow(): number;
+/** "1M", "200k", "128k", "4,096" -- how the window is named in output. */
+export declare function formatWindow(tokens?: number): string;
+/**
+ * "~0.1% of a 1M window" -- always names the denominator, so the reader is
+ * never left guessing which model it assumed.
+ */
+export declare function formatWindowShare(tokens: number, window?: number): string;

package/dist/weigh/window.js

@@ -0,0 +1,44 @@
+/**
+ * The context window a token count is reported as a share of.
+ *
+ * There is no single correct denominator: it is a property of the model the
+ * host happens to be running, not of the server being measured. Every current
+ * frontier Claude model (Fable 5, Opus 5, Opus 4.8/4.7/4.6, Sonnet 5, Sonnet
+ * 4.6) is 1M; Haiku 4.5 is 200K, as are many non-Claude and local models, where the
+ * same tool definitions cost 5x the share shown here.
+ *
+ * So the share is always printed with the window it was computed against, and
+ * `--window` lets the caller name their own. The absolute token count is the
+ * number efaimo actually stands behind; this is a readability aid on top of it.
+ *
+ * Note that no rule grades on this share -- E128's thresholds are absolute
+ * token counts, so changing the window never moves a grade.
+ */
+export const DEFAULT_CONTEXT_WINDOW = 1_000_000;
+let contextWindow = DEFAULT_CONTEXT_WINDOW;
+export function setContextWindow(tokens) {
+    if (!Number.isFinite(tokens) || tokens <= 0) {
+        throw new Error(`--window must be a positive number of tokens, got ${tokens}`);
+    }
+    contextWindow = tokens;
+}
+export function getContextWindow() {
+    return contextWindow;
+}
+/** "1M", "200k", "128k", "4,096" -- how the window is named in output. */
+export function formatWindow(tokens = contextWindow) {
+    if (tokens >= 1_000_000 && tokens % 1_000_000 === 0)
+        return `${tokens / 1_000_000}M`;
+    if (tokens >= 1_000 && tokens % 1_000 === 0)
+        return `${tokens / 1_000}k`;
+    return tokens.toLocaleString("en-US");
+}
+/**
+ * "~0.1% of a 1M window" -- always names the denominator, so the reader is
+ * never left guessing which model it assumed.
+ */
+export function formatWindowShare(tokens, window = contextWindow) {
+    const pct = (tokens / window) * 100;
+    const shown = pct < 0.1 && pct > 0 ? "<0.1" : pct.toFixed(1);
+    return `~${shown}% of a ${formatWindow(window)} window`;
+}