@event4u/agent-config 6.1.0 → 7.0.1

package/src/scripts/command_suggester/cooldown.py

@@ -1,132 +0,0 @@
-"""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-command-routing-policy` 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/src/scripts/command_suggester/loader.py

@@ -1,73 +0,0 @@
-"""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.rglob("*.md")):
-        # Skip cluster authoring docs — not commands.
-        if path.name == "AGENTS.md":
-            continue
-        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/src/scripts/command_suggester/match.py

@@ -1,180 +0,0 @@
-"""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/src/scripts/command_suggester/rank.py

@@ -1,120 +0,0 @@
-"""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/src/scripts/command_suggester/render.py

@@ -1,86 +0,0 @@
-"""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."