algo-cli-runtime 0.14.0__py3-none-any.whl

algo_cli/resources/skills/qol-algorithms.md

@@ -0,0 +1,224 @@
+---
+name: qol-algorithms
+description: Quality-of-life algorithm patterns for Algo CLI that reduce friction, prevent common errors, and improve terminal UX.
+tags: [algo-cli, qol, algorithms, ux, fuzzy-matching, configuration, suggestions]
+created: 2026-07-02
+---
+
+# Quality of Life (QoL) Algorithms
+
+A compact catalog of medium-priority UX algorithms for Algo CLI. They don't change retrieval correctness, but they make the terminal feel faster, safer, and more forgiving.
+
+## 1. Fuzzy Slash-Command Matcher
+
+**Use for:** turning typos like `/selfcehck`, `/harnes`, or `/modle-check` into "Did you mean `/selfcheck`, `/harness`, `/model-check`?"
+
+**Algorithm:**
+
+```text
+candidates = all registered slash commands + aliases
+for candidate in candidates:
+    d = Damerau-Levenshtein distance(query, candidate)
+    score = 1 - d / max(len(query), len(candidate))
+rank by score descending, filter score >= 0.6
+```
+
+**Why it matters:**
+
+- Users type fast in a terminal; a single transposition shouldn't fail silently.
+- Damerau-Levenshtein handles adjacent swaps (`selfcehck` → `selfcheck`) better than plain Levenshtein.
+- A ranked suggestion is safer than silent auto-correction.
+
+**Harness contract:**
+
+- Input: mistyped slash command string, registered command list.
+- Output: zero or more suggestions with confidence scores.
+- Telemetry: typo count, accepted suggestion, fallback to unknown-command handler.
+
+**Tests:**
+
+- `/selfcehck` suggests `/selfcheck` with score >= 0.8.
+- `/harnes` suggests `/harness` before `/harness-search`.
+- `/totally-unknown` returns no suggestions and falls through.
+- Suggestions are deterministic for a fixed command registry.
+
+## 2. Layered Configuration Precedence
+
+**Use for:** resolving defaults, config file values, environment variables, and per-command flags without surprising overrides.
+
+**Precedence (lowest to highest):**
+
+```text
+built-in default
+config file (algo_cli/config.json)
+environment variable (ALGO_CLI_*)
+per-command flag / runtime override
+```
+
+**Why it matters:**
+
+- Smart defaults reduce setup friction.
+- A clear precedence order prevents "why didn't my env var work?" bugs.
+- Makes telemetry reproducible: log the winning source for each setting.
+
+**Harness contract:**
+
+- Input: setting name, default value, config dict, env mapping, CLI overrides.
+- Output: resolved value plus source provenance.
+- Telemetry: override source counts, unknown config keys.
+
+**Tests:**
+
+- Default wins when no other source provides the value.
+- Env var overrides config file.
+- Runtime flag overrides env var.
+- Unknown config keys are warned, not silently ignored.
+
+## 3. Progressive Command Aliases
+
+**Use for:** letting users type short, memorable forms (`/hs` for `/harness-search`, `/m` for `/model`) without fragmenting the command namespace.
+
+**Algorithm:**
+
+```text
+alias_map = {
+    "hs": "harness-search",
+    "m":  "model",
+    ...
+}
+resolve(input):
+    if input in alias_map: return alias_map[input]
+    if input is a registered command: return input
+    else: pass to fuzzy matcher
+```
+
+**Why it matters:**
+
+- Reduces keystrokes for power users.
+- Keeps help text and telemetry canonical by expanding aliases early.
+- Avoids the trap of many near-duplicate commands.
+
+**Harness contract:**
+
+- Input: raw slash command token.
+- Output: canonical command name or unknown.
+- Telemetry: alias expansion count, collisions.
+
+**Tests:**
+
+- `/hs` resolves to `/harness-search`.
+- Unknown alias falls through to fuzzy matcher.
+- Alias-to-alias chains are flattened or rejected.
+- Help text lists aliases next to canonical names.
+
+## 4. History-Aware Command Suggestions
+
+**Use for:** surfacing likely next commands based on the current session's command history.
+
+**Algorithm:**
+
+```text
+score(cmd) = recency_weight * last_used_seconds_ago^-1
+           + frequency_weight * count_in_session
+           + context_weight * co_occurrence_with_last_cmd
+return top-k, deduplicated
+```
+
+**Why it matters:**
+
+- Repeating a recently used `/harness-search` or `/model` is common.
+- Recency + frequency beats either signal alone.
+- Context boost helps after multi-step workflows (e.g., `/google-login` → `/google-status`).
+
+**Harness contract:**
+
+- Input: session command history, current command, k.
+- Output: ranked suggestion list.
+- Telemetry: suggestion acceptance rate, history length.
+
+**Tests:**
+
+- Most recent unique command appears first.
+- Frequent but stale command is ranked below recent frequent command.
+- Suggestions exclude the command just typed.
+- Empty history returns defaults or nothing.
+
+## 5. Confidence-Gated Auto-Correction
+
+**Use for:** automatically fixing low-risk typos (command names, common flag values) while asking the user when confidence is low.
+
+**Algorithm:**
+
+```text
+if best_suggestion.score >= high_threshold (e.g. 0.85):
+    auto-correct and run
+elif best_suggestion.score >= low_threshold (e.g. 0.60):
+    prompt user: "Did you mean X? [y/n]"
+else:
+    report unknown command
+```
+
+**Why it matters:**
+
+- High-confidence corrections save keystrokes.
+- Low-confidence guesses are destructive if applied silently.
+- A threshold makes the behavior testable and tunable.
+
+**Harness contract:**
+
+- Input: raw input, suggestion list, high/low thresholds.
+- Output: corrected input, prompt, or error.
+- Telemetry: auto-correct count, prompt count, rejection count, threshold breaches.
+
+**Tests:**
+
+- Score 0.90 auto-corrects without prompt.
+- Score 0.70 prompts user.
+- Score 0.40 reports unknown.
+- Thresholds are configurable per command class.
+
+## 6. Mojibake Fixer
+
+**Use for:** cleaning UTF-8 display artifacts (`·`, `…`, `’`, `“`) in harness output.
+
+**Algorithm:** Detect windows-1252 mojibake in otherwise UTF-8 text and replace the byte sequence with the intended Unicode glyph.
+
+**Tests:**
+
+- `algo-cli · wiki ·` becomes `algo-cli · wiki ·`.
+- `periodic…` becomes `periodic…`.
+- `don’t` becomes `don't`.
+
+## 7. Relevance Threshold Filter
+
+**Use for:** suppressing `## Relevant Context` blocks when none of the top-k records are actually relevant.
+
+**Algorithm:**
+
+```text
+filtered = [r for r in ranked if r.score >= min_relevance]
+```
+
+**Tests:**
+
+- If all scores < 0.3, return empty list.
+- If top record > 0.7, include all above 0.3.
+- Log filtered records for debugging.
+
+## 8. Probe Query Linter
+
+**Use for:** validating `/selfcheck` probe queries are real indexed records.
+
+**Algorithm:** Run each probe query through `harness_search`; mark invalid any query that returns no matches.
+
+**Tests:**
+
+- `index-compute-lab` → valid.
+- A retired synthetic label → invalid (no matching record).
+- Log invalid queries to suggest replacements.
+
+## References
+
+- Full spec and harness contracts: `docs/ALGO.reviewed.md` Track B.
+- Fuzzy matching background: Levenshtein and Damerau-Levenshtein edit distance.
+- UX inspiration: fzf, git's DWIM mistyped-command wrapper, smart_config layered defaults.

algo_cli/resources/skills/smart-error-recovery.md

@@ -0,0 +1,56 @@
+---
+name: smart-error-recovery
+description: When a tool returns an error, classify it and pick the right recovery path: tighten input, change tools, ask the user, or escalate to /reason reflexion.
+tags: [algo-cli, error-handling, recovery, reflexion]
+created: 2026-06-09
+---
+
+# Smart Error Recovery
+
+## Trigger
+
+Whenever a tool call returns a string starting with `Error:`.
+
+## Steps
+
+1. **Read the error string verbatim.** It usually contains a hint
+   (e.g. "matched 2 locations" means "tighten old_string" or
+   "pass replace_all=True"; "old_string not found" means "re-read
+   the file and check whitespace").
+2. **Classify** the error:
+   - *Transient* (network, model timeout): retry once with same args,
+     then with timeout bump, then escalate to user.
+   - *Input validation* (empty, ambiguous, missing file): adjust the
+     input and retry.
+   - *Permission denied* (`tool_denied` event, approval needed):
+     stop and ask the user, or check whether `/auto` is on.
+   - *Logical* (no search results, hypothesis wrong): switch tools
+     or change approach.
+3. **If the same tool fails twice in a row:** switch tools or change
+   strategy. Don't keep retrying the same broken call.
+4. **If 3+ different tools have failed on the same goal:** switch to
+   `/reason reflexion` mode, or stop and ask the user for guidance.
+5. **Always narrate the recovery** in the user-facing answer:
+   "I tried X, got Y, so I tried Z instead."
+
+## Key Discoveries
+
+- The 2,000-character tool-result cap in `tools.MAX_TOOL_RESULT` is
+  per-call. For large matches, narrow the search with `glob=` and
+  `path=` arguments rather than asking for everything at once.
+- `harness_search` returns "No harness matches" for both "nothing in
+  the index" and "all matches were excluded by kind filter". Try
+  `kind=None` first to see what's there.
+- `run_shell` has a hard 120s cap regardless of `timeout=` argument.
+  Long-running commands need to be backgrounded and polled, not timed
+  out at 600s and hoped for.
+- `edit_file` is the highest-leverage recovery tool: when a `write_file`
+  call returns "file already exists" or "you need to read the file first",
+  switch to `edit_file` with the exact existing string instead.
+- `session_command` errors with EOFError mean the user typed `/exit` —
+  do not retry, the session is over.
+
+## Environment
+
+algo-cli only. These heuristics are encoded in the system prompt
+verification_layer; this skill captures the long-form reasoning.

algo_cli/resources/skills/tool-selection-cheatsheet.md

@@ -0,0 +1,65 @@
+---
+name: tool-selection-cheatsheet
+description: Quick reference for picking the right tool — read vs search vs harness_search, edit_file vs write_file, run_shell vs session_command.
+tags: [algo-cli, tool-selection, cheatsheet, productivity]
+created: 2026-06-09
+---
+
+# Tool Selection Cheatsheet
+
+## Trigger
+
+When you are about to call a tool and are not 100% sure which one to use.
+
+## Steps
+
+1. If you are looking for **a known file** by path → `read_file` (or
+   `session_slash /read` for deterministic cwd-relative).
+2. If you are looking for **a fact or string** inside any file →
+   `search_files` for direct grep, OR `harness_search` first if the
+   fact might be in a skill/memory/wiki.
+3. If you are looking for **a workflow or how-to** → `harness_search
+   (kind="skill")` first. Use `query_knowledge_graph` for project/entity
+   relations only when `/icl status` reports that integration enabled and ready.
+4. If you need to **change a single specific thing in an existing file**
+   → `edit_file` (find/replace) with 2-5 lines of context.
+5. If you need to **create a new file** → `write_file` (no overwrite).
+6. If you need to **rewrite most of an existing file** → `write_file` with
+   `overwrite=True` after re-reading the target.
+7. If you need to **run tests/builds/lint/diff/grep** → `run_shell` (safe
+   in requires_change blocks; mutations are flagged for approval).
+8. If you need to **change session state** (model, theme, context,
+   harness refresh, route preview) → `session_command` (`/status`,
+   `/mode execute`, `/context status`, `/harness refresh`, `/route TASK`).
+9. If you need to **fetch a URL or search the web** → `web_search` /
+   `web_fetch` (requires OLLAMA_API_KEY for Ollama Cloud).
+10. If you are **unsure what to use** → `available_actions(topic="...")`
+    returns the relevant tools + slash commands for any focus area.
+
+## Key Discoveries
+
+- `edit_file` is preferred over `write_file` for ANY change to an existing
+  file. The cost is the same, but edit_file reports the affected line
+  range, fails on ambiguous matches, and uses fewer tokens (you don't
+  have to read+echo the whole file).
+- `session_slash` is preferred over `read_file` when the path is
+  cwd-relative and the user named the file in a `/read`-style request.
+  It honors `/cd` state.
+- `query_knowledge_graph` can be faster and more relevant than
+  `harness_search` for project/entity questions when the user enabled and
+  populated index-compute-lab. Use it for relationship questions about entities.
+- `harness_search` is preferred over `search_files` when the file
+  might be in a skill/memory/wiki, because the indexer has already
+  parsed frontmatter and scored relevance. `search_files` is the
+  right call for raw code/text/grep across the workspace.
+- `available_actions(topic="...")` is the meta-tool: if you find
+  yourself guessing, call it. Topics: files, shell, web, memory,
+  harness, models, reasoning, slash, documents, multimodal.
+- `run_shell` mutations are audited and may be blocked. The `requires_change`
+  block tells you which shell commands count as mutations; everything
+  else (read-only) is fine.
+
+## Environment
+
+algo-cli >= 0.4. The tool inventory in `available_actions` is the
+authoritative list; this skill captures the selection heuristics.

algo_cli/retrieval_algorithms.py

@@ -0,0 +1,127 @@
+"""Deterministic bounded ranking primitives used by harness retrieval."""
+
+from __future__ import annotations
+
+import heapq
+import math
+import re
+from collections import Counter
+from collections.abc import Callable, Sequence
+from typing import TypeVar
+
+T = TypeVar("T")
+
+TOKEN_RE = re.compile(r"[\w.-]+", re.UNICODE)
+FULL_SORT_THRESHOLD = 8_192
+MOJIBAKE_REPLACEMENTS = (
+    ("·", "·"),
+    ("…", "…"),
+    ("’", "’"),
+    ("“", "“"),
+    ("”", "”"),
+    ("–", "–"),
+    ("—", "—"),
+)
+
+
+def lexical_tokens(text: str) -> list[str]:
+    """Return normalized lexical tokens shared by BM25 and query parsing."""
+    return [token.lower() for token in TOKEN_RE.findall(text or "") if len(token) > 1]
+
+
+def repair_mojibake(text: str) -> str:
+    """Repair common UTF-8-as-Windows-1252 artifacts at display boundaries."""
+    repaired = str(text or "")
+    for broken, replacement in MOJIBAKE_REPLACEMENTS:
+        repaired = repaired.replace(broken, replacement)
+    return repaired
+
+
+def bm25_scores(
+    documents: Sequence[str],
+    query_terms: Sequence[str],
+    *,
+    k1: float = 1.5,
+    b: float = 0.75,
+) -> list[float]:
+    """Score documents with Okapi BM25 using a query-local in-memory corpus."""
+    return BM25Index(documents, k1=k1, b=b).scores(query_terms)
+
+
+class BM25Index:
+    """Reusable exact BM25 corpus statistics for repeated queries."""
+
+    def __init__(
+        self,
+        documents: Sequence[str],
+        *,
+        k1: float = 1.5,
+        b: float = 0.75,
+    ) -> None:
+        self.k1 = float(k1)
+        self.b = float(b)
+        self._counters = [Counter(lexical_tokens(document)) for document in documents]
+        self._lengths = [sum(counter.values()) for counter in self._counters]
+        self._average_length = sum(self._lengths) / max(1, len(self._lengths))
+        self._document_frequency: Counter[str] = Counter()
+        for counter in self._counters:
+            self._document_frequency.update(counter.keys())
+
+    def scores(self, query_terms: Sequence[str]) -> list[float]:
+        terms = tuple(dict.fromkeys(term.lower() for term in query_terms if term))
+        if not terms:
+            return [0.0] * len(self._counters)
+
+        document_count = len(self._counters)
+        if document_count == 0:
+            return []
+        scores: list[float] = []
+        for counter, length in zip(self._counters, self._lengths):
+            score = 0.0
+            length_normalizer = (
+                1.0 - self.b + self.b * length / max(1.0, self._average_length)
+            )
+            for term in terms:
+                frequency = counter.get(term, 0)
+                if frequency <= 0:
+                    continue
+                df = self._document_frequency.get(term, 0)
+                inverse_document_frequency = math.log(
+                    1.0 + (document_count - df + 0.5) / (df + 0.5)
+                )
+                score += inverse_document_frequency * (
+                    frequency * (self.k1 + 1.0)
+                    / (frequency + self.k1 * length_normalizer)
+                )
+            scores.append(score)
+        return scores
+
+
+def stable_top_k(items: Sequence[T], k: int, score: Callable[[T], float]) -> list[T]:
+    """Return stable top-k with the faster strategy for the candidate scale.
+
+    CPython's C-backed Timsort wins on the harness's bounded (<=4k) pools;
+    heap selection wins once pools are materially larger. Keep the crossover
+    explicit so a theoretically better complexity does not slow the live path.
+    """
+    limit = max(0, int(k))
+    if limit == 0 or not items:
+        return []
+    if len(items) <= FULL_SORT_THRESHOLD:
+        return sorted(items, key=score, reverse=True)[:limit]
+    ranked = heapq.nlargest(
+        min(limit, len(items)),
+        enumerate(items),
+        key=lambda pair: (score(pair[1]), -pair[0]),
+    )
+    return [item for _index, item in ranked]
+
+
+__all__ = [
+    "FULL_SORT_THRESHOLD",
+    "BM25Index",
+    "bm25_scores",
+    "lexical_tokens",
+    "repair_mojibake",
+    "stable_top_k",
+]