@claudexor/core 3.1.0 → 3.1.1

package/dist/effort.d.ts

@@ -1,18 +1,60 @@
 import type { EffortHint } from "@claudexor/schema";
 /**
- * Map a requested reasoning-effort hint onto the nearest level a harness
- * actually supports.
+ * Effort resolution against VENDOR-ordered ladders. There is no static rank
+ * table anywhere in this repo: a level's rank is its position in the ladder the
+ * vendor itself advertised (a model's own ordered list, or the harness's merged
+ * ladder — `mergeEffortLadders` in the schema package). Ranking is NOT
+ * permission: what a run may actually use is whatever the resolved (harness,
+ * model) ADVERTISES, so a level newer than this repo passes through untouched
+ * the moment the vendor ships it.
+ */
+/**
+ * Outcome of resolving a requested effort against an advertised vocabulary.
+ * `rejected` carries actionable text naming what IS advertised — an unknown
+ * level is never silently downgraded into something we merely guessed at.
+ */
+export type EffortCheck = {
+    status: "ok";
+    effort: EffortHint | null;
+    clamped: boolean;
+} | {
+    status: "rejected";
+    message: string;
+};
+/**
+ * Resolve a requested reasoning-effort level against the levels a specific
+ * (harness, model) advertises. THE single owner of effort semantics; every
+ * surface (adapters, settings writes, preflight) resolves through it.
  *
- * - `requested` null/undefined → null (no effort was asked for; pass no flag).
- * - `supported` empty → null (effort is NOT a tunable surface for this adapter;
- *   it passes no effort flag at all — honest, not a silent clamp to a default).
- * - `requested` exactly supported → returned unchanged.
- * - otherwise CLAMP to the nearest supported level BY RANK: above the strongest
- *   supported → the strongest; below the weakest → the weakest; in-between → the
- *   closest by rank, ties resolving to the LOWER (cheaper) level.
+ * `advertised` is what the resolved target accepts (the model's own ordered
+ * list, or the harness ladder when the model recorded none). `ladder` is the
+ * rank authority for clamping: the harness's MERGED vendor order, so a level
+ * one sibling model advertises can clamp onto what THIS model accepts (`ultra`
+ * on gpt-5.4 → `xhigh`, because the merged codex ladder places `ultra` above
+ * it). It defaults to `advertised` itself — the degenerate case where nothing
+ * beyond the target's own order is known, including a harness whose models'
+ * orders CONTRADICT each other: pass `advertised` there, which makes
+ * cross-model clamping impossible by construction and refuses instead of
+ * inventing an order.
  *
- * Pure and data-driven: the adapter feeds its own declared `effort_levels` and
- * never hard-codes a clamp table.
+ * - nothing requested → ok, no effort (pass no flag).
+ * - `advertised` empty → ok, no effort: effort is not a tunable surface here, so
+ *   the caller discloses it as ignored (INV-105) instead of clamping to a guess.
+ * - requested IS advertised → PASS THROUGH VERBATIM. This is what makes a
+ *   future vendor level work with no Claudexor change.
+ * - requested is not advertised but the LADDER places it → CLAMP to the nearest
+ *   advertised level by ladder position (ties resolve to the cheaper one).
+ * - requested is unknown to the ladder too → REJECT, naming the advertised
+ *   set. We cannot place it, so any "nearest" would be invented.
+ */
+export declare function resolveEffort(requested: EffortHint | null | undefined, advertised: readonly EffortHint[], ladder?: readonly EffortHint[]): EffortCheck;
+/**
+ * Map a requested effort onto a level the resolved (harness, model) accepts, or
+ * null when none should be sent. Thin translational wrapper over `resolveEffort`
+ * for arg builders, which must never emit a level the vendor would reject: a
+ * rejection yields null (send NO flag, keep the vendor default) rather than a
+ * fabricated downgrade. Surfaces that can talk back to the user call
+ * `resolveEffort` and report its `message`.
  */
-export declare function normalizeEffort(requested: EffortHint | null | undefined, supported: readonly EffortHint[]): EffortHint | null;
+export declare function normalizeEffort(requested: EffortHint | null | undefined, advertised: readonly EffortHint[], ladder?: readonly EffortHint[]): EffortHint | null;
 //# sourceMappingURL=effort.d.ts.map

package/dist/effort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"effort.d.ts","sourceRoot":"","sources":["../src/effort.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAiBpD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACxC,SAAS,EAAE,SAAS,UAAU,EAAE,GAC/B,UAAU,GAAG,IAAI,CAoBnB"}
+{"version":3,"file":"effort.d.ts","sourceRoot":"","sources":["../src/effort.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC7D;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACxC,UAAU,EAAE,SAAS,UAAU,EAAE,EACjC,MAAM,GAAE,SAAS,UAAU,EAAe,GACzC,WAAW,CAkCb;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACxC,UAAU,EAAE,SAAS,UAAU,EAAE,EACjC,MAAM,GAAE,SAAS,UAAU,EAAe,GACzC,UAAU,GAAG,IAAI,CAGnB"}

package/dist/effort.js

@@ -1,50 +1,71 @@
-import { EffortHint as EffortHintSchema } from "@claudexor/schema";
 /**
- * The full cross-harness reasoning-effort ladder, ordered weakest→strongest.
- * DERIVED from the EffortHint enum's declaration order (the single source) so the
- * ladder can never drift from the enum: a future level (e.g. `ultra`) appended to
- * the enum is automatically ranked and every adapter clamps it with no code
- * change. An EffortHint's RANK is its index here; the normalizer below clamps any
- * requested level onto the nearest level a given adapter actually supports.
- */
-const EFFORT_LADDER = EffortHintSchema.options;
-function rank(level) {
-    return EFFORT_LADDER.indexOf(level);
-}
-/**
- * Map a requested reasoning-effort hint onto the nearest level a harness
- * actually supports.
+ * Resolve a requested reasoning-effort level against the levels a specific
+ * (harness, model) advertises. THE single owner of effort semantics; every
+ * surface (adapters, settings writes, preflight) resolves through it.
  *
- * - `requested` null/undefined → null (no effort was asked for; pass no flag).
- * - `supported` empty → null (effort is NOT a tunable surface for this adapter;
- *   it passes no effort flag at all — honest, not a silent clamp to a default).
- * - `requested` exactly supported → returned unchanged.
- * - otherwise CLAMP to the nearest supported level BY RANK: above the strongest
- *   supported → the strongest; below the weakest → the weakest; in-between → the
- *   closest by rank, ties resolving to the LOWER (cheaper) level.
+ * `advertised` is what the resolved target accepts (the model's own ordered
+ * list, or the harness ladder when the model recorded none). `ladder` is the
+ * rank authority for clamping: the harness's MERGED vendor order, so a level
+ * one sibling model advertises can clamp onto what THIS model accepts (`ultra`
+ * on gpt-5.4 → `xhigh`, because the merged codex ladder places `ultra` above
+ * it). It defaults to `advertised` itself — the degenerate case where nothing
+ * beyond the target's own order is known, including a harness whose models'
+ * orders CONTRADICT each other: pass `advertised` there, which makes
+ * cross-model clamping impossible by construction and refuses instead of
+ * inventing an order.
  *
- * Pure and data-driven: the adapter feeds its own declared `effort_levels` and
- * never hard-codes a clamp table.
+ * - nothing requested → ok, no effort (pass no flag).
+ * - `advertised` empty → ok, no effort: effort is not a tunable surface here, so
+ *   the caller discloses it as ignored (INV-105) instead of clamping to a guess.
+ * - requested IS advertised → PASS THROUGH VERBATIM. This is what makes a
+ *   future vendor level work with no Claudexor change.
+ * - requested is not advertised but the LADDER places it → CLAMP to the nearest
+ *   advertised level by ladder position (ties resolve to the cheaper one).
+ * - requested is unknown to the ladder too → REJECT, naming the advertised
+ *   set. We cannot place it, so any "nearest" would be invented.
  */
-export function normalizeEffort(requested, supported) {
-    if (requested === null || requested === undefined)
-        return null;
-    if (supported.length === 0)
-        return null;
-    if (supported.includes(requested))
-        return requested;
-    const want = rank(requested);
-    let best = null;
-    let bestDistance = Number.POSITIVE_INFINITY;
-    for (const level of supported) {
-        const distance = Math.abs(rank(level) - want);
-        // Strictly-closer wins; on a tie keep the LOWER-ranked (cheaper) candidate.
+export function resolveEffort(requested, advertised, ladder = advertised) {
+    if (requested === null || requested === undefined) {
+        return { status: "ok", effort: null, clamped: false };
+    }
+    if (advertised.length === 0)
+        return { status: "ok", effort: null, clamped: false };
+    if (advertised.includes(requested))
+        return { status: "ok", effort: requested, clamped: false };
+    const want = ladder.indexOf(requested);
+    // Only levels the ladder places can host a clamp; a level outside the ladder
+    // is a valid TARGET only through the exact-match branch above.
+    const rankable = advertised.filter((level) => ladder.indexOf(level) >= 0);
+    if (want < 0 || rankable.length === 0) {
+        return {
+            status: "rejected",
+            message: `effort "${requested}" is not advertised here and the advertised ladder cannot place it ` +
+                `(advertised: ${advertised.join(", ")})`,
+        };
+    }
+    let best = rankable[0];
+    let bestDistance = Math.abs(ladder.indexOf(best) - want);
+    for (const level of rankable.slice(1)) {
+        const distance = Math.abs(ladder.indexOf(level) - want);
+        // Strictly-closer wins; on a tie keep the LOWER-positioned (cheaper) candidate.
         if (distance < bestDistance ||
-            (distance === bestDistance && best !== null && rank(level) < rank(best))) {
+            (distance === bestDistance && ladder.indexOf(level) < ladder.indexOf(best))) {
             best = level;
             bestDistance = distance;
         }
     }
-    return best;
+    return { status: "ok", effort: best, clamped: true };
+}
+/**
+ * Map a requested effort onto a level the resolved (harness, model) accepts, or
+ * null when none should be sent. Thin translational wrapper over `resolveEffort`
+ * for arg builders, which must never emit a level the vendor would reject: a
+ * rejection yields null (send NO flag, keep the vendor default) rather than a
+ * fabricated downgrade. Surfaces that can talk back to the user call
+ * `resolveEffort` and report its `message`.
+ */
+export function normalizeEffort(requested, advertised, ladder = advertised) {
+    const check = resolveEffort(requested, advertised, ladder);
+    return check.status === "ok" ? check.effort : null;
 }
 //# sourceMappingURL=effort.js.map

package/dist/effort.js.map

@@ -1 +1 @@
-{"version":3,"file":"effort.js","sourceRoot":"","sources":["../src/effort.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,IAAI,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEnE;;;;;;;GAOG;AACH,MAAM,aAAa,GAA0B,gBAAgB,CAAC,OAAO,CAAC;AAEtE,SAAS,IAAI,CAAC,KAAiB;IAC7B,OAAO,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAwC,EACxC,SAAgC;IAEhC,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC/D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IAEpD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7B,IAAI,IAAI,GAAsB,IAAI,CAAC;IACnC,IAAI,YAAY,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QAC9C,4EAA4E;QAC5E,IACE,QAAQ,GAAG,YAAY;YACvB,CAAC,QAAQ,KAAK,YAAY,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EACxE,CAAC;YACD,IAAI,GAAG,KAAK,CAAC;YACb,YAAY,GAAG,QAAQ,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"effort.js","sourceRoot":"","sources":["../src/effort.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,aAAa,CAC3B,SAAwC,EACxC,UAAiC,EACjC,SAAgC,UAAU;IAE1C,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAClD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACxD,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACnF,IAAI,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAE/F,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACvC,6EAA6E;IAC7E,+DAA+D;IAC/D,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1E,IAAI,IAAI,GAAG,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtC,OAAO;YACL,MAAM,EAAE,UAAU;YAClB,OAAO,EACL,WAAW,SAAS,qEAAqE;gBACzF,gBAAgB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;SAC3C,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,GAAe,QAAQ,CAAC,CAAC,CAAe,CAAC;IACjD,IAAI,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;IACzD,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QACxD,gFAAgF;QAChF,IACE,QAAQ,GAAG,YAAY;YACvB,CAAC,QAAQ,KAAK,YAAY,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAC3E,CAAC;YACD,IAAI,GAAG,KAAK,CAAC;YACb,YAAY,GAAG,QAAQ,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAwC,EACxC,UAAiC,EACjC,SAAgC,UAAU;IAE1C,MAAM,KAAK,GAAG,aAAa,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAC3D,OAAO,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudexor/core",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "license": "MIT",
   "description": "HarnessAdapter contract, process helpers, typed errors, and low-level execution utilities.",
   "type": "module",
@@ -20,8 +20,8 @@
   ],
   "dependencies": {
     "@playwright/mcp": "0.0.78",
-    "@claudexor/schema": "3.1.0",
-    "@claudexor/util": "3.1.0"
+    "@claudexor/util": "3.1.1",
+    "@claudexor/schema": "3.1.1"
   },
   "repository": {
     "type": "git",