@event4u/agent-config 16.2.0 → 16.4.0

package/src/shared/skillRanking.ts

@@ -24,10 +24,13 @@
  * `score_skill_relevance` CLI's argparse-parity suite is the check that the move
  * changed nothing.
  *
- * THE ONE ADDITION is `triggerTerms`, off by default. Phase 3.1 of the same
- * roadmap indexes `triggers.keyword` / `triggers.phrase` text; it is an opt-in
- * parameter rather than a second function so the two rankers can be measured
- * against each other on one corpus.
+ * THE ADDITIONS ARE ALL OFF BY DEFAULT and live in one {@link RankOptions}
+ * object: three that widen the indexed TERM SOURCE (trigger prose, the skill's
+ * own `## When to use` section, the body's headings) and one that changes the
+ * WEIGHTING (inverse document frequency over the catalogue). They are opt-in
+ * parameters rather than separate functions so two configurations can be
+ * measured against each other on one corpus without becoming two rankers. With
+ * every flag off the arithmetic is the ported one, unchanged.
  *
  * Pure — no imports, no I/O, no clock.
  */
@@ -115,36 +118,159 @@ export interface RankableSkill {
     personas?: readonly string[];
     /** `triggers[].keyword` / `triggers[].phrase` text. Indexed only on request. */
     triggerText?: readonly string[];
+    /** The skill's own `## When to use` prose. Indexed only on request. */
+    whenToUseText?: string;
+    /** The skill body's `##` / `###` heading lines. Indexed only on request. */
+    headingText?: readonly string[];
 }
 
+/**
+ * The candidate signals, each off by default and each measurable alone.
+ *
+ * `road-to-a-ranker-that-routes` 2.2 requires exactly this shape: one flag per
+ * signal, default off, so a configuration is a named set of flags and two
+ * readings of "the ranker" are never two different rankers under one name. With
+ * every flag off the score is byte-identical to the Python-parity scorer, which
+ * is what the CLI parity suite pins.
+ */
 export interface RankOptions {
-    /** Phase 3.1: fold `triggerText` into the indexed terms. Default false (keyword-v1). */
+    /** Fold `triggerText` into the indexed terms. Default false (keyword-v1). */
     includeTriggers?: boolean;
+    /** Fold the skill's own `## When to use` prose into the indexed terms. */
+    includeWhenToUse?: boolean;
+    /** Fold the body's section headings into the indexed terms. */
+    includeHeadings?: boolean;
+    /**
+     * Weight each matched term by its inverse document frequency over the
+     * catalogue, instead of counting every term alike.
+     *
+     * Needs {@link TermStats}. Setting it WITHOUT one throws, rather than
+     * quietly taking the unweighted branch: a weighting that falls back to
+     * unweighted on a missing input produces a baseline number under a
+     * configuration's name, which is the one failure the whole flag table
+     * exists to prevent.
+     */
+    idfWeighting?: boolean;
+    /**
+     * Order equal INTEGER scores by the unrounded score before the name.
+     *
+     * Changes no score — `scoreSkill` still returns the rounded integer — only
+     * the order inside a block of equal integers, which is otherwise decided by
+     * the alphabet (`road-to-a-ranker-whose-ties-break-on-signal` D4). Off, the
+     * comparator is the Python-parity `(-score, name)` one, unchanged.
+     */
+    tieBreakUnrounded?: boolean;
 }
 
 /** The indexed term set for one skill, under the given options. */
 export function skillTerms(skill: RankableSkill, opts: RankOptions = {}): Set<string> {
     const parts = [skill.name, skill.description];
     if (opts.includeTriggers && skill.triggerText) parts.push(...skill.triggerText);
+    if (opts.includeWhenToUse && skill.whenToUseText) parts.push(skill.whenToUseText);
+    if (opts.includeHeadings && skill.headingText) parts.push(...skill.headingText);
     return tokenize(parts.join(' '));
 }
 
+/** True when `opts` turns on at least one term source beyond name + description. */
+export function widensTermSource(opts: RankOptions): boolean {
+    return Boolean(opts.includeTriggers || opts.includeWhenToUse || opts.includeHeadings);
+}
+
+/**
+ * How many indexed skills carry each term, and how many skills there are.
+ *
+ * Derived from the catalogue under the SAME options the ranking uses — a
+ * document frequency computed over one term source and applied to another
+ * would weight terms by how rare they are somewhere they were never read.
+ */
+export interface TermStats {
+    df: ReadonlyMap<string, number>;
+    skills: number;
+}
+
+/**
+ * @param termSets the per-skill term sets, in the same order as `skills`.
+ *   Required rather than derived, so the catalogue is tokenized ONCE per call
+ *   instead of once here and again at the scoring loop. Tokenizing ~300 skills
+ *   twice per prompt is invisible next to re-reading them from disk, which is
+ *   exactly why it would have stayed invisible.
+ */
+export function buildTermStats(
+    skills: readonly RankableSkill[],
+    termSets: readonly ReadonlySet<string>[],
+): TermStats {
+    const df = new Map<string, number>();
+    for (const terms of termSets) {
+        for (const t of terms) df.set(t, (df.get(t) ?? 0) + 1);
+    }
+    return { df, skills: skills.length };
+}
+
+/**
+ * The weight one matched term carries.
+ *
+ * `ln(1 + skills / (1 + df))`, the smoothed textbook form: a term on every
+ * skill tends to zero, a term on one skill carries the most. Unknown terms are
+ * treated as df 0 — a task term no skill indexes cannot be matched anyway, so
+ * its weight only affects the denominator, where counting it fully is right:
+ * failing to cover a rare term should cost more than failing to cover a common
+ * one.
+ */
+export function idf(term: string, stats: TermStats): number {
+    return Math.log(1 + stats.skills / (1 + (stats.df.get(term) ?? 0)));
+}
+
 /**
  * The score. `taskTerms` is `tokenize(task)`; `terms` is `skillTerms(skill)`.
  *
  * Both are passed in rather than derived here so a caller ranking N skills
  * tokenizes the task once and each skill once, which is what makes this usable
- * on a per-prompt hook path.
+ * on a per-prompt hook path. `opts` and `stats` are optional and, with them
+ * absent or every flag off, the arithmetic is exactly the Python-parity one.
  */
 export function scoreSkill(
     taskTerms: ReadonlySet<string>,
     skill: RankableSkill,
     terms: ReadonlySet<string>,
+    opts: RankOptions = {},
+    stats?: TermStats,
+): number {
+    return roundHalfToEven(rawSkillScore(taskTerms, skill, terms, opts, stats));
+}
+
+/**
+ * The score before `roundHalfToEven` — what {@link scoreSkill} rounds. Exposed
+ * only so `tieBreakUnrounded` can order a block of equal integers by it.
+ */
+export function rawSkillScore(
+    taskTerms: ReadonlySet<string>,
+    skill: RankableSkill,
+    terms: ReadonlySet<string>,
+    opts: RankOptions = {},
+    stats?: TermStats,
 ): number {
+    if (opts.idfWeighting && !stats) {
+        throw new Error(
+            'scoreSkill: idfWeighting is set but no TermStats was passed — scoring unweighted here ' +
+                'would publish a baseline number under the idf label. Build stats with buildTermStats.',
+        );
+    }
     if (taskTerms.size === 0) return 0;
-    let inter = 0;
-    for (const t of taskTerms) if (terms.has(t)) inter++;
-    const overlap = inter / Math.max(taskTerms.size, 1);
+    let overlap: number;
+    if (opts.idfWeighting && stats) {
+        let hit = 0;
+        let total = 0;
+        for (const t of taskTerms) {
+            const w = idf(t, stats);
+            total += w;
+            if (terms.has(t)) hit += w;
+        }
+        overlap = total > 0 ? hit / total : 0;
+    } else {
+        let inter = 0;
+        for (const t of taskTerms) if (terms.has(t)) inter++;
+        overlap = inter / Math.max(taskTerms.size, 1);
+    }
     let personaHit = 0;
     const taskLower = [...taskTerms].join(' ');
     for (const persona of skill.personas ?? []) {
@@ -154,7 +280,7 @@ export function scoreSkill(
             break;
         }
     }
-    return roundHalfToEven(overlap * 70 + personaHit * 30);
+    return overlap * 70 + personaHit * 30;
 }
 
 export interface RankedSkill {
@@ -173,11 +299,40 @@ export function rankSkills(
     opts: RankOptions = {},
 ): RankedSkill[] {
     const taskTerms = tokenize(task);
+    const termSets = skills.map((s) => skillTerms(s, opts));
+    const stats = opts.idfWeighting ? buildTermStats(skills, termSets) : undefined;
     const rows: RankedSkill[] = [];
-    for (const skill of skills) {
-        const score = scoreSkill(taskTerms, skill, skillTerms(skill, opts));
-        if (score > 0) rows.push({ name: skill.name, score, personas: [...(skill.personas ?? [])] });
+    const raw = new Map<string, number>();
+    for (let i = 0; i < skills.length; i += 1) {
+        const skill = skills[i] as RankableSkill;
+        const unrounded = rawSkillScore(taskTerms, skill, termSets[i] as ReadonlySet<string>, opts, stats);
+        const score = roundHalfToEven(unrounded);
+        if (score > 0) {
+            rows.push({ name: skill.name, score, personas: [...(skill.personas ?? [])] });
+            raw.set(skill.name, unrounded);
+        }
     }
-    rows.sort((a, b) => (b.score - a.score) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    rows.sort((a, b) => compareRanked(a.name, a.score, b.name, b.score, opts, raw));
     return rows;
 }
+
+/**
+ * The ranking order: score descending, then — only under `tieBreakUnrounded` —
+ * the unrounded score descending, then the name. One comparator for both
+ * rankers, so the flag cannot mean two orders in two places.
+ */
+export function compareRanked(
+    aName: string,
+    aScore: number,
+    bName: string,
+    bScore: number,
+    opts: RankOptions,
+    raw: ReadonlyMap<string, number>,
+): number {
+    if (bScore !== aScore) return bScore - aScore;
+    if (opts.tieBreakUnrounded) {
+        const d = (raw.get(bName) ?? 0) - (raw.get(aName) ?? 0);
+        if (d !== 0) return d;
+    }
+    return aName < bName ? -1 : aName > bName ? 1 : 0;
+}

package/dist/cli-delegate/chunk-5R7HOLAF.js

@@ -1,99 +0,0 @@
-import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
-import {
-  atomicAppendLine
-} from "./chunk-6KM6ORRY.js";
-
-// src/install/txlog.ts
-import { createGzip } from "node:zlib";
-import { createReadStream, createWriteStream, existsSync, readFileSync, renameSync, statSync, unlinkSync } from "node:fs";
-import { pipeline } from "node:stream/promises";
-var ROTATION_MAX_BYTES = 10 * 1024 * 1024;
-var ROTATION_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1e3;
-var RECOVERY_DEPTH_CAP = 500;
-function appendTxLog(logPath, entry) {
-  if (shouldRotate(logPath)) {
-    rotateLogSync(logPath);
-  }
-  atomicAppendLine(logPath, JSON.stringify(entry));
-}
-function readRecentEntries(logPath) {
-  if (!existsSync(logPath)) {
-    return [];
-  }
-  const raw = readFileSync(logPath, "utf8");
-  const lines = raw.split("\n").filter((l) => l.length > 0);
-  const tail = lines.slice(-RECOVERY_DEPTH_CAP);
-  const out = [];
-  for (const line of tail) {
-    const parsed = tryParseEntry(line);
-    if (parsed !== null) {
-      out.push(parsed);
-    }
-  }
-  return out;
-}
-function shouldRotate(logPath, now = /* @__PURE__ */ new Date()) {
-  if (!existsSync(logPath)) {
-    return false;
-  }
-  let size = 0;
-  try {
-    size = statSync(logPath).size;
-  } catch {
-    return false;
-  }
-  if (size >= ROTATION_MAX_BYTES) {
-    return true;
-  }
-  const firstTs = readFirstTimestamp(logPath);
-  if (firstTs === null) {
-    return false;
-  }
-  return now.getTime() - firstTs >= ROTATION_MAX_AGE_MS;
-}
-function rotateLogSync(logPath) {
-  if (!existsSync(logPath)) {
-    return;
-  }
-  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const rotated = logPath.replace(/\.jsonl$/, `.${stamp}.jsonl`);
-  renameSync(logPath, rotated);
-  void gzipInPlace(rotated).catch(() => {
-  });
-}
-async function gzipInPlace(source) {
-  const target = `${source}.gz`;
-  await pipeline(createReadStream(source), createGzip(), createWriteStream(target));
-  try {
-    unlinkSync(source);
-  } catch {
-  }
-}
-function readFirstTimestamp(logPath) {
-  try {
-    const raw = readFileSync(logPath, "utf8");
-    const firstLine = raw.split("\n", 1)[0] ?? "";
-    const parsed = tryParseEntry(firstLine);
-    if (parsed === null) return null;
-    const t = Date.parse(parsed.ts);
-    return Number.isFinite(t) ? t : null;
-  } catch {
-    return null;
-  }
-}
-function tryParseEntry(line) {
-  try {
-    const obj = JSON.parse(line);
-    if (typeof obj.ts !== "string" || typeof obj.kind !== "string" || typeof obj.path !== "string") {
-      return null;
-    }
-    return obj;
-  } catch {
-    return null;
-  }
-}
-
-export {
-  appendTxLog,
-  readRecentEntries
-};