agent-nuvira 3.3.13 → 3.3.14

package/dist/tools/loop-skill-hint.d.ts

@@ -1,225 +1,125 @@
 /**
- * Loop skill hint (`src/tools/loop-skill-hint.ts`) — AGENTIC_CAPABILITY_ASSESSMENT
- * Addendum v4 Phase 3.2: "The loop never hears about the orchestrator's skill
- * layer: the pipeline consults SkillStore.findMatch + the hub catalog before
- * planning and injects the matched methodology, but a chat/execute-loop goal
- * starts with zero knowledge that a first-party playbook exists."
- *
- * This module closes that parity gap DETERMINISTICALLY (no LLM call): given
- * the user's goal, it finds the best available skill the SAME way the
- * orchestrator does —
- *
- *   1. compiled SkillStore.findMatch (the first-party capability batch),
- *   2. the hub catalog (findHubSkillMatch — installed SKILL.md skills),
- *
- * then returns a system-prompt block that hands the model the skill's
- * methodology with an EXPLICIT escape hatch ("this is a recommendation —
- * ignore it when it does not fit") and the exact load syntax
- * (`skill` tool, {"skill":"<name>"}).
- *
- * Why an evidence filter on top of findMatch: the compiled store's threshold
- * is intentionally low (score >= 1, "manual discovery") and its scoring adds
- * a quality/usage bonus to EVERY skill — so a goal merely containing a generic
- * pattern word ("goal", "task") can false-positive. The chat loop runs on
- * EVERY message (not just pipeline goals), so the loop hint requires REAL
- * goal evidence: a name-word or tag hit, or two pattern-word hits. The
- * orchestrator does not need this (its planner only sees pipeline goals); the
- * hub catalog's own scoring is keyword-based and needs no filter.
- *
- * Safety rails (mirroring the orchestrator's injection contract):
- *   - skills.disabled[] gate — a dashboard/CLI-disabled skill is NEVER
- *     injected (the same "the toggle is never cosmetic" rule the match gates
- *     enforce elsewhere).
- *   - Website-deploy activation gate — the orchestrator requires
- *     hosting-specific intent before injecting website methodology; the loop
- *     hint applies the identical regex so "deploy the API" does not drag in
- *     static-site deployment steps.
- *   - Side-effect-free matching: the match itself marks nothing; usage is
- *     marked ONCE via markLoopSkillUsed by the caller (skillView()'s internal
- *     markUsed is deliberately avoided so the hint builder is idempotent).
- *   - Bounded injection: at most ONE methodology block per prompt, and the
- *     methodology text itself is capped (compiled: 8 steps; hub: 2000 chars)
- *     so a crowded catalog cannot balloon the system prompt.
- *   - Best-effort by construction: any store/catalog failure returns '' /
- *     null and the turn proceeds exactly as before (a hint must never break
- *     a turn).
- *
- * Consumers: chat's runChatAnswer (system prompt) and the execute loop's
- * runLoopExecutor — the two runToolLoop callers that had no skill knowledge.
+ * Skill hint (`src/tools/loop-skill-hint.ts`) — model-driven skill selection.
+ *
+ * HISTORY (why the keyword scorer is gone). This module used to decide, in code,
+ * WHICH skill a goal wanted: `findLoopSkillMatch` scored the compiled store and
+ * the hub catalog, then a hand-written evidence filter (`hasRealGoalEvidence`)
+ * pulled back the false positives with stopword lists, generic-name-word lists,
+ * generic-tag lists and platform-host lists. Every one of those lists was a bug
+ * report: "blood test report" matched the software `test-strategy` skill,
+ * "Windows and Linux" matched `wsl-setup`, "packaging" matched `electron-app`.
+ * A word list cannot decide what a goal MEANS, and each word added to force one
+ * case right made some real match wrong.
+ *
+ * THE REPLACEMENT. Selection is the MODEL's job now. The harness no longer
+ * guesses; it hands the model the discovery path and gets out of the way:
+ *
+ *   - default (`pointer`) — a few lines saying skills exist and HOW to find one:
+ *     the `skill` tool (list / load) and the capability search (`tool_search`,
+ *     whose hits include `kind:"skill"` capabilities). Near-zero prompt cost,
+ *     no false positives, no maintenance.
+ *   - `catalog` / `names` (OPT-IN) — the full name+description catalog, or the
+ *     names-only list, for a user who wants everything in-context.
+ *   - `off` — inject nothing.
+ *
+ * The old default was the ~24.5K-char catalog, which buried the task on every
+ * turn (3.3.11 regression, see tests/release/agent-contracts.test.ts); the
+ * pointer keeps the small-prompt property while still being model-driven.
+ *
+ * The pipeline arm consumes the SAME catalog builder (see the orchestrator's
+ * `skillCatalog` injection): the planner is a model too, so it is handed the
+ * list instead of a keyword-selected skill.
+ *
+ * Best-effort by construction: any store/catalog failure returns '' and the turn
+ * proceeds byte-identically (a hint must never break a turn).
  */
 import type { ConfigManager } from '../config/manager.js';
-/**
- * The match the hint was built from (echoed to callers for telemetry/tests).
- * `null` = no match (no skill scored, or it was gated out).
- */
-export interface LoopSkillHintMatch {
+/** One catalog entry the model can read and pick from. */
+interface SkillEntry {
     name: string;
-    id: string;
-    source: 'compiled' | 'hub';
+    description: string;
 }
-/** Is this token a host/platform name (never goal evidence)? */
-export declare function isPlatformName(word: string): boolean;
-/**
- * Did the goal show REAL evidence for this skill — a name-word hit, a tag hit,
- * or two DISTINCT pattern/description words (meta-words and platform names
- * excluded)? Guards the compiled store's intentionally loose threshold:
- * findMatch adds a quality/usage bonus to every skill, so a generic word like
- * "goal" alone must never inject methodology into a chat turn.
- *
- * Also the HUB path's only filter: `findHubSkillMatch` scores name words and
- * DESCRIPTION keywords and returns the top scorer with no evidence gate at all,
- * so an installed skill whose description merely names the target platform
- * scored on that alone. A hub match carries no tags/goalPattern, so its
- * description words are the pattern-level evidence (the caller passes it here).
- *
- * MATCHING IS BY WHOLE WORD, never substring. `q.includes(word)` matched
- * "kill" inside "s**kill**" — measured: `feature-flags` (goalPattern “…kill
- * switch…”) matched "no **skill** covers alpaca husbandry whatsoever", and the
- * same class makes `mac` match "machine" and `arch` match "search". The goal is
- * tokenized once into a word set and skills are matched against tokens.
- *
- * Deterministic, no LLM.
- */
-export declare function hasRealGoalEvidence(goal: string, skill: {
-    name: string;
-    tags?: string[];
-    goalPattern?: string;
-    description?: string;
-}): boolean;
 /**
- * THE skill-activation gate — the single decision every injection path makes.
- *
- * Composes (1) the website-deploy activation rule: website methodology needs
- * HOSTING intent, so a generic "deploy the API" goal never gets it; and (2) the
- * evidence rule above.
- *
- * Before this existed the gate was implemented three times with different
- * strength: the chat/execute loop applied the evidence filter to COMPILED
- * matches but trusted hub matches raw, and the ORCHESTRATOR applied neither
- * (only the website-deploy rule) — so the pipeline was the most exposed
- * surface. One predicate, consumed by all of them.
+ * Every skill the model may pick from — compiled first-party + installed hub
+ * (SKILL.md) skills, deduped by name, with the disabled gate applied. Best-effort:
+ * a store/catalog failure contributes nothing rather than throwing.
  */
-export declare function isSkillActivated(goal: string, skill: {
-    id?: string;
-    name: string;
-    tags?: string[];
-    goalPattern?: string;
-    description?: string;
-}): boolean;
+export declare function collectSkillEntries(cm?: ConfigManager): Promise<SkillEntry[]>;
+/** Where the "load one" tail should point: the loop's skill tool, or the pipeline's skill_view. */
+export type SkillLoadHint = 'skill-tool' | 'skill-view';
 /**
- * Find the best skill for the goal across BOTH sources the orchestrator
- * consults, honoring the disabled + website-deploy activation gates (+ the
- * compiled evidence filter). Compiled wins ties (its id is the deterministic
- * seed id). Returns null when nothing matches (never a forced match).
- */
-export declare function findLoopSkillMatch(goal: string, cm?: ConfigManager): Promise<LoopSkillHintMatch | null>;
-/**
- * Build the system-prompt block for a matched skill, or '' when there is no
- * match. The block follows the orchestrator's injection contract:
- *
- *   - the skill is a RECOMMENDATION, the model still owns the plan (the
- *     orchestrator's "model-selected activation" phrasing),
- *   - the methodology rides in as Level-2 content (progressive disclosure —
- *     the model sees the steps without paying a tool call for them),
- *   - the exact load syntax is included so the model can refresh/parameterize
- *     via the `skill` tool mid-turn,
- *   - ONE block max (bounded system-prompt growth).
+ * The DEFAULT hint — a bounded discovery pointer, not a recommendation.
  *
- * Marks nothing: usage tracking belongs to markLoopSkillUsed (the caller
- * decides when a match actually got USED — i.e. was injected).
- *
- * @param goal       the user's goal text (matched against skill triggers)
- * @param cm         ConfigManager for the disabled-skills gate (optional)
- * @param injected   out-param: when provided, receives the match that was
- *                   injected (null when none).
+ * It names the two model-driven paths to a skill (the `skill` tool and the
+ * capability search) and leaves the decision with the model. Returns '' when
+ * there are no skills to discover (nothing to say — never a forced hint).
  */
-export declare function buildLoopSkillHint(goal: string, cm?: ConfigManager, injected?: {
-    value: LoopSkillHintMatch | null;
-}): Promise<string>;
+export declare function buildSkillPointerHint(cm?: ConfigManager, loadHint?: SkillLoadHint): Promise<string>;
 /**
- * A bounded CATALOG of available skills for the system prompt — the model-facing
- * replacement for keyword auto-injection.
- *
- * WHY THIS REPLACES THE MATCHER: a word list cannot decide whether "blood test
- * report" is software testing, and every stopword added to force it right made
- * some real match wrong. The model can read the same catalog and judge instantly,
- * so the fix is to STOP deciding in code and hand the model the list: name + a
- * one-line description each, plus the exact `skill` tool syntax to load one. This
- * scales to infinite permutations with no maintenance and no false positives —
- * the model loads a skill only when it actually applies.
+ * The bounded CATALOG of available skills for the system prompt — the model-facing
+ * discovery surface, read straight through.
  *
  * Bounded deliberately: descriptions are capped and the list is capped, so a
- * crowded catalog cannot balloon the system prompt. Returns '' when there are no
- * skills (nothing to say) — never a forced recommendation.
+ * crowded catalog cannot balloon the prompt. Returns '' when there are no skills.
  *
  * @param cm       ConfigManager (honors skills.disabled — a disabled skill is
  *                 never listed, the same gate the tool enforces)
  * @param opts     caps: maxSkills (default 200 — the full bundled+hub catalog,
  *                 so NO skill is dropped from the model's view; missing a skill
  *                 is the failure this design exists to avoid), descriptionChars
- *                 (default 140)
+ *                 (default 140), namesOnly (default false), loadHint
  */
 export declare function buildSkillCatalogHint(cm?: ConfigManager, opts?: {
     maxSkills?: number;
     descriptionChars?: number;
     namesOnly?: boolean;
+    loadHint?: SkillLoadHint;
 }): Promise<string>;
 /**
  * Which skill hint the system prompt carries. See {@link resolveSkillHintMode}.
- *   - `match`   — the small keyword-matched hint (ONE skill, only on a real
- *                 match). The default and the 3.3.10 behaviour.
+ *   - `pointer` — the small discovery pointer (names the skill tool + capability
+ *                 search). The DEFAULT.
  *   - `catalog` — the FULL name+description catalog (opt-in).
  *   - `names`   — the catalog WITHOUT descriptions (names only; far smaller).
  *   - `off`     — never inject a skill hint.
  */
-export type SkillHintMode = 'match' | 'catalog' | 'names' | 'off';
+export type SkillHintMode = 'pointer' | 'catalog' | 'names' | 'off';
 /** The default. The catalog is ~24K chars — it must never be the default. */
 export declare const DEFAULT_SKILL_HINT_MODE: SkillHintMode;
 /**
  * Parse a raw value into a mode. Synonyms accepted so a typo cannot silently
  * change behaviour; null (unrecognized) falls through to the next source.
- *   - match / keyword / auto / small / default      → 'match'
- *   - catalog / full / all / on / true / 1          → 'catalog'
- *   - names / names-only / list / bare / titles     → 'names'
- *   - off / none / never / false / 0                → 'off'
+ *   - pointer / match / keyword / auto / small / default → 'pointer'
+ *   - catalog / full / all / on / true / 1               → 'catalog'
+ *   - names / names-only / list / bare / titles          → 'names'
+ *   - off / none / never / false / 0                     → 'off'
+ *
+ * `match`/`keyword` are kept as ACCEPTED SYNONYMS for back-compat (an existing
+ * `NUVIRA_SKILL_CATALOG=match` or `skills.catalogHint: "match"` still works) —
+ * they now mean the pointer, since there is no keyword matcher any more.
  */
 export declare function parseSkillHintMode(raw: string | undefined | null): SkillHintMode | null;
 /**
  * The effective skill-hint mode. Env first (`NUVIRA_SKILL_CATALOG`, then the
  * legacy `BUFF_*`), then `skills.catalogHint` in the config file, then the
- * default (`match`). Pure and never throws.
- *
- * WHY THIS EXISTS (2026-10-04). 3.3.11 replaced the keyword hint with the full
- * catalog unconditionally — measured live, `buildSkillCatalogHint()` returned
- * 24,543 chars on the goal "create mac od gui app", taking the chat system
- * prompt from 7,653 chars (3.3.10) to 32,809. That ~6.1K-token tax on EVERY
- * turn buried the task for weak/free-tier models and made 16K-token tiers
- * impossible (the prompt alone is ~8.2K). The catalog is a genuinely useful
- * discovery mechanism, but it must be CHOSEN, not imposed.
+ * default (`pointer`). Pure and never throws.
  */
 export declare function resolveSkillHintMode(cm?: ConfigManager): SkillHintMode;
 /**
- * The skill hint for a goal, resolved through the configured mode. The ONE
- * entry point both chat and execute call, so the surface can never drift from
- * the policy:
+ * The skill hint, resolved through the configured mode — the ONE entry point
+ * both the chat/execute loop and the pipeline call, so a surface can never drift
+ * from the policy:
  *   - `off`     → ''
  *   - `catalog` → the full name+description catalog ({@link buildSkillCatalogHint})
  *   - `names`   → the names-only catalog (no descriptions)
- *   - `match`   → the small keyword-matched hint ({@link buildLoopSkillHint})
+ *   - `pointer` → the discovery pointer ({@link buildSkillPointerHint})
  *
- * `injected` is the same out-param `buildLoopSkillHint` takes (the match that
- * was injected, for usage marking) — left untouched in the catalog/names/off
- * modes, where no single skill was selected.
+ * `loadHint` lets the pipeline point its tail at skill_view (the writer's load
+ * path) instead of the loop's skill tool; it is ignored in the catalog modes'
+ * default wording and only affects the tail line.
  */
-export declare function buildConfiguredSkillHint(goal: string, cm?: ConfigManager, injected?: {
-    value: LoopSkillHintMatch | null;
+export declare function buildConfiguredSkillHint(cm?: ConfigManager, opts?: {
+    loadHint?: SkillLoadHint;
 }): Promise<string>;
-/**
- * Mark an injected skill as used (usage tracking parity with the orchestrator
- * — compiled skills only; hub skills have no compiled usage counter). The
- * SINGLE usage marker for the loop hint path (the hint builder never marks).
- * Best-effort, fire-and-forget: never throws, never awaited by callers on the
- * hot path.
- */
-export declare function markLoopSkillUsed(match: LoopSkillHintMatch | null): Promise<void>;
+export {};
 //# sourceMappingURL=loop-skill-hint.d.ts.map

package/dist/tools/loop-skill-hint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop-skill-hint.d.ts","sourceRoot":"","sources":["../../src/tools/loop-skill-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,GAAG,KAAK,CAAC;CAC5B;AA8MD,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACnF,OAAO,CAiDT;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAChG,OAAO,CAIT;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,EAAE,CAAC,EAAE,aAAa,GACjB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAuCpC;AAmCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,EAAE,CAAC,EAAE,aAAa,EAClB,QAAQ,CAAC,EAAE;IAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAA;CAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAsCjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,CAAC,EAAE,aAAa,EAClB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAChF,OAAO,CAAC,MAAM,CAAC,CAiDjB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AAElE,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,EAAE,aAAuB,CAAC;AAK9D;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,aAAa,GAAG,IAAI,CAQvF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,CAAC,EAAE,aAAa,GAAG,aAAa,CAatE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,EACZ,EAAE,CAAC,EAAE,aAAa,EAClB,QAAQ,CAAC,EAAE;IAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAA;CAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvF"}
+{"version":3,"file":"loop-skill-hint.d.ts","sourceRoot":"","sources":["../../src/tools/loop-skill-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAqB1D,0DAA0D;AAC1D,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAsBnF;AAED,mGAAmG;AACnG,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,YAAY,CAAC;AAQxD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,EAAE,CAAC,EAAE,aAAa,EAAE,QAAQ,GAAE,aAA4B,GAAG,OAAO,CAAC,MAAM,CAAC,CAYvH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,CAAC,EAAE,aAAa,EAClB,IAAI,GAAE;IACJ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,aAAa,CAAC;CACrB,GACL,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AAEpE,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,EAAE,aAAyB,CAAC;AAKhE;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,aAAa,GAAG,IAAI,CAQvF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,CAAC,EAAE,aAAa,GAAG,aAAa,CAatE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAC5C,EAAE,CAAC,EAAE,aAAa,EAClB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,aAAa,CAAA;CAAO,GACtC,OAAO,CAAC,MAAM,CAAC,CAOjB"}