@event4u/agent-config 1.13.0 → 1.15.0

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."

package/scripts/command_suggester/sanitize.py

@@ -0,0 +1,113 @@
+"""Sanitize matcher input to prevent self-echo and quoted-code triggering.
+
+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.
+"""
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+# Triple-backtick fence — handles language hints (```bash …```) and
+# unhinted blocks alike. Non-greedy so adjacent fences don't merge.
+_CODE_FENCE_RE = re.compile(r"```.*?```", re.DOTALL)
+# Inline code span. Excludes empty `` `` `` and respects single-line scope.
+_INLINE_CODE_RE = re.compile(r"`[^`\n]+`")
+# 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.
+_SUGGESTION_LINE_RE = re.compile(
+    r"^\s*>\s*\d+\.\s*/[A-Za-z][A-Za-z0-9_-]*\b.*$",
+    re.MULTILINE,
+)
+# As-is escape hatch line — recognisable suffix from render.py.
+_AS_IS_LINE_RE = re.compile(
+    r"^\s*>\s*\d+\.\s*Just run the prompt as-is.*$",
+    re.MULTILINE | re.IGNORECASE,
+)
+# Header line emitted by render.py.
+_SUGGESTION_HEADER_RE = re.compile(
+    r"^\s*>\s*💡\s*Your request matches a command.*$",
+    re.MULTILINE,
+)
+# Recommendation line right after the block.
+_RECOMMENDATION_LINE_RE = re.compile(
+    r"^\s*\*\*Recommendation:\s*\d+\b.*$",
+    re.MULTILINE,
+)
+
+
+def strip_code_blocks(text: str) -> str:
+    """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.
+    """
+    if not text:
+        return text
+    out = _CODE_FENCE_RE.sub(" ", text)
+    out = _INLINE_CODE_RE.sub(" ", out)
+    return out
+
+
+def strip_suggestion_echo(text: str) -> str:
+    """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.
+    """
+    if not text:
+        return text
+    out = _SUGGESTION_HEADER_RE.sub("", text)
+    out = _SUGGESTION_LINE_RE.sub("", out)
+    out = _AS_IS_LINE_RE.sub("", out)
+    out = _RECOMMENDATION_LINE_RE.sub("", out)
+    return out
+
+
+def sanitize_message(message: str) -> str:
+    """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.
+    """
+    return strip_suggestion_echo(strip_code_blocks(message))
+
+
+def sanitize_context(context_lines: Iterable[str]) -> list[str]:
+    """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.
+    """
+    out: list[str] = []
+    for line in context_lines:
+        cleaned = sanitize_message(line)
+        if cleaned and cleaned.strip():
+            out.append(cleaned)
+    return out

package/scripts/command_suggester/settings.py

@@ -0,0 +1,125 @@
+"""Read `commands.suggestion.*` from `.agent-settings.yml` into `Settings`.
+
+Mirror of the chat-history pattern (`scripts/chat_history.py`):
+
+* Lazy PyYAML import — the engine works without yaml installed when no
+  settings file is present (test fixtures, cloud bundles).
+* 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 a tuple of strings).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Iterable
+
+from .types import Settings
+
+DEFAULT_SETTINGS_FILE = ".agent-settings.yml"
+
+_DEFAULT = Settings()
+
+
+def load_settings(settings_path: Path | str | None = None) -> Settings:
+    """Return a `Settings` instance hydrated from `.agent-settings.yml`.
+
+    Parameters
+    ----------
+    settings_path:
+        Explicit override. ``None`` resolves to ``./.agent-settings.yml``
+        relative to the current working directory — same convention as
+        ``chat_history``.
+    """
+    path = Path(settings_path) if settings_path else Path(DEFAULT_SETTINGS_FILE)
+    raw = _read_section(path)
+    if raw is None:
+        return _DEFAULT
+    return _settings_from_raw(raw)
+
+
+def _read_section(path: Path) -> dict[str, Any] | None:
+    """Return the ``commands.suggestion`` mapping or ``None`` on any miss."""
+    if not path.is_file():
+        return None
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        return None
+    try:
+        with path.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    commands = data.get("commands")
+    if not isinstance(commands, dict):
+        return None
+    section = commands.get("suggestion")
+    if not isinstance(section, dict):
+        return None
+    return section
+
+
+def _settings_from_raw(raw: dict[str, Any]) -> Settings:
+    return Settings(
+        enabled=_coerce_bool(raw.get("enabled"), _DEFAULT.enabled),
+        confidence_floor=_coerce_floor(
+            raw.get("confidence_floor"), _DEFAULT.confidence_floor
+        ),
+        cooldown_seconds=_coerce_nonneg_int(
+            raw.get("cooldown_seconds"), _DEFAULT.cooldown_seconds
+        ),
+        max_options=_coerce_nonneg_int(
+            raw.get("max_options"), _DEFAULT.max_options
+        ),
+        blocklist=_coerce_str_tuple(raw.get("blocklist")),
+    )
+
+
+def _coerce_bool(value: Any, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    if isinstance(value, str):
+        s = value.strip().lower()
+        if s in ("true", "yes", "on", "1"):
+            return True
+        if s in ("false", "no", "off", "0"):
+            return False
+    return default
+
+
+def _coerce_floor(value: Any, default: float) -> float:
+    try:
+        f = float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return default
+    if f < 0.0:
+        return 0.0
+    if f > 1.0:
+        return 1.0
+    return f
+
+
+def _coerce_nonneg_int(value: Any, default: int) -> int:
+    try:
+        i = int(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return default
+    return i if i >= 0 else default
+
+
+def _coerce_str_tuple(value: Any) -> tuple[str, ...]:
+    if not isinstance(value, Iterable) or isinstance(value, (str, bytes)):
+        return ()
+    out: list[str] = []
+    for item in value:
+        if isinstance(item, str) and item.strip():
+            out.append(item.strip())
+    return tuple(out)