@softspark/ai-toolkit 4.16.1 → 4.17.0

package/scripts/tool_output_filter/engine.py

@@ -1,260 +0,0 @@
-"""Pure orchestration for post-execution output filtering."""
-
-from __future__ import annotations
-
-import re
-import time
-from collections.abc import Callable
-
-from .contracts import FilterMode, FilterRequest, FilterResult, FilterTelemetry
-from .invariants import SessionCircuitBreaker
-from .profiles import ProfileTransform, apply_profile
-from .recovery import RecoveryStore
-from .telemetry import TelemetrySink
-
-_UNSAFE_CONTROL_PATTERN = re.compile(
-    r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f\u2028\u2029]|\r(?!\n)"
-)
-
-
-def _meets_savings_gate(
-    raw_output: str,
-    candidate: str,
-    request: FilterRequest,
-) -> bool:
-    input_bytes = len(raw_output.encode("utf-8"))
-    output_bytes = len(candidate.encode("utf-8"))
-    bytes_saved = input_bytes - output_bytes
-    savings_ratio = bytes_saved / input_bytes if input_bytes else 0.0
-    return (
-        bytes_saved >= request.min_savings_bytes
-        and savings_ratio >= request.min_savings_ratio
-    )
-
-
-def _telemetry(
-    request: FilterRequest,
-    output: str,
-    profile_id: str,
-    profile_version: int,
-) -> FilterTelemetry:
-    return FilterTelemetry(
-        profile_id=profile_id,
-        profile_version=profile_version,
-        input_bytes=len(request.output.encode("utf-8")),
-        output_bytes=len(output.encode("utf-8")),
-        input_lines=len(request.output.splitlines()),
-        output_lines=len(output.splitlines()),
-    )
-
-
-def _with_recovery_marker(
-    candidate: str,
-    request: FilterRequest,
-    handle: str,
-    profile_id: str,
-    profile_version: int,
-) -> str:
-    separator = "" if candidate.endswith("\n") else "\n"
-    emitted_lines = len(candidate.splitlines()) + 1
-    return (
-        f"{candidate}{separator}"
-        f"[ai-toolkit-output-filter {profile_id}/v{profile_version}; "
-        f"original_lines={len(request.output.splitlines())}; "
-        f"emitted_lines={emitted_lines}; recovery={handle}]\n"
-    )
-
-
-def _discard_recovery(recovery: RecoveryStore, handle: str) -> None:
-    try:
-        recovery.delete(handle)
-    except Exception:
-        pass
-
-
-def _passthrough(
-    request: FilterRequest,
-    reason: str,
-    telemetry: FilterTelemetry | None = None,
-) -> FilterResult:
-    return FilterResult(
-        output=request.output,
-        changed=False,
-        outcome="passthrough",
-        telemetry=telemetry,
-        fallback_reason=reason,
-    )
-
-
-def _eligibility_failure(request: FilterRequest) -> str | None:
-    if not request.successful:
-        return "execution-failed"
-    if request.stderr:
-        return "stderr-present"
-    if request.interrupted:
-        return "execution-interrupted"
-    if request.is_image:
-        return "unsupported-media"
-    if request.is_streaming:
-        return "unsupported-stream"
-    if _UNSAFE_CONTROL_PATTERN.search(request.output) is not None:
-        return "unsupported-control-sequence"
-    try:
-        input_bytes = len(request.output.encode("utf-8"))
-    except UnicodeEncodeError:
-        return "invalid-text"
-    if input_bytes > request.max_input_bytes:
-        return "input-too-large"
-    return None
-
-
-def _apply_profile_safely(
-    request: FilterRequest,
-) -> tuple[ProfileTransform | None, str | None]:
-    try:
-        profile = apply_profile(request.profile_id, request.output)
-    except Exception:
-        return None, "profile-failed"
-    if profile is None:
-        return None, "unknown-profile"
-    if not profile.accepted:
-        return None, "profile-rejected"
-    return profile, None
-
-
-def _save_verified_recovery(
-    response: object,
-    recovery: RecoveryStore,
-) -> tuple[str | None, str | None]:
-    handle: str | None = None
-    try:
-        handle = recovery.save(response)
-        recovered = recovery.load(handle)
-    except Exception:
-        if handle is not None:
-            _discard_recovery(recovery, handle)
-        return None, "recovery-failed"
-    if recovered != response:
-        _discard_recovery(recovery, handle)
-        return None, "recovery-verification-failed"
-    return handle, None
-
-
-def _safe_result(
-    request: FilterRequest,
-    profile: ProfileTransform,
-    telemetry: FilterTelemetry,
-    recovery: RecoveryStore | None,
-) -> FilterResult:
-    if request.raw_response is None:
-        return _passthrough(request, "raw-response-unavailable", telemetry)
-    if recovery is None:
-        return _passthrough(request, "recovery-unavailable", telemetry)
-    handle, failure = _save_verified_recovery(
-        request.raw_response,
-        recovery,
-    )
-    if failure is not None or handle is None:
-        return _passthrough(request, failure or "recovery-failed", telemetry)
-    replacement = _with_recovery_marker(
-        profile.output,
-        request,
-        handle,
-        request.profile_id,
-        profile.profile_version,
-    )
-    if not _meets_savings_gate(request.output, replacement, request):
-        _discard_recovery(recovery, handle)
-        return _passthrough(request, "never-worse", telemetry)
-    return FilterResult(
-        output=replacement,
-        changed=True,
-        outcome="replaced",
-        telemetry=_telemetry(
-            request,
-            replacement,
-            request.profile_id,
-            profile.profile_version,
-        ),
-    )
-
-
-def _filter_output(
-    request: FilterRequest,
-    *,
-    recovery: RecoveryStore | None = None,
-) -> FilterResult:
-    """Return an exact passthrough unless every safety gate succeeds."""
-
-    if request.mode is FilterMode.OFF:
-        return FilterResult(request.output, False, "disabled")
-    eligibility_failure = _eligibility_failure(request)
-    if eligibility_failure is not None:
-        return _passthrough(request, eligibility_failure)
-    profile, profile_failure = _apply_profile_safely(request)
-    if profile_failure is not None or profile is None:
-        return _passthrough(
-            request,
-            profile_failure or "profile-failed",
-        )
-    if not _meets_savings_gate(request.output, profile.output, request):
-        return _passthrough(request, "insufficient-savings")
-    candidate_telemetry = _telemetry(
-        request,
-        profile.output,
-        request.profile_id,
-        profile.profile_version,
-    )
-    if request.mode is FilterMode.OBSERVE:
-        return FilterResult(
-            request.output,
-            False,
-            "observed",
-            candidate_telemetry,
-        )
-    return _safe_result(
-        request,
-        profile,
-        candidate_telemetry,
-        recovery,
-    )
-
-
-def filter_output(
-    request: FilterRequest,
-    *,
-    recovery: RecoveryStore | None = None,
-    telemetry: TelemetrySink | None = None,
-    circuit_breaker: SessionCircuitBreaker | None = None,
-    clock_ns: Callable[[], int] = time.perf_counter_ns,
-) -> FilterResult:
-    """Apply one profile without mutating execution state or raw input."""
-
-    if circuit_breaker is not None and circuit_breaker.is_open:
-        return FilterResult(
-            output=request.output,
-            changed=False,
-            outcome="passthrough",
-            fallback_reason="circuit-open",
-        )
-
-    started_ns = clock_ns()
-    result = _filter_output(request, recovery=recovery)
-    finished_ns = clock_ns()
-    if circuit_breaker is not None:
-        circuit_breaker.record(result.fallback_reason)
-    if result.telemetry is None:
-        return result
-
-    event = result.telemetry.with_runtime(
-        duration_ms=max(0, finished_ns - started_ns) / 1_000_000,
-        outcome=result.outcome,
-        fallback_reason=result.fallback_reason,
-    )
-    result = result.with_telemetry(event)
-    if telemetry is not None:
-        try:
-            telemetry.record(event)
-        except Exception:
-            pass
-    return result

package/scripts/tool_output_filter/hook_runtime.py

@@ -1,369 +0,0 @@
-"""Lean Claude PostToolUse runtime for native tool-output filtering."""
-
-from __future__ import annotations
-
-import json
-import os
-import re
-import shlex
-import sys
-
-from .contracts import FilterMode, FilterRequest
-from .engine import filter_output
-from .input import JSON_ENVELOPE_ALLOWANCE_BYTES, load_bounded_json
-from .invariants import SessionCircuitBreaker
-from .policy import OutputFilterPolicy, load_policy
-from .recovery import EphemeralRecoveryStore
-
-_UNSAFE_SHELL_FRAGMENTS = ("|", ">", "<", ";", "&&", "||", "`", "$(", "\n")
-# Claude Code's Bash tool_response has no guaranteed exit-status field; when a
-# runtime does provide one, a non-zero value must veto filtering outright.
-_EXIT_STATUS_KEYS = ("exitCode", "exit_code", "returncode")
-_FAILURE_LINE_PREFIXES = (
-    "not ok",
-    "npm err!",
-    "fail",
-    "--- fail",
-    "error",
-    "fatal",
-    "panic",
-    "traceback",
-    "critical",
-    "segmentation fault",
-    "assert",
-    "exception",
-    "✕",
-    "✗",
-    "e   ",
-)
-_FAILURE_SUMMARY_PATTERN = re.compile(
-    r"\b[1-9][0-9]* (?:failed|failures|errors)\b"
-)
-_DANGEROUS_FRAGMENTS = (
-    "audit",
-    "deploy",
-    "destroy",
-    "migrat",
-    "publish",
-    "release",
-    "semgrep",
-    "snyk",
-    "terraform",
-    "trivy",
-)
-_SAFE_TASK_TOKENS = frozenset(
-    {
-        "analyze",
-        "analysis",
-        "check",
-        "checks",
-        "clippy",
-        "lint",
-        "qa",
-        "test",
-        "tests",
-        "typecheck",
-        "validate",
-        "validation",
-        "vet",
-    }
-)
-_TASK_TOKEN_SEPARATORS = "-_:./"
-_SAFE_SESSION_ID_CHARACTERS = frozenset(
-    "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-"
-)
-_MAX_SESSION_ID_LENGTH = 160
-
-
-def _is_safe_task(value: str) -> bool:
-    normalized = value.lower()
-    for separator in _TASK_TOKEN_SEPARATORS:
-        normalized = normalized.replace(separator, " ")
-    return any(token in _SAFE_TASK_TOKENS for token in normalized.split())
-
-
-def _matches_supported_shape(arguments: list[str]) -> bool:
-    executable = os.path.basename(arguments[0]).lower()
-    remaining = arguments[1:]
-    if executable in {"bats", "jest", "pytest", "vitest"}:
-        return True
-    if executable in {"python", "python3"}:
-        return len(remaining) >= 2 and remaining[:2] in (
-            ["-m", "pytest"],
-            ["-m", "unittest"],
-        )
-    if executable in {"cargo", "dart", "flutter", "go"}:
-        return bool(remaining) and _is_safe_task(remaining[0])
-    if executable == "npm":
-        if not remaining:
-            return False
-        if remaining[0] == "test":
-            return True
-        return len(remaining) >= 2 and remaining[0] == "run" and _is_safe_task(
-            remaining[1]
-        )
-    if executable == "npx":
-        return bool(remaining) and os.path.basename(remaining[0]).lower() in {
-            "eslint",
-            "jest",
-            "tsc",
-            "vitest",
-        }
-    if executable == "make":
-        return bool(remaining) and all(_is_safe_task(target) for target in remaining)
-    if executable == "composer":
-        if len(remaining) == 1:
-            return _is_safe_task(remaining[0])
-        return (
-            len(remaining) == 2
-            and remaining[0] in {"run", "run-script"}
-            and _is_safe_task(remaining[1])
-        )
-    return False
-
-
-def _is_supported_command(command: str) -> bool:
-    if any(fragment in command for fragment in _UNSAFE_SHELL_FRAGMENTS):
-        return False
-    try:
-        arguments = shlex.split(command, posix=True)
-    except ValueError:
-        return False
-    if not arguments:
-        return False
-    lowered_arguments = [argument.lower() for argument in arguments]
-    if any(
-        fragment in argument
-        for argument in lowered_arguments
-        for fragment in _DANGEROUS_FRAGMENTS
-    ):
-        return False
-    return _matches_supported_shape(arguments)
-
-
-def _reports_failed_execution(response: dict[str, object]) -> bool:
-    for key in _EXIT_STATUS_KEYS:
-        value = response.get(key)
-        if value is None:
-            continue
-        if isinstance(value, bool) or not isinstance(value, int) or value != 0:
-            return True
-    return False
-
-
-def _looks_like_failure_output(stdout: str) -> bool:
-    for line in stdout.splitlines():
-        content = line.lstrip().lower()
-        if not content:
-            continue
-        if content.startswith(_FAILURE_LINE_PREFIXES):
-            return True
-        if _FAILURE_SUMMARY_PATTERN.search(content) is not None:
-            return True
-    return False
-
-
-def _infer_repo_root(start: str) -> str | None:
-    # realpath keeps the repo key aligned with the bash hooks, which resolve
-    # symlinks via `git rev-parse --show-toplevel`.
-    candidate_path = os.path.realpath(os.path.expanduser(start))
-    if not os.path.isdir(candidate_path):
-        return None
-    candidate = candidate_path
-    while True:
-        git_marker = os.path.join(candidate, ".git")
-        if os.path.isdir(git_marker) or os.path.isfile(git_marker):
-            return candidate
-        parent = os.path.dirname(candidate)
-        if parent == candidate:
-            break
-        candidate = parent
-    return candidate_path
-
-
-def _session_base_for_repo(repo_root: str) -> str:
-    repo_key = "-" + str(repo_root).replace("/", "-").lstrip("-")
-    return os.path.join(
-        os.path.expanduser("~"),
-        ".softspark",
-        "ai-toolkit",
-        "sessions",
-        repo_key,
-    )
-
-
-def _normalize_payload(payload: object) -> tuple[dict[str, object], str] | None:
-    if not isinstance(payload, dict):
-        return None
-    if payload.get("hook_event_name") != "PostToolUse":
-        return None
-    if payload.get("tool_name") != "Bash":
-        return None
-    response = payload.get("tool_response")
-    tool_input = payload.get("tool_input")
-    if not isinstance(response, dict) or not isinstance(tool_input, dict):
-        return None
-    stdout = response.get("stdout")
-    command = tool_input.get("command")
-    if not isinstance(stdout, str) or not isinstance(command, str):
-        return None
-    if response.get("stderr") != "" or response.get("interrupted") is not False:
-        return None
-    if response.get("isImage") is not False:
-        return None
-    if _reports_failed_execution(response):
-        return None
-    if _looks_like_failure_output(stdout):
-        return None
-    if not _is_supported_command(command):
-        return None
-    return response, stdout
-
-
-def _repo_session_root(payload: dict[str, object]) -> tuple[str, str] | None:
-    cwd = payload.get("cwd")
-    session_identifier = payload.get("session_id")
-    if not isinstance(cwd, str) or not isinstance(session_identifier, str):
-        return None
-    if not cwd or not session_identifier:
-        return None
-    if (
-        len(session_identifier) > _MAX_SESSION_ID_LENGTH
-        or any(
-            character not in _SAFE_SESSION_ID_CHARACTERS
-            for character in session_identifier
-        )
-    ):
-        return None
-    repo_root = _infer_repo_root(cwd)
-    if repo_root is None:
-        return None
-    return _session_base_for_repo(repo_root), session_identifier
-
-
-def _request(
-    policy: OutputFilterPolicy,
-    response: dict[str, object],
-    stdout: str,
-    profile_id: str,
-) -> FilterRequest:
-    return FilterRequest(
-        output=stdout,
-        raw_response=response,
-        mode=policy.mode,
-        profile_id=profile_id,
-        max_input_bytes=policy.max_input_bytes,
-        min_savings_bytes=policy.min_savings_bytes,
-        min_savings_ratio=policy.min_savings_ratio,
-    )
-
-
-def _emit_replacement(
-    response: dict[str, object],
-    replacement: str,
-) -> None:
-    updated_response = dict(response)
-    updated_response["stdout"] = replacement
-    output = {
-        "hookSpecificOutput": {
-            "hookEventName": "PostToolUse",
-            "updatedToolOutput": updated_response,
-        }
-    }
-    sys.stdout.write(json.dumps(output, ensure_ascii=False, separators=(",", ":")))
-    sys.stdout.write("\n")
-
-
-def _emit_system_message(message: str) -> None:
-    sys.stdout.write(
-        json.dumps(
-            {"systemMessage": message},
-            ensure_ascii=False,
-            separators=(",", ":"),
-        )
-    )
-    sys.stdout.write("\n")
-
-
-def _filter_profiles(
-    policy: OutputFilterPolicy,
-    response: dict[str, object],
-    stdout: str,
-    recovery: EphemeralRecoveryStore,
-    circuit_breaker: SessionCircuitBreaker,
-) -> None:
-    for profile_id in policy.profiles:
-        result = filter_output(
-            _request(policy, response, stdout, profile_id),
-            recovery=recovery,
-            telemetry=recovery,
-            circuit_breaker=circuit_breaker,
-        )
-        recovery.save_failure_count(
-            min(
-                circuit_breaker.consecutive_failures,
-                circuit_breaker.failure_limit,
-            )
-        )
-        if result.changed:
-            _emit_replacement(response, result.output)
-            return
-        if result.outcome == "observed":
-            return
-
-
-def run_hook(policy_path: str | os.PathLike[str]) -> int:
-    """Run one bounded, fail-open Claude PostToolUse decision."""
-
-    if os.environ.get("AI_TOOLKIT_OUTPUT_FILTER_DISABLE") == "1":
-        return 0
-    try:
-        policy = load_policy(policy_path)
-    except (OSError, TypeError, ValueError, KeyError):
-        return 0
-    if policy.mode is FilterMode.OFF:
-        return 0
-    payload_limit = policy.max_input_bytes + JSON_ENVELOPE_ALLOWANCE_BYTES
-    try:
-        payload = load_bounded_json(sys.stdin.buffer, max_bytes=payload_limit)
-    except (json.JSONDecodeError, TypeError, UnicodeDecodeError, ValueError):
-        return 0
-    if not isinstance(payload, dict):
-        return 0
-    normalized = _normalize_payload(payload)
-    if normalized is None:
-        return 0
-    response, stdout = normalized
-    recovery_location = _repo_session_root(payload)
-    if recovery_location is None:
-        return 0
-    base_directory, session_identifier = recovery_location
-    try:
-        with EphemeralRecoveryStore(
-            base_directory,
-            session_identifier=session_identifier,
-            max_session_bytes=policy.max_session_bytes,
-            ttl_minutes=policy.ttl_minutes,
-        ) as recovery:
-            circuit_breaker = SessionCircuitBreaker(
-                consecutive_failures=recovery.load_failure_count()
-            )
-            if circuit_breaker.is_open and not recovery.load_warning_emitted():
-                _emit_system_message(
-                    "ai-toolkit: output filtering disabled for this session "
-                    "after 3 safety failures"
-                )
-                recovery.mark_warning_emitted()
-            _filter_profiles(
-                policy,
-                response,
-                stdout,
-                recovery,
-                circuit_breaker,
-            )
-    except (OSError, RuntimeError, TypeError, ValueError):
-        return 0
-    return 0
-
-
-__all__ = ["run_hook"]

package/scripts/tool_output_filter/input.py

@@ -1,56 +0,0 @@
-"""Bounded input helpers for fail-open runtime adapters."""
-
-from __future__ import annotations
-
-import json
-from collections.abc import Callable
-
-JSON_ENVELOPE_ALLOWANCE_BYTES = 64 * 1024
-
-
-def read_bounded_text(
-    stream: object,
-    *,
-    max_bytes: int,
-) -> str | None:
-    """Read UTF-8 text without retaining data beyond the byte limit."""
-
-    if max_bytes < 0:
-        raise ValueError("maximum input bytes must be non-negative")
-    read = getattr(stream, "read", None)
-    if not callable(read):
-        raise TypeError("bounded text input must be readable")
-    chunks: list[bytes] = []
-    received = 0
-    while received <= max_bytes:
-        chunk = read(max_bytes + 1 - received)
-        if not isinstance(chunk, bytes):
-            raise TypeError("bounded text input must be binary")
-        if not chunk:
-            break
-        chunks.append(chunk)
-        received += len(chunk)
-    if received > max_bytes:
-        return None
-    return b"".join(chunks).decode("utf-8")
-
-
-def load_bounded_json(
-    stream: object,
-    *,
-    max_bytes: int,
-    decoder: Callable[[str], object] = json.loads,
-) -> object | None:
-    """Decode one JSON value only when its encoded form fits the hard cap."""
-
-    text = read_bounded_text(stream, max_bytes=max_bytes)
-    if text is None:
-        return None
-    return decoder(text)
-
-
-__all__ = [
-    "JSON_ENVELOPE_ALLOWANCE_BYTES",
-    "load_bounded_json",
-    "read_bounded_text",
-]