packet-tracer-skill 0.2.2 → 0.3.0

package/scripts/twofish_diagnostics.py

@@ -23,9 +23,25 @@ def _vendor_dir() -> Path:
     return Path(__file__).resolve().parent / "vendor"
 
 
+MINIMUM_PYTHON = (3, 10)
+
+
+def _pure_python_status() -> tuple[bool, str]:
+    """Verify the vendored pure-Python engine against the official vectors."""
+    try:
+        sys.path.insert(0, str(_vendor_dir()))
+        from twofish_pure import self_test
+
+        self_test()
+        return True, "vendored pure-Python Twofish (official test vectors pass)"
+    except Exception as exc:  # pragma: no cover - runtime diagnostics
+        return False, f"vendored pure-Python Twofish failed: {exc}"
+
+
 def collect_twofish_diagnostics() -> dict[str, str]:
     python_version = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
-    python_supported = sys.version_info[:2] == SUPPORTED_PYTHON
+    python_supported = sys.version_info[:2] >= MINIMUM_PYTHON
+    compiled_abi_match = sys.version_info[:2] == SUPPORTED_PYTHON
     result = {
         "host_os": normalized_host_os(),
         "python_version": python_version,
@@ -33,49 +49,50 @@ def collect_twofish_diagnostics() -> dict[str, str]:
         "python_support_message": (
             "supported"
             if python_supported
-            else f"requires Python {SUPPORTED_PYTHON[0]}.{SUPPORTED_PYTHON[1]}.x"
+            else f"requires Python {MINIMUM_PYTHON[0]}.{MINIMUM_PYTHON[1]} or newer"
         ),
         "expected_twofish_patterns": expected_bridge_patterns(),
         "twofish_search_roots": recommended_search_roots(_vendor_dir()),
         "resolved_twofish_path": "",
         "twofish_source": "",
+        "twofish_backend": "",
         "twofish_load_status": "missing",
-        "twofish_message": "no local Twofish bridge was found",
+        "twofish_message": "no Twofish engine could be resolved",
         "twofish_sha256": "",
     }
 
-    for source, candidate in candidate_bridge_paths(_vendor_dir(), env_path=os.getenv("PKT_TWOFISH_LIBRARY")):
-        if not candidate.exists():
-            continue
-        result["resolved_twofish_path"] = str(candidate)
-        result["twofish_source"] = source
-        result["twofish_sha256"] = hashlib.sha256(candidate.read_bytes()).hexdigest()
-        if not python_supported:
-            result["twofish_load_status"] = "python_unsupported"
-            result["twofish_message"] = (
-                f"found {candidate}, but this bridge is only supported with Python "
-                f"{SUPPORTED_PYTHON[0]}.{SUPPORTED_PYTHON[1]}.x"
-            )
-            return result
-        try:
-            library = CDLL(str(candidate))
-            getattr(library, "exp_Twofish_encrypt")
-            getattr(library, "exp_Twofish_decrypt")
+    # The compiled bridge is an optional accelerator: preferred when it loads,
+    # but never required, because the vendored pure-Python engine always works.
+    if compiled_abi_match:
+        for source, candidate in candidate_bridge_paths(
+            _vendor_dir(), env_path=os.getenv("PKT_TWOFISH_LIBRARY")
+        ):
+            if not candidate.exists():
+                continue
+            try:
+                library = CDLL(str(candidate))
+                getattr(library, "exp_Twofish_encrypt")
+                getattr(library, "exp_Twofish_decrypt")
+            except Exception:  # pragma: no cover - runtime diagnostics
+                continue
+            result["resolved_twofish_path"] = str(candidate)
+            result["twofish_source"] = source
+            result["twofish_sha256"] = hashlib.sha256(candidate.read_bytes()).hexdigest()
+            result["twofish_backend"] = "compiled"
             result["twofish_load_status"] = "ok"
-            result["twofish_message"] = f"loaded {candidate}"
-            return result
-        except Exception as exc:  # pragma: no cover - runtime diagnostics
-            result["twofish_load_status"] = "load_error"
-            result["twofish_message"] = f"{candidate}: {exc}"
+            result["twofish_message"] = f"loaded compiled accelerator {candidate}"
             return result
 
-    env_path = os.getenv("PKT_TWOFISH_LIBRARY")
-    if env_path:
-        result["resolved_twofish_path"] = str(Path(env_path).expanduser())
-        result["twofish_source"] = "env"
-        result["twofish_load_status"] = "missing"
-        result["twofish_message"] = f"set but missing: {env_path}"
+    pure_ok, pure_message = _pure_python_status()
+    if pure_ok and python_supported:
+        result["twofish_backend"] = "pure_python"
+        result["twofish_source"] = "vendored"
+        result["resolved_twofish_path"] = str(_vendor_dir() / "twofish_pure.py")
+        result["twofish_load_status"] = "ok"
+        result["twofish_message"] = pure_message
+        return result
 
+    result["twofish_message"] = pure_message
     return result
 
 

package/scripts/usage_ledger.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""A local, append-only record of what actually worked, so the skill improves with use.
+
+Donor selection is expensive and mostly repetitive: the same scenario families
+come back, and the same handful of donors keep winning or keep failing for the
+same reasons. Rediscovering that on every run wastes several seconds per
+candidate and, worse, throws away the only real evidence the skill ever gets
+about which donors survive a Packet Tracer open.
+
+The ledger records the outcome of each generation and feeds it back into donor
+ranking on the next run. Nothing is inferred or guessed: an entry is written
+only after a real attempt produced a real result.
+
+Privacy and safety rules, deliberately strict:
+
+- the ledger is local only. It is written under `output/`, which is gitignored,
+  and it is never committed, packaged, or transmitted anywhere.
+- prompts are stored as a normalised fingerprint, not verbatim text, so a lab
+  description containing names or addresses does not end up on disk.
+- the file is bounded. Old entries are dropped once the cap is reached.
+- a corrupt or unreadable ledger is ignored, never fatal. Learning is an
+  optimisation; the skill must work identically with the ledger deleted.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_LEDGER_PATH = SKILL_ROOT / "output" / "usage-ledger.jsonl"
+MAX_ENTRIES = 2000
+LEDGER_VERSION = 1
+
+OUTCOME_GENERATED_VERIFIED = "generated_verified"
+OUTCOME_GENERATED_UNVERIFIED = "generated_unverified"
+OUTCOME_REFUSED = "refused"
+OUTCOMES = (OUTCOME_GENERATED_VERIFIED, OUTCOME_GENERATED_UNVERIFIED, OUTCOME_REFUSED)
+
+# Outcomes that count as evidence a donor works, best first.
+_SUCCESS_WEIGHT = {
+    OUTCOME_GENERATED_VERIFIED: 3,
+    OUTCOME_GENERATED_UNVERIFIED: 1,
+}
+
+
+def ledger_path() -> Path:
+    override = os.getenv("PKT_USAGE_LEDGER")
+    return Path(override).expanduser() if override else DEFAULT_LEDGER_PATH
+
+
+def ledger_enabled() -> bool:
+    """Learning is on by default; `PKT_USAGE_LEDGER=off` disables it entirely."""
+    return (os.getenv("PKT_USAGE_LEDGER") or "").strip().lower() not in {"off", "0", "false", "none"}
+
+
+def prompt_fingerprint(prompt: str) -> str:
+    """A stable, non-reversible fingerprint of a prompt's *shape*.
+
+    Digits are collapsed to `#` and case and spacing are normalised, so
+    "3 switch 6 pc" and "5 switch 2 pc" share a fingerprint: they are the same
+    kind of request, which is exactly the granularity donor reuse needs. The
+    result is hashed so no prompt text is ever written to disk.
+    """
+    normalised = re.sub(r"\d+", "#", (prompt or "").strip().lower())
+    normalised = re.sub(r"[^\w#]+", " ", normalised).strip()
+    return hashlib.sha256(normalised.encode("utf-8")).hexdigest()[:16]
+
+
+@dataclass
+class LedgerEntry:
+    scenario_family: str
+    donor: str
+    outcome: str
+    prompt_shape: str = ""
+    target_version: str = ""
+    donor_version: str = ""
+    rejected_donors: list[str] = field(default_factory=list)
+    rejection_codes: list[str] = field(default_factory=list)
+    recorded_at: str = ""
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "v": LEDGER_VERSION,
+            "recorded_at": self.recorded_at or datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "scenario_family": self.scenario_family,
+            "prompt_shape": self.prompt_shape,
+            "donor": self.donor,
+            "donor_version": self.donor_version,
+            "target_version": self.target_version,
+            "outcome": self.outcome,
+            "rejected_donors": self.rejected_donors[:20],
+            "rejection_codes": self.rejection_codes[:20],
+        }
+
+
+def record(entry: LedgerEntry, path: Path | None = None) -> bool:
+    """Append one outcome. Returns False if the ledger is off or unwritable."""
+    if not ledger_enabled():
+        return False
+    if entry.outcome not in OUTCOMES:
+        raise ValueError(f"unknown outcome: {entry.outcome}")
+
+    target = path or ledger_path()
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(entry.to_json(), ensure_ascii=False) + "\n")
+    except OSError:
+        return False
+
+    _trim(target)
+    return True
+
+
+def _trim(path: Path) -> None:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return
+    if len(lines) <= MAX_ENTRIES:
+        return
+    try:
+        path.write_text("\n".join(lines[-MAX_ENTRIES:]) + "\n", encoding="utf-8")
+    except OSError:
+        return
+
+
+def load_entries(path: Path | None = None) -> list[dict[str, object]]:
+    """Read the ledger. A damaged file yields whatever lines still parse."""
+    target = path or ledger_path()
+    if not ledger_enabled() or not target.exists():
+        return []
+    entries: list[dict[str, object]] = []
+    try:
+        raw_lines = target.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return []
+    for line in raw_lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            parsed = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict) and parsed.get("donor"):
+            entries.append(parsed)
+    return entries
+
+
+def donor_scores(
+    scenario_family: str,
+    prompt_shape: str = "",
+    path: Path | None = None,
+) -> dict[str, int]:
+    """Learned preference per donor, as `relative_path -> score`.
+
+    Positive means the donor has produced output for this kind of request
+    before; negative means it has been rejected. An exact prompt-shape match
+    counts double, because it is stronger evidence than family alone.
+    """
+    scores: dict[str, int] = defaultdict(int)
+    for entry in load_entries(path):
+        if str(entry.get("scenario_family") or "") != scenario_family:
+            continue
+        multiplier = 2 if prompt_shape and entry.get("prompt_shape") == prompt_shape else 1
+
+        donor = str(entry.get("donor") or "")
+        weight = _SUCCESS_WEIGHT.get(str(entry.get("outcome") or ""), 0)
+        if donor and weight:
+            scores[donor] += weight * multiplier
+
+        for rejected in entry.get("rejected_donors") or []:
+            name = str(rejected)
+            if name:
+                scores[name] -= multiplier
+    return dict(scores)
+
+
+def summary(path: Path | None = None) -> dict[str, object]:
+    """Human-facing view of what the skill has learned so far."""
+    entries = load_entries(path)
+    by_outcome: dict[str, int] = defaultdict(int)
+    by_family: dict[str, int] = defaultdict(int)
+    proven: dict[str, int] = defaultdict(int)
+    for entry in entries:
+        outcome = str(entry.get("outcome") or "")
+        by_outcome[outcome] += 1
+        by_family[str(entry.get("scenario_family") or "unknown")] += 1
+        if outcome in _SUCCESS_WEIGHT:
+            proven[str(entry.get("donor") or "")] += _SUCCESS_WEIGHT[outcome]
+    return {
+        "ledger_path": str(path or ledger_path()),
+        "enabled": ledger_enabled(),
+        "entry_count": len(entries),
+        "outcomes": dict(by_outcome),
+        "scenario_families": dict(by_family),
+        "proven_donors": sorted(
+            ({"donor": donor, "score": score} for donor, score in proven.items() if score > 0),
+            key=lambda item: (-int(item["score"]), str(item["donor"])),
+        )[:10],
+    }
+
+
+def main() -> int:
+    print(json.dumps(summary(), ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/vendor/README.md

@@ -1,58 +1,65 @@
-# Twofish Bridge Setup
+# Twofish Engines
 
-This repository does not ship a prebuilt Twofish bridge binary by default.
+The Packet Tracer `.pkt` codec uses Twofish in EAX mode. Two engines live here.
 
-The Packet Tracer `.pkt` codec needs a local Twofish bridge at runtime for
-modern Packet Tracer 9.x encode/decode operations.
+## `twofish_pure.py` — the baseline (always available)
 
-## Supported loading paths
+A vendored pure-Python Twofish. Twofish is unpatented and uncopyrighted by
+design, so it can be implemented and shipped directly.
 
-The wrapper in `twofish.py` loads the bridge from one of these locations:
+- no compiled artifacts, no environment variables, no per-host setup
+- works on any supported Python (3.10+) and any OS
+- verified at import-time diagnostics against the three official test vectors
+  from section B.2 of the Twofish book (128/192/256-bit)
+- bit-identical to the compiled bridge; `tests/test_twofish_pure.py` asserts
+  this whenever both are present
 
-1. `PKT_TWOFISH_LIBRARY`
-2. directories listed in `PKT_TWOFISH_SEARCH_ROOTS`
-3. a sibling file in this folder named like:
-   - `_twofish*.pyd`
-   - `_twofish*.so`
-   - `_twofish*.dylib`
-   - `_twofish*.dll`
+This is what `pkt_codec` uses unless a compiled bridge is found. Nothing has to
+be installed for `decode`, `inventory`, `edit`, or `generate` to work.
+
+Cost: roughly 14 µs per block. A typical 280 KB lab decodes in under a second;
+the largest labs seen so far (~2.8 MB) take about 12 seconds.
+
+## `twofish.py` — the optional accelerator
+
+A ctypes wrapper around a compiled `_twofish` C library. Roughly 12x faster than
+the pure engine, and worth setting up if you routinely process large labs or
+scan the whole sample corpus. It is never required.
 
-## Recommended public-repo workflow
+The wrapper loads the bridge from, in order:
 
-- keep this repository free of prebuilt machine-specific binaries
-- keep the bridge local to your machine
-- preferred: place the bridge next to `scripts/vendor/twofish.py` inside the installed skill folder
-- optional: store the bridge elsewhere and point `PKT_TWOFISH_LIBRARY` at that local file
-- optional: store bridges in one or more local directories and set `PKT_TWOFISH_SEARCH_ROOTS`
+1. `PKT_TWOFISH_LIBRARY`
+2. directories listed in `PKT_TWOFISH_SEARCH_ROOTS`
+3. a sibling file in this folder named like `_twofish*.pyd` / `.so` / `.dylib` / `.dll`
 
 Example on Windows:
 
 ```powershell
-$env:PKT_TWOFISH_LIBRARY="$env:USERPROFILE\.codex\skills\pkt\scripts\vendor\_twofish.cp314-win_amd64.pyd"
+$env:PKT_TWOFISH_LIBRARY="C:\path\to\_twofish.cp314-win_amd64.pyd"
 ```
 
-Example for multiple local search roots:
+The compiled bridge is ABI-locked to one Python version. The current filename
+contract is `_twofish.cp314-win_amd64.pyd` (macOS `_twofish.cp314-macos*.dylib`,
+Linux `_twofish.cp314-linux*.so`). On any other Python version the accelerator is
+skipped and the pure engine is used instead — this is not an error.
 
-```powershell
-$env:PKT_TWOFISH_SEARCH_ROOTS="$env:USERPROFILE\.codex\skills\pkt\scripts\vendor;$env:USERPROFILE\pkt-bridges"
-```
+## Which engine am I using?
 
-## Supported runtime
+```bash
+python scripts/runtime_doctor.py
+```
 
-- supported Python runtime: `3.14.x`
-- current bridge filename: `_twofish.cp314-win_amd64.pyd`
-- recommended non-Windows naming contract:
-  - macOS: `_twofish.cp314-macos*.dylib`
-  - Linux: `_twofish.cp314-linux*.so`
-- other Python ABIs are not considered supported by this public setup
+Read `twofish_backend`: `pure_python` or `compiled`.
 
 ## Security and privacy
 
-- do not commit machine-specific binaries unless you have reviewed them
-- do not commit binaries that embed private paths, usernames, or internal build metadata
-- prefer rebuilding or sourcing the bridge in a reproducible way for your own machine
+- this repository ships no prebuilt machine-specific binaries
+- do not commit binaries that embed private paths, usernames, or build metadata
+- prefer rebuilding the bridge reproducibly for your own machine
 
-## Failure mode
+## Licensing
 
-If the bridge is missing, the wrapper raises an `ImportError` with setup guidance
-instead of silently loading a repo-shipped binary.
+`twofish_pure.py` is original work implemented from the published Twofish
+specification and is covered by this repository's licence. `twofish.py` derives
+from the BSD-3-Clause Python Twofish ctypes bindings; see
+`LICENSES/LICENSE.Twofish-BSD-3-Clause.txt`.