@event4u/agent-config 6.0.0 → 7.0.0

package/src/scripts/command_suggester/rank.ts

@@ -0,0 +1,201 @@
+/**
+ * Rank scored matches into the final candidate list.
+ *
+ * TypeScript twin of `src/scripts/command_suggester/rank.py`
+ * (ADR-200 py2ts).
+ *
+ * Pipeline:
+ * 1. Drop commands whose name is in `settings.blocklist`.
+ * 2. Drop matches below the effective `confidence_floor` (per-command
+ *    override if set, else global).
+ * 3. Anti-noise:
+ *    - vague-input suppression (short message + many candidates, no structural bonus)
+ *    - lonely-band suppression (single match below `floor + 0.1`, no structural bonus)
+ *    - continuation suppression (message is pure follow-through, no new intent)
+ * 4. Sort by score desc; tie-break:
+ *    - structural bonus wins (named entities outrank generic verbs)
+ *    - longer matched evidence wins (more specific trigger)
+ *    - alphabetic command name wins (stable, deterministic)
+ * 5. Cap at `settings.max_options`.
+ */
+
+import type { CommandSpec, Match, Settings } from './types.js';
+
+const _LONELY_BAND = 0.1; // roadmap Phase 4: floor + 0.1 lonely-match threshold
+
+const _CONTINUATION_PHRASES: ReadonlySet<string> = new Set([
+    // English
+    'ok', 'okay', 'yes', 'no', 'sure', 'go', 'do it', 'go on',
+    'continue', 'next', 'proceed', 'more', 'again',
+    // German
+    'ja', 'nein', 'weiter', 'mach weiter', 'los', 'machen',
+    'weitermachen', 'fortfahren', 'nochmal',
+]);
+
+function _floor_for(
+    name: string,
+    specs_by_name: Map<string, CommandSpec> | ReadonlyMap<string, CommandSpec>,
+    settings: Settings,
+): number {
+    const spec = specs_by_name.get(name);
+    if (spec && spec.confidence_floor !== null) {
+        return spec.confidence_floor;
+    }
+    return settings.confidence_floor;
+}
+
+/**
+ * Short prompts hitting many commands are usually too ambiguous.
+ *
+ * Suppress when:
+ *  - message has < 6 words
+ *  - more than 2 matches survived the floor
+ *  - none of the matches carry a structural bonus (ticket key, path)
+ *
+ * A structural bonus means the prompt was specific even if short
+ * — `"setze ABC-123 um"` is 3 words but unambiguous.
+ */
+function _vague_input_suppression(message: string, matches: Match[]): boolean {
+    const word_count = _pySplitLen(message);
+    if (word_count >= 6 || matches.length <= 2) {
+        return false;
+    }
+    return !matches.some((m) => m.has_structural_bonus);
+}
+
+/**
+ * Python `str.split()` (no args) splits on runs of whitespace and
+ * drops empty leading/trailing tokens. `len(message.split())` is the
+ * whitespace-delimited word count.
+ */
+function _pySplitLen(message: string): number {
+    const trimmed = message.trim();
+    if (trimmed === '') {
+        return 0;
+    }
+    return trimmed.split(/\s+/).length;
+}
+
+/**
+ * Single match whose score sits within `floor + _LONELY_BAND`.
+ *
+ * Roadmap Phase 4 sets this band at 0.1 — a single signal that
+ * barely clears the floor is too uncertain to interrupt for. A
+ * structural bonus (ticket key, path) overrides the suppression
+ * because the match is already grounded in a specific entity.
+ */
+function _sub_floor_lonely_suppression(matches: Match[], floor: number): boolean {
+    if (matches.length !== 1) {
+        return false;
+    }
+    const only = matches[0]!;
+    if (only.has_structural_bonus) {
+        return false;
+    }
+    return only.score < floor + _LONELY_BAND;
+}
+
+/**
+ * Pure follow-through messages carry no new intent — suppress.
+ *
+ * Triggers when the message reduces to a known continuation phrase
+ * (`ok`, `weiter`, `mach weiter`, …) once trailing punctuation is
+ * stripped. A structural bonus (ticket key, path) overrides — even
+ * `"weiter mit ABC-123"` is a fresh intent signal.
+ */
+function _continuation_suppression(message: string, matches: Match[]): boolean {
+    const stripped = _normalizeContinuation(message);
+    if (!stripped) {
+        return false;
+    }
+    if (!_CONTINUATION_PHRASES.has(stripped)) {
+        return false;
+    }
+    return !matches.some((m) => m.has_structural_bonus);
+}
+
+/**
+ * Mirror of `re.sub(r"[\s\W_]+", " ", message, flags=re.UNICODE)
+ * .strip().lower()`.
+ *
+ * Python's `\W` under `re.UNICODE` (the default in Py3) is
+ * "not a Unicode word character" — i.e. anything not a letter, digit,
+ * or underscore in any script. Together with `\s` and `_` the class
+ * collapses every run of non-alphanumeric (across scripts) plus
+ * underscores into a single space. We reproduce that with the `u`
+ * flag and a Unicode property escape so non-ASCII letters/digits are
+ * preserved exactly as Python keeps them.
+ */
+function _normalizeContinuation(message: string): string {
+    const s = message || '';
+    // [^...] = the complement of (Unicode letter | Unicode number).
+    // This equals "[\s\W_]+" because \w (with _) = letter|number|_, so
+    // its complement (\W) ∪ \s ∪ _ collapses to "anything that is not a
+    // letter and not a number".
+    const collapsed = s.replace(/[^\p{L}\p{N}]+/gu, ' ');
+    return collapsed.trim().toLowerCase();
+}
+
+function _tie_break_key(m: Match): [number, number, number, string] {
+    // Score desc, structural bonus first, longer evidence first, alpha last.
+    return [-m.score, m.has_structural_bonus ? 0 : 1, -m.evidence.length, m.command];
+}
+
+export function rank(
+    matches: Iterable<Match>,
+    settings: Settings,
+    specs_by_name: Map<string, CommandSpec> | ReadonlyMap<string, CommandSpec>,
+    options: { raw_message?: string } = {},
+): Match[] {
+    const raw_message = options.raw_message ?? '';
+    if (!settings.enabled) {
+        return [];
+    }
+    const blocked = new Set(settings.blocklist);
+    const candidates: Match[] = [];
+    for (const m of matches) {
+        if (!blocked.has(m.command)) {
+            candidates.push(m);
+        }
+    }
+    const above_floor: Match[] = candidates.filter(
+        (m) => m.score >= _floor_for(m.command, specs_by_name, settings),
+    );
+    if (_continuation_suppression(raw_message, above_floor)) {
+        return [];
+    }
+    if (_vague_input_suppression(raw_message, above_floor)) {
+        return [];
+    }
+    if (_sub_floor_lonely_suppression(above_floor, settings.confidence_floor)) {
+        return [];
+    }
+    above_floor.sort((a, b) => _compareKeys(_tie_break_key(a), _tie_break_key(b)));
+    if (settings.max_options > 0) {
+        return above_floor.slice(0, settings.max_options);
+    }
+    return above_floor;
+}
+
+/** Lexicographic comparison of a (number, number, number, string) tuple. */
+function _compareKeys(
+    a: [number, number, number, string],
+    b: [number, number, number, string],
+): number {
+    if (a[0] !== b[0]) {
+        return a[0] - b[0];
+    }
+    if (a[1] !== b[1]) {
+        return a[1] - b[1];
+    }
+    if (a[2] !== b[2]) {
+        return a[2] - b[2];
+    }
+    if (a[3] < b[3]) {
+        return -1;
+    }
+    if (a[3] > b[3]) {
+        return 1;
+    }
+    return 0;
+}

package/src/scripts/command_suggester/render.ts

@@ -0,0 +1,122 @@
+/**
+ * Render ranked matches as a numbered-options block.
+ *
+ * TypeScript twin of `src/scripts/command_suggester/render.py`
+ * (ADR-200 py2ts).
+ *
+ * Output strictly conforms to `user-interaction` Iron Law:
+ *  - Every option is one numbered line.
+ *  - Options block stays neutral (no inline `(recommended)` tag).
+ *  - Exactly one `Recommendation: N — …` line follows the block.
+ *  - The last numbered option is the as-is escape hatch — always
+ *    present, no exceptions.
+ *
+ * The renderer is purely structural — it does not pick a recommendation
+ * based on free judgment. The first match (highest score, most
+ * specific evidence) becomes the recommendation; ties leave the line
+ * out so the agent doesn't fabricate a tie-break the user didn't ask
+ * for.
+ */
+
+import type { CommandSpec, Match } from './types.js';
+
+export const AS_IS_LABEL = 'Just run the prompt as-is, no command';
+
+/**
+ * Python `len(s)` / slicing on a `str` operate on Unicode code points.
+ * `[...s]` iterates by code point, so an array of code points + join
+ * reproduces `len(s)` and `s[:n]` exactly for any character (BMP or
+ * astral). Description trimming uses both, so we match it precisely.
+ */
+function _pyCodePoints(s: string): string[] {
+    return Array.from(s);
+}
+
+/**
+ * Return the numbered-options block as plain markdown text.
+ *
+ * Empty `matches` ⇒ empty string. The rule never emits anything
+ * when nothing crossed the floor.
+ */
+export function render(
+    matches: Match[],
+    specs_by_name: Map<string, CommandSpec> | ReadonlyMap<string, CommandSpec>,
+    options: { as_is_label?: string } = {},
+): string {
+    const as_is_label = options.as_is_label ?? AS_IS_LABEL;
+    if (!matches.length) {
+        return '';
+    }
+    const lines: string[] = [];
+    for (let idx = 0; idx < matches.length; idx += 1) {
+        const m = matches[idx]!;
+        const i = idx + 1;
+        const spec = specs_by_name.get(m.command);
+        let desc = spec && spec.description ? spec.description : '';
+        // Trim long descriptions for one-line option labels.
+        const cps = _pyCodePoints(desc);
+        if (cps.length > 120) {
+            // Python: desc[:117].rstrip() + "..."
+            desc = `${_pyRstrip(cps.slice(0, 117).join(''))}...`;
+        }
+        const slash = `/${m.command}`;
+        if (desc) {
+            lines.push(`> ${i}. ${slash} — ${desc}`);
+        } else {
+            lines.push(`> ${i}. ${slash}`);
+        }
+    }
+    const as_is_index = matches.length + 1;
+    lines.push(`> ${as_is_index}. ${as_is_label}`);
+    const block = lines.join('\n');
+    const rec_line = _recommendation_line(matches, specs_by_name);
+    if (rec_line) {
+        return `${block}\n\n${rec_line}`;
+    }
+    return block;
+}
+
+/**
+ * Mirror of Python `str.rstrip()` with no args — strips trailing
+ * Unicode whitespace.
+ */
+function _pyRstrip(s: string): string {
+    return s.replace(/\s+$/u, '');
+}
+
+/**
+ * Single-source recommendation per `user-interaction` Iron Law.
+ *
+ * No recommendation when the top two matches are within 0.05 of
+ * each other — surfacing a winner there would be fabrication.
+ */
+function _recommendation_line(
+    matches: Match[],
+    specs_by_name: Map<string, CommandSpec> | ReadonlyMap<string, CommandSpec>,
+): string {
+    if (!matches.length) {
+        return '';
+    }
+    if (matches.length >= 2 && (matches[0]!.score - matches[1]!.score) < 0.05) {
+        return '';
+    }
+    const top = matches[0]!;
+    const spec = specs_by_name.get(top.command) ?? null;
+    const name = top.command;
+    const rationale = _rationale_for(top, spec);
+    return `**Recommendation: 1 — /${name}** — ${rationale}`;
+}
+
+function _rationale_for(match: Match, spec: CommandSpec | null): string {
+    // `spec` is unused (mirrors the Python signature, which also ignores it).
+    void spec;
+    let why: string;
+    if (match.matched_trigger === 'both') {
+        why = `both the request and context match (\`${match.evidence}\`)`;
+    } else if (match.matched_trigger === 'description') {
+        why = `the request matches its trigger description (\`${match.evidence}\`)`;
+    } else {
+        why = `the surrounding context matches its trigger (\`${match.evidence}\`)`;
+    }
+    return `${why}. Pick the last option to skip the command and run the prompt as written.`;
+}

package/src/scripts/command_suggester/sanitize.ts

@@ -0,0 +1,114 @@
+/**
+ * Sanitize matcher input to prevent self-echo and quoted-code triggering.
+ *
+ * TypeScript twin of `src/scripts/command_suggester/sanitize.py`
+ * (ADR-200 py2ts).
+ *
+ * The suggestion engine scores against the user's raw message and the
+ * last 2 turns of context. Two adversarial inputs would otherwise
+ * re-trigger the engine on its own output or on user-pasted code:
+ *
+ *  - Self-echo — the previous turn's suggestion block (`> 1. /commit
+ *    — …`) is part of the conversation context. Scoring against it
+ *    re-surfaces the same commands turn after turn.
+ *  - Quoted code — user-pasted snippets that mention a command
+ *    (`` `/implement-ticket` ``, fenced ``` ```bash\ngit commit``` ```)
+ *    read like real intent signals to the substring matcher.
+ *
+ * Both patterns are stripped here before the matcher sees them. The
+ * sanitiser is conservative: only well-formed Markdown fences,
+ * inline-code spans, and the engine's own suggestion-line shape are
+ * removed. Plain prose is untouched so legitimate intent ("commit my
+ * changes please") still scores.
+ */
+
+// Triple-backtick fence — handles language hints (```bash …```) and
+// unhinted blocks alike. Non-greedy so adjacent fences don't merge.
+// Python `re.DOTALL` → JS `s` flag.
+const _CODE_FENCE_RE = /```[\s\S]*?```/g;
+// Inline code span. Excludes empty `` `` `` and respects single-line scope.
+const _INLINE_CODE_RE = /`[^`\n]+`/g;
+// Suggestion-block line shape from `render.py`:
+//   > 1. /implement-ticket — drive ticket end-to-end…
+//   > 2. /refine-ticket — tighten the AC…
+// Numbered-options lines starting with `>` and a `/command` token.
+// Python `re.MULTILINE` → JS `m` flag; `$` then matches end-of-line.
+const _SUGGESTION_LINE_RE =
+    /^\s*>\s*\d+\.\s*\/[A-Za-z][A-Za-z0-9_-]*\b.*$/gm;
+// As-is escape hatch line — recognisable suffix from render.py.
+const _AS_IS_LINE_RE =
+    /^\s*>\s*\d+\.\s*Just run the prompt as-is.*$/gim;
+// Header line emitted by render.py.
+const _SUGGESTION_HEADER_RE =
+    /^\s*>\s*💡\s*Your request matches a command.*$/gm;
+// Recommendation line right after the block.
+const _RECOMMENDATION_LINE_RE =
+    /^\s*\*\*Recommendation:\s*\d+\b.*$/gm;
+
+/**
+ * Remove fenced and inline code spans.
+ *
+ * Fenced blocks first (greedy across newlines, non-greedy across
+ * fences), then inline backticks. Plain text outside code is left
+ * bit-identical.
+ */
+export function strip_code_blocks(text: string): string {
+    if (!text) {
+        return text;
+    }
+    let out = text.replace(_CODE_FENCE_RE, ' ');
+    out = out.replace(_INLINE_CODE_RE, ' ');
+    return out;
+}
+
+/**
+ * Remove lines that look like the engine's own previous output.
+ *
+ * Matches the four shapes `render.py` emits:
+ *  - the `> 💡 …` header
+ *  - `> N. /command — …` numbered options
+ *  - the `> N. Just run the prompt as-is …` escape hatch
+ *  - the `**Recommendation: N — …` follow-up line
+ *
+ * Anything else (including user-authored quotes that happen to
+ * mention a command) is preserved — only the engine's distinctive
+ * block shape is filtered.
+ */
+export function strip_suggestion_echo(text: string): string {
+    if (!text) {
+        return text;
+    }
+    let out = text.replace(_SUGGESTION_HEADER_RE, '');
+    out = out.replace(_SUGGESTION_LINE_RE, '');
+    out = out.replace(_AS_IS_LINE_RE, '');
+    out = out.replace(_RECOMMENDATION_LINE_RE, '');
+    return out;
+}
+
+/**
+ * Apply both filters to a single user message.
+ *
+ * Order matters: strip code first (a `/command` inside a fence is
+ * code, not an echo), then strip echoes from what remains.
+ */
+export function sanitize_message(message: string): string {
+    return strip_suggestion_echo(strip_code_blocks(message));
+}
+
+/**
+ * Apply `sanitize_message` to each line of recent-turn context.
+ *
+ * Returns a new list — the caller's list is untouched. Empty strings
+ * after sanitising are kept out of the result so they don't dilute
+ * token-overlap scoring.
+ */
+export function sanitize_context(context_lines: Iterable<string>): string[] {
+    const out: string[] = [];
+    for (const line of context_lines) {
+        const cleaned = sanitize_message(line);
+        if (cleaned && cleaned.trim()) {
+            out.push(cleaned);
+        }
+    }
+    return out;
+}

package/src/scripts/command_suggester/settings.ts

@@ -0,0 +1,186 @@
+/**
+ * Read `commands.suggestion.*` from `.agent-settings.yml` into `Settings`.
+ *
+ * TypeScript twin of `src/scripts/command_suggester/settings.py`
+ * (ADR-200 py2ts). Mirror of the chat-history pattern:
+ *
+ *  - Default-permissive: a missing file or missing section returns
+ *    `Settings()` defaults (suggestion layer enabled). Only an explicit
+ *    `enabled: false` flips the master switch off.
+ *  - Malformed YAML / unreadable file → defaults; the suggester degrades
+ *    silently rather than crashing the turn.
+ *  - Type-coerces with bounded fallbacks (floors clamped 0.0-1.0, ints
+ *    non-negative, blocklist forced to an array of strings).
+ *
+ * The Python module reads the YAML via the shared `agent_settings`
+ * loader; this twin delegates to the ported `agent_settings.ts`.
+ */
+
+import { load_agent_settings } from '../_lib/agent_settings.js';
+import { Settings } from './types.js';
+
+export const DEFAULT_SETTINGS_FILE = '.agent-settings.yml';
+
+const _DEFAULT = new Settings();
+
+/**
+ * Return a `Settings` instance hydrated from `.agent-settings.yml`.
+ *
+ * `settings_path` is an explicit override. `null` / `undefined`
+ * resolves to `./.agent-settings.yml` relative to the current working
+ * directory — same convention as `chat_history`.
+ */
+export function load_settings(settings_path?: string | null): Settings {
+    const path = settings_path ? settings_path : DEFAULT_SETTINGS_FILE;
+    const raw = _read_section(path);
+    if (raw === null) {
+        return _DEFAULT;
+    }
+    return _settings_from_raw(raw);
+}
+
+/**
+ * Return the `commands.suggestion` mapping or `null` on any miss.
+ *
+ * The tolerance contract handles missing file / malformed YAML /
+ * absent section uniformly. No `commands.*` keys are whitelisted in
+ * the user-global cascade, so user-global cannot cascade into this
+ * section.
+ */
+function _read_section(path: string): Record<string, unknown> | null {
+    const data = load_agent_settings({ project_path: path });
+    const commands = (data as Record<string, unknown>).commands;
+    if (!_isPlainObject(commands)) {
+        return null;
+    }
+    const section = commands.suggestion;
+    if (!_isPlainObject(section)) {
+        return null;
+    }
+    return section;
+}
+
+function _settings_from_raw(raw: Record<string, unknown>): Settings {
+    return new Settings({
+        enabled: _coerce_bool(raw.enabled, _DEFAULT.enabled),
+        confidence_floor: _coerce_floor(raw.confidence_floor, _DEFAULT.confidence_floor),
+        cooldown_seconds: _coerce_nonneg_int(raw.cooldown_seconds, _DEFAULT.cooldown_seconds),
+        max_options: _coerce_nonneg_int(raw.max_options, _DEFAULT.max_options),
+        blocklist: _coerce_str_tuple(raw.blocklist),
+    });
+}
+
+function _coerce_bool(value: unknown, defaultValue: boolean): boolean {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (value === null || value === undefined) {
+        return defaultValue;
+    }
+    if (typeof value === 'string') {
+        const s = value.trim().toLowerCase();
+        if (['true', 'yes', 'on', '1'].includes(s)) {
+            return true;
+        }
+        if (['false', 'no', 'off', '0'].includes(s)) {
+            return false;
+        }
+    }
+    return defaultValue;
+}
+
+function _coerce_floor(value: unknown, defaultValue: number): number {
+    const f = _pyFloat(value);
+    if (f === null) {
+        return defaultValue;
+    }
+    if (f < 0.0) {
+        return 0.0;
+    }
+    if (f > 1.0) {
+        return 1.0;
+    }
+    return f;
+}
+
+function _coerce_nonneg_int(value: unknown, defaultValue: number): number {
+    const i = _pyInt(value);
+    if (i === null) {
+        return defaultValue;
+    }
+    return i >= 0 ? i : defaultValue;
+}
+
+function _coerce_str_tuple(value: unknown): string[] {
+    // Python: `if not isinstance(value, Iterable) or isinstance(value, (str, bytes))`
+    // → only non-string iterables pass; here, arrays. (YAML never yields
+    // bytes; strings are excluded just like Python.)
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const out: string[] = [];
+    for (const item of value) {
+        if (typeof item === 'string' && item.trim()) {
+            out.push(item.trim());
+        }
+    }
+    return out;
+}
+
+/**
+ * Mirror of Python `float(value)`, returning null where Python raises
+ * `TypeError` / `ValueError` (the coercion catches those and falls
+ * back to the default).
+ */
+function _pyFloat(value: unknown): number | null {
+    if (typeof value === 'boolean') {
+        return value ? 1.0 : 0.0;
+    }
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const s = value.trim();
+        if (s === '') {
+            return null;
+        }
+        const n = Number(s);
+        return Number.isNaN(n) ? null : n;
+    }
+    return null;
+}
+
+/**
+ * Mirror of Python `int(value)` for the YAML scalar types, returning
+ * null where Python raises.
+ *
+ *  - bool → 1 / 0.
+ *  - int  → itself.
+ *  - float → truncated toward zero (Python `int(3.9) == 3`).
+ *  - string → `int(str, 10)` semantics: an optional sign + digits,
+ *    surrounding whitespace allowed; a float-shaped string raises in
+ *    Python, so it maps to null.
+ */
+function _pyInt(value: unknown): number | null {
+    if (typeof value === 'boolean') {
+        return value ? 1 : 0;
+    }
+    if (typeof value === 'number') {
+        if (Number.isNaN(value) || !Number.isFinite(value)) {
+            return null;
+        }
+        return Math.trunc(value);
+    }
+    if (typeof value === 'string') {
+        const s = value.trim();
+        if (!/^[+-]?\d+$/.test(s)) {
+            return null;
+        }
+        return parseInt(s, 10);
+    }
+    return null;
+}
+
+function _isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}