@event4u/agent-config 1.13.0 → 1.14.0

package/scripts/command_suggester/cooldown.py

@@ -0,0 +1,132 @@
+"""Suppress recently-shown suggestions per conversation.
+
+Cooldown key is `(command_name, evidence)` so two distinct triggers
+for the same command (e.g. `/commit` from "git status shows changes"
+vs. from "save this to git") track separately. The user explicitly
+invoking a command via `/command` clears that command's cooldown so
+the next genuine match surfaces immediately.
+
+The store is in-memory; persistence is the agent's job (conversation
+state). Phase 5 wires the per-conversation `disabled_for_conversation`
+flag into the same store.
+"""
+from __future__ import annotations
+
+import re
+import time
+from typing import Mapping
+
+from .types import CommandSpec, CooldownState, Match, Settings
+
+
+_DURATION_RE = re.compile(r"^\s*(\d+)\s*([smhd])\s*$", re.IGNORECASE)
+_DISABLE_DIRECTIVE_RE = re.compile(
+    r"(?:^|\s)/command-suggestion-(off|on)\b", re.IGNORECASE
+)
+_EXPLICIT_SLASH_RE = re.compile(r"^\s*/[A-Za-z][A-Za-z0-9_-]*\b")
+
+
+def is_explicit_slash_invocation(message: str) -> bool:
+    """Return True when the message starts with an explicit ``/command``.
+
+    Per the `command-suggestion` rule, explicit slash invocations
+    bypass the suggestion layer entirely \u2014 they're handled by
+    `slash-commands` directly. The engine should not score in that
+    case. Helper exposed for the runtime caller and the GT-CS4
+    golden.
+    """
+    if not message:
+        return False
+    return bool(_EXPLICIT_SLASH_RE.match(message))
+
+
+def detect_disable_directive(message: str) -> bool | None:
+    """Detect a `/command-suggestion-off` / `-on` directive in the user message.
+
+    Returns ``True`` to disable for the rest of the conversation,
+    ``False`` to re-enable, ``None`` when no directive is present.
+    The latest occurrence in the message wins (order-stable on tie).
+    Mutating the `CooldownStore` is the caller's responsibility — this
+    helper stays pure so tests don't have to fake time.
+    """
+    if not message:
+        return None
+    last: bool | None = None
+    for m in _DISABLE_DIRECTIVE_RE.finditer(message):
+        last = m.group(1).lower() == "off"
+    return last
+
+
+def parse_cooldown(value: str | None, default_seconds: int) -> int:
+    """Convert `'10m'` / `'30s'` / `'1h'` / `'2d'` to seconds.
+
+    Returns ``default_seconds`` for any malformed or missing input —
+    keeping the runtime fail-soft. The schema validator caps the
+    string length, so we never see absurd inputs in practice.
+    """
+    if not value:
+        return default_seconds
+    m = _DURATION_RE.match(str(value))
+    if not m:
+        return default_seconds
+    n, unit = int(m.group(1)), m.group(2).lower()
+    factor = {"s": 1, "m": 60, "h": 3600, "d": 86400}[unit]
+    return n * factor
+
+
+class CooldownStore:
+    """Thin wrapper around `CooldownState` with time-aware helpers.
+
+    Tests inject a fixed `now` to make decay deterministic; runtime
+    leaves it as `time.time`.
+    """
+
+    def __init__(self, state: CooldownState | None = None, *, now=time.time):
+        self.state = state or CooldownState()
+        self._now = now
+
+    def is_cooled_down(
+        self, command: str, evidence: str, *, window_seconds: int
+    ) -> bool:
+        last = self.state.last_shown.get((command, evidence))
+        if last is None:
+            return False
+        return (self._now() - last) < window_seconds
+
+    def record_shown(self, matches: list[Match]) -> None:
+        ts = self._now()
+        for m in matches:
+            self.state.last_shown[(m.command, m.evidence)] = ts
+
+    def record_explicit_invocation(self, command: str) -> None:
+        """Clear the cooldown when the user explicitly types `/command`.
+
+        We drop every entry for that command (across all evidences)
+        so a deliberate invocation always produces a clean slate.
+        """
+        ts = self._now()
+        self.state.explicit_invocations[command] = ts
+        keys_to_drop = [
+            k for k in self.state.last_shown if k[0] == command
+        ]
+        for k in keys_to_drop:
+            del self.state.last_shown[k]
+
+
+def apply_cooldown(
+    matches: list[Match],
+    store: CooldownStore,
+    settings: Settings,
+    specs_by_name: Mapping[str, CommandSpec],
+) -> list[Match]:
+    if store.state.disabled_for_conversation:
+        return []
+    out: list[Match] = []
+    for m in matches:
+        spec = specs_by_name.get(m.command)
+        per_cmd = spec.cooldown if spec else None
+        window = parse_cooldown(per_cmd, settings.cooldown_seconds)
+        if store.is_cooled_down(m.command, m.evidence, window_seconds=window):
+            continue
+        out.append(m)
+    return out

package/scripts/command_suggester/loader.py

@@ -0,0 +1,70 @@
+"""Read command frontmatter into `CommandSpec` instances.
+
+Reuses the package's stdlib-only `validate_frontmatter.parse_frontmatter`
+so the loader and the linter agree on what counts as well-formed.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from .types import CommandSpec
+
+# Sibling stdlib parser — same one the linter calls.
+_SCRIPTS_DIR = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_SCRIPTS_DIR))
+from validate_frontmatter import parse_frontmatter  # noqa: E402
+
+
+def load_commands(commands_dir: Path) -> list[CommandSpec]:
+    """Load every `*.md` under ``commands_dir`` as a `CommandSpec`.
+
+    Files without a `suggestion` block are loaded as `eligible=False`
+    with empty rationale — keeps tests deterministic on legacy data.
+    Bad frontmatter is skipped silently; the linter is the gate, not
+    this loader.
+    """
+    specs: list[CommandSpec] = []
+    for path in sorted(commands_dir.glob("*.md")):
+        text = path.read_text(encoding="utf-8")
+        data, _offset = parse_frontmatter(text)
+        if data is None:
+            continue
+        name = str(data.get("name") or path.stem)
+        description = str(data.get("description") or "")
+        spec = _spec_from_data(name, description, data.get("suggestion"))
+        specs.append(spec)
+    return specs
+
+
+def _spec_from_data(
+    name: str, description: str, suggestion: Any
+) -> CommandSpec:
+    if not isinstance(suggestion, dict):
+        return CommandSpec(name=name, description=description, eligible=False)
+    eligible = suggestion.get("eligible") is True
+    if not eligible:
+        return CommandSpec(
+            name=name,
+            description=description,
+            eligible=False,
+            rationale=str(suggestion.get("rationale") or ""),
+        )
+    floor = suggestion.get("confidence_floor")
+    floor_f: float | None
+    try:
+        floor_f = float(floor) if floor is not None else None
+    except (TypeError, ValueError):
+        floor_f = None
+    cooldown = suggestion.get("cooldown")
+    cooldown_s = str(cooldown) if cooldown is not None else None
+    return CommandSpec(
+        name=name,
+        description=description,
+        eligible=True,
+        trigger_description=str(suggestion.get("trigger_description") or ""),
+        trigger_context=str(suggestion.get("trigger_context") or ""),
+        confidence_floor=floor_f,
+        cooldown=cooldown_s,
+    )

package/scripts/command_suggester/match.py

@@ -0,0 +1,180 @@
+"""Score eligible commands against a user message + recent context.
+
+Deterministic, no ML, no third-party deps. Two signals combine into
+a 0.0–1.0 score:
+
+* **Description match** — strongest single signal.
+  - Long phrase substring (≥ 10 chars) → 0.65.
+  - Short phrase substring (6–9 chars) → 0.4.
+  - Otherwise content-word overlap (≥ 4-char tokens, stop-words
+    stripped) scaled to 0.4.
+* **Context match** — supporting evidence.
+  - Structural pattern (ticket key, file path, glob) co-occurring
+    in the message → 0.5.
+  - Otherwise content-word overlap scaled to 0.3.
+
+Total `score = min(1.0, description_score + context_score)`. A long
+phrase hit alone clears the default 0.6 floor; structural patterns
+alone do not (anti-noise) — they need a description signal too.
+A `Match.has_structural_bonus` flag lets the ranker know when a
+short, otherwise-ambiguous prompt is actually specific (ticket
+keys, paths) so it can override vague-input suppression.
+"""
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+from .sanitize import sanitize_context, sanitize_message
+from .types import CommandSpec, Match
+
+_TICKET_RE = re.compile(r"[A-Z][A-Z0-9]+-\d+")
+_WORD_RE = re.compile(r"[A-Za-z][A-Za-z0-9_-]{3,}")
+_PATH_RE = re.compile(r"[A-Za-z0-9_./-]+/[A-Za-z0-9_.*-]+")
+_STOPWORDS: frozenset[str] = frozenset({
+    "this", "that", "with", "from", "have", "what", "when", "they",
+    "them", "into", "would", "could", "should", "about", "there",
+    "these", "those", "their", "your", "mine", "ours", "yours",
+    "show", "tell", "make", "want", "need", "like", "just", "some",
+    "many", "more", "most", "less", "than", "then", "also", "very",
+})
+
+
+def _tokens(text: str) -> set[str]:
+    return {
+        w.lower() for w in _WORD_RE.findall(text or "")
+        if w.lower() not in _STOPWORDS
+    }
+
+
+def _phrases(trigger_description: str) -> list[str]:
+    return [
+        p.strip().lower() for p in (trigger_description or "").split(",")
+        if p.strip()
+    ]
+
+
+def _phrase_substring_hit(phrases: list[str], hay: str) -> str | None:
+    """Return the longest phrase that occurs as a substring, else None.
+
+    Falls back to a hyphen-normalized hay so e.g. `"create pr"` still
+    matches `"create-pr"` in a path or branch reference.
+    """
+    best: str | None = None
+    hay_norm = hay.replace("-", " ")
+    for p in sorted(phrases, key=len, reverse=True):
+        if len(p) < 6:
+            continue
+        if p in hay or p in hay_norm:
+            return p
+    return best
+
+
+def _structural_bonus(spec: CommandSpec, message: str) -> str | None:
+    """Heavy-signal patterns that score context fully (0.5).
+
+    Ticket keys (`ABC-123`) and file paths in the spec's
+    `trigger_context` only count when they actually appear in the
+    message — `trigger_context` advertises *which* signals matter,
+    the message provides them.
+    """
+    ctx_lower = (spec.trigger_context or "").lower()
+    msg_lower = message.lower()
+    if "ticket" in ctx_lower or "proj-" in ctx_lower or "[a-z]+-[0-9]+" in ctx_lower:
+        m = _TICKET_RE.search(message)
+        if m:
+            return m.group(0)
+    for path in _PATH_RE.findall(spec.trigger_context or ""):
+        if path.lower() in msg_lower:
+            return path
+    return None
+
+
+def _description_score(spec: CommandSpec, message: str, ctx_text: str) -> tuple[float, str]:
+    phrases = _phrases(spec.trigger_description)
+    hay = (message + " \n " + ctx_text).lower()
+    hit = _phrase_substring_hit(phrases, hay)
+    if hit:
+        # Long phrase substring is the strongest signal — clears the
+        # default 0.6 floor on its own. Short phrases need context.
+        return (0.65 if len(hit) >= 10 else 0.4), hit
+    spec_tokens = _tokens(spec.trigger_description)
+    if not spec_tokens:
+        return 0.0, ""
+    msg_tokens = _tokens(message) | _tokens(ctx_text)
+    common = spec_tokens & msg_tokens
+    if not common:
+        return 0.0, ""
+    score = 0.4 * (len(common) / len(spec_tokens))
+    return score, sorted(common)[0]
+
+
+def _context_score(
+    spec: CommandSpec, message: str, ctx_text: str
+) -> tuple[float, str, bool]:
+    """Returns (score, evidence, has_structural_bonus)."""
+    bonus = _structural_bonus(spec, message)
+    if bonus:
+        return 0.5, bonus, True
+    spec_tokens = _tokens(spec.trigger_context)
+    if not spec_tokens:
+        return 0.0, "", False
+    msg_tokens = _tokens(message) | _tokens(ctx_text)
+    common = spec_tokens & msg_tokens
+    if not common:
+        return 0.0, "", False
+    score = 0.3 * (len(common) / len(spec_tokens))
+    return score, sorted(common)[0], False
+
+
+def match(
+    message: str,
+    context: Iterable[str] = (),
+    commands: Iterable[CommandSpec] = (),
+    *,
+    sanitize: bool = True,
+) -> list[Match]:
+    """Return scored matches sorted by descending score (ties stable).
+
+    Eligible commands only; ineligible ones are silently skipped. The
+    caller is responsible for ranking, cooldown, and rendering.
+
+    ``sanitize`` (default ``True``) strips fenced/inline code and
+    previous suggestion-block echoes from both the message and the
+    last 2 turns of context. The flag is exposed for tests that
+    exercise the raw scoring path; runtime callers should leave it
+    on.
+    """
+    if sanitize:
+        message = sanitize_message(message)
+        cleaned_ctx = sanitize_context(context)
+    else:
+        cleaned_ctx = list(context)
+    ctx_text = "\n".join(cleaned_ctx[-2:])  # last 2 turns max
+    matches: list[Match] = []
+    for spec in commands:
+        if not spec.eligible:
+            continue
+        d_score, d_evidence = _description_score(spec, message, ctx_text)
+        c_score, c_evidence, structural = _context_score(spec, message, ctx_text)
+        score = round(min(1.0, d_score + c_score), 4)
+        if score <= 0:
+            continue
+        if d_score > 0 and c_score > 0:
+            kind = "both"
+            evidence = d_evidence if len(d_evidence) >= len(c_evidence) else c_evidence
+        elif d_score > 0:
+            kind = "description"
+            evidence = d_evidence
+        else:
+            kind = "context"
+            evidence = c_evidence
+        matches.append(Match(
+            command=spec.name,
+            score=score,
+            matched_trigger=kind,
+            evidence=evidence,
+            has_structural_bonus=structural,
+        ))
+    matches.sort(key=lambda m: (-m.score, m.command))
+    return matches

package/scripts/command_suggester/rank.py

@@ -0,0 +1,120 @@
+"""Rank scored matches into the final candidate list.
+
+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`.
+"""
+from __future__ import annotations
+
+import re
+from typing import Iterable, Mapping
+
+from .types import CommandSpec, Match, Settings
+
+_LONELY_BAND = 0.1  # roadmap Phase 4: floor + 0.1 lonely-match threshold
+
+_CONTINUATION_PHRASES: frozenset[str] = frozenset({
+    # 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",
+})
+
+
+def _floor_for(name: str, specs_by_name: Mapping[str, CommandSpec], settings: Settings) -> float:
+    spec = specs_by_name.get(name)
+    if spec and spec.confidence_floor is not None:
+        return spec.confidence_floor
+    return settings.confidence_floor
+
+
+def _vague_input_suppression(message: str, matches: list[Match]) -> bool:
+    """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.
+    """
+    word_count = len(message.split())
+    if word_count >= 6 or len(matches) <= 2:
+        return False
+    return not any(m.has_structural_bonus for m in matches)
+
+
+def _sub_floor_lonely_suppression(matches: list[Match], floor: float) -> bool:
+    """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.
+    """
+    if len(matches) != 1:
+        return False
+    if matches[0].has_structural_bonus:
+        return False
+    return matches[0].score < floor + _LONELY_BAND
+
+
+def _continuation_suppression(message: str, matches: list[Match]) -> bool:
+    """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.
+    """
+    stripped = re.sub(r"[\s\W_]+", " ", message or "", flags=re.UNICODE).strip().lower()
+    if not stripped:
+        return False
+    if stripped not in _CONTINUATION_PHRASES:
+        return False
+    return not any(m.has_structural_bonus for m in matches)
+
+
+def _tie_break_key(m: Match) -> tuple[float, int, int, str]:
+    # Score desc, structural bonus first, longer evidence first, alpha last.
+    return (-m.score, 0 if m.has_structural_bonus else 1, -len(m.evidence), m.command)
+
+
+def rank(
+    matches: Iterable[Match],
+    settings: Settings,
+    specs_by_name: Mapping[str, CommandSpec],
+    *,
+    raw_message: str = "",
+) -> list[Match]:
+    if not settings.enabled:
+        return []
+    blocked = set(settings.blocklist)
+    candidates: list[Match] = [m for m in matches if m.command not in blocked]
+    above_floor: list[Match] = [
+        m for m in candidates
+        if 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(key=_tie_break_key)
+    if settings.max_options > 0:
+        return above_floor[: settings.max_options]
+    return above_floor

package/scripts/command_suggester/render.py

@@ -0,0 +1,86 @@
+"""Render ranked matches as a numbered-options block.
+
+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.
+"""
+from __future__ import annotations
+
+from typing import Mapping
+
+from .types import CommandSpec, Match
+
+
+AS_IS_LABEL = "Just run the prompt as-is, no command"
+
+
+def render(
+    matches: list[Match],
+    specs_by_name: Mapping[str, CommandSpec],
+    *,
+    as_is_label: str = AS_IS_LABEL,
+) -> str:
+    """Return the numbered-options block as plain markdown text.
+
+    Empty `matches` ⇒ empty string. The rule never emits anything
+    when nothing crossed the floor.
+    """
+    if not matches:
+        return ""
+    lines: list[str] = []
+    for i, m in enumerate(matches, start=1):
+        spec = specs_by_name.get(m.command)
+        desc = spec.description if spec and spec.description else ""
+        # Trim long descriptions for one-line option labels.
+        if len(desc) > 120:
+            desc = desc[:117].rstrip() + "..."
+        slash = f"/{m.command}"
+        if desc:
+            lines.append(f"> {i}. {slash} — {desc}")
+        else:
+            lines.append(f"> {i}. {slash}")
+    as_is_index = len(matches) + 1
+    lines.append(f"> {as_is_index}. {as_is_label}")
+    block = "\n".join(lines)
+    rec_line = _recommendation_line(matches, specs_by_name)
+    if rec_line:
+        return block + "\n\n" + rec_line
+    return block
+
+
+def _recommendation_line(
+    matches: list[Match], specs_by_name: Mapping[str, CommandSpec]
+) -> str:
+    """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.
+    """
+    if not matches:
+        return ""
+    if len(matches) >= 2 and (matches[0].score - matches[1].score) < 0.05:
+        return ""
+    top = matches[0]
+    spec = specs_by_name.get(top.command)
+    name = top.command
+    rationale = _rationale_for(top, spec)
+    return f"**Recommendation: 1 — /{name}** — {rationale}"
+
+
+def _rationale_for(match: Match, spec: CommandSpec | None) -> str:
+    if match.matched_trigger == "both":
+        why = f"both the request and context match (`{match.evidence}`)"
+    elif match.matched_trigger == "description":
+        why = f"the request matches its trigger description (`{match.evidence}`)"
+    else:
+        why = f"the surrounding context matches its trigger (`{match.evidence}`)"
+    return f"{why}. Pick the last option to skip the command and run the prompt as written."