@softspark/ai-toolkit 4.15.1 → 4.16.0

package/scripts/schemas/ai-toolkit-config.schema.json

@@ -39,6 +39,66 @@
       "default": "standard",
       "description": "Installation profile controlling which modules are installed."
     },
+    "toolOutputFilter": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Native post-execution Bash output filtering. Disabled by default.",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["off", "observe", "safe"],
+          "default": "off"
+        },
+        "profiles": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["repeat-lines", "tap-success"]
+          },
+          "uniqueItems": true,
+          "default": ["repeat-lines", "tap-success"]
+        },
+        "maxInputBytes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8388608,
+          "default": 8388608
+        },
+        "minSavingsBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 8388608,
+          "default": 1024
+        },
+        "minSavingsRatio": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.15
+        },
+        "recovery": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["ephemeral"],
+              "default": "ephemeral"
+            },
+            "ttlMinutes": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 60
+            },
+            "maxSessionBytes": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 33554432
+            }
+          }
+        }
+      }
+    },
     "agents": {
       "type": "object",
       "additionalProperties": false,
@@ -61,6 +121,23 @@
         }
       }
     },
+    "plugins": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Resolved plugin enable/disable intent. Runtime installation remains explicit.",
+      "properties": {
+        "enabled": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "disabled": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        }
+      }
+    },
     "rules": {
       "type": "object",
       "additionalProperties": false,
@@ -81,7 +158,7 @@
     "constitution": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Constitution amendments. Articles I-VI are immutable. Base articles are immutable. Projects can only ADD new articles (7+).",
+      "description": "Constitution amendments. Articles I-VII are immutable. Base articles are immutable. Projects can only ADD new articles (8+).",
       "properties": {
         "amendments": {
           "type": "array",
@@ -92,8 +169,8 @@
             "properties": {
               "article": {
                 "type": "integer",
-                "minimum": 1,
-                "description": "Article number. 1-5 are reserved (immutable). Base articles are also immutable."
+                "minimum": 8,
+                "description": "Article number. 1-7 are reserved (immutable). Base articles are also immutable."
               },
               "title": {
                 "type": "string",
@@ -120,8 +197,9 @@
         },
         "requiredPlugins": {
           "type": "array",
-          "items": { "type": "string" },
-          "description": "Plugins that must be installed in all inheriting projects."
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true,
+          "description": "Plugins that must appear in resolved enabled intent. Runtime installation remains explicit."
         },
         "forbidOverride": {
           "type": "array",

package/scripts/session_state.py

@@ -5,14 +5,16 @@ Stores per-session file edits so hooks can:
 - Know which paths were touched (revert-guard, test-cohesion).
 - Run only related tests (quality-gate ai-toolkit branch).
 
-State file: ``~/.softspark/ai-toolkit/state/session-edits.json``
+State files: ``~/.softspark/ai-toolkit/state/session-edits-<hash>.json``.
+The legacy ``session-edits.json`` alias tracks the most recently active session.
 
 Usage:
     session_state.py reset [--session-id ID]
     session_state.py append --tool Edit --path /abs/path [--session-id ID]
-    session_state.py was-edited /abs/path
-    session_state.py list
-    session_state.py session-id
+    session_state.py was-edited /abs/path [--session-id ID]
+    session_state.py list [--session-id ID]
+    session_state.py session-id [--session-id ID]
+    session_state.py clean --session-id ID
 
 Exit codes:
     0  success / true
@@ -23,9 +25,12 @@ from __future__ import annotations
 
 import argparse
 import datetime as _dt
+import hashlib
 import json
 import os
+import stat
 import sys
+import tempfile
 import uuid
 from pathlib import Path
 
@@ -42,77 +47,176 @@ def _ensure_dir() -> None:
     STATE_DIR.mkdir(parents=True, exist_ok=True)
 
 
-def _load() -> dict:
-    if not STATE_FILE.is_file():
-        return {"session_id": "", "started_at": "", "edits": []}
+def _state_file(session_id: str | None) -> Path:
+    if not session_id:
+        return STATE_FILE
+    digest = hashlib.sha256(session_id.encode("utf-8")).hexdigest()
+    return STATE_DIR / f"session-edits-{digest}.json"
+
+
+def _empty_state(session_id: str = "") -> dict:
+    return {"session_id": session_id, "started_at": "", "edits": []}
+
+
+def _validated_state(data: object, session_id: str | None) -> dict:
+    fallback = _empty_state(session_id or "")
+    if not isinstance(data, dict):
+        return fallback
+    stored_session = data.get("session_id", session_id or "")
+    started_at = data.get("started_at", "")
+    edits = data.get("edits", [])
+    if not isinstance(stored_session, str) or not isinstance(started_at, str):
+        return fallback
+    if not isinstance(edits, list) or any(
+        not isinstance(edit, dict)
+        or not isinstance(edit.get("path", ""), str)
+        for edit in edits
+    ):
+        return fallback
+    return {
+        "session_id": stored_session,
+        "started_at": started_at,
+        "edits": edits,
+    }
+
+
+def _load(session_id: str | None = None) -> dict:
+    state_file = _state_file(session_id)
+    if not state_file.is_file():
+        return _empty_state(session_id or "")
     try:
-        with STATE_FILE.open() as f:
+        with state_file.open(encoding="utf-8") as f:
             data = json.load(f)
-    except (json.JSONDecodeError, OSError):
-        return {"session_id": "", "started_at": "", "edits": []}
-    data.setdefault("session_id", "")
-    data.setdefault("started_at", "")
-    data.setdefault("edits", [])
-    return data
+    except (json.JSONDecodeError, OSError, UnicodeError):
+        return _empty_state(session_id or "")
+    return _validated_state(data, session_id)
 
 
-def _save(data: dict) -> None:
+def _atomic_save(state_file: Path, data: dict) -> None:
     _ensure_dir()
-    tmp = STATE_FILE.with_suffix(".json.tmp")
-    with tmp.open("w") as f:
-        json.dump(data, f, indent=2)
-        f.write("\n")
-    os.replace(tmp, STATE_FILE)
+    temp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            dir=STATE_DIR,
+            prefix=f".{state_file.name}.",
+            encoding="utf-8",
+            delete=False,
+        ) as temp_file:
+            json.dump(data, temp_file, indent=2)
+            temp_file.write("\n")
+            temp_path = Path(temp_file.name)
+        os.replace(temp_path, state_file)
+        temp_path = None
+    finally:
+        if temp_path is not None:
+            temp_path.unlink(missing_ok=True)
+
+
+def _save(data: dict, session_id: str | None = None) -> None:
+    _atomic_save(_state_file(session_id), data)
+    if session_id:
+        # Preserve no-ID CLI behavior without making it the source of truth.
+        _atomic_save(STATE_FILE, data)
 
 
 def cmd_reset(session_id: str | None) -> int:
     sid = session_id or str(uuid.uuid4())
-    _save({"session_id": sid, "started_at": _now(), "edits": []})
+    _save({"session_id": sid, "started_at": _now(), "edits": []}, session_id)
     return 0
 
 
 def cmd_append(tool: str, path: str, session_id: str | None) -> int:
     if not path:
         return 0  # silently ignore tools without file_path (e.g., bash)
-    data = _load()
+    data = _load(session_id)
     if session_id and data["session_id"] != session_id:
-        # New session detected mid-stream — auto-reset.
-        cmd_reset(session_id)
-        data = _load()
+        data = _empty_state(session_id)
+    if not data["started_at"]:
+        data["started_at"] = _now()
     abs_path = os.path.abspath(path)
     data["edits"].append({"ts": _now(), "tool": tool, "path": abs_path})
     if len(data["edits"]) > MAX_EDITS:
         data["edits"] = data["edits"][-MAX_EDITS:]
-    _save(data)
+    _save(data, session_id)
     return 0
 
 
-def cmd_was_edited(path: str) -> int:
+def cmd_was_edited(path: str, session_id: str | None) -> int:
     abs_path = os.path.abspath(path)
-    data = _load()
+    data = _load(session_id)
     for edit in data["edits"]:
         if edit.get("path") == abs_path:
             return 0
     return 1
 
 
-def cmd_list() -> int:
-    data = _load()
+def cmd_list(session_id: str | None) -> int:
+    data = _load(session_id)
     seen: set[str] = set()
     for edit in data["edits"]:
-        p = edit.get("path", "")
-        if p and p not in seen:
-            seen.add(p)
-            print(p)
+        path = edit.get("path", "")
+        if path and path not in seen:
+            seen.add(path)
+            print(path)
     return 0
 
 
-def cmd_session_id() -> int:
-    data = _load()
+def cmd_session_id(session_id: str | None) -> int:
+    data = _load(session_id)
     print(data.get("session_id", ""))
     return 0
 
 
+def cmd_clean(session_id: str) -> int:
+    """Remove the selected hashed state and its matching legacy alias."""
+    state_file = _state_file(session_id)
+    try:
+        metadata = state_file.lstat()
+    except FileNotFoundError:
+        _clean_matching_legacy_alias(session_id)
+        return 0
+    if not stat.S_ISREG(metadata.st_mode):
+        return 2
+    try:
+        state_file.unlink()
+    except FileNotFoundError:
+        pass
+    _clean_matching_legacy_alias(session_id)
+    return 0
+
+
+def _clean_matching_legacy_alias(session_id: str) -> None:
+    """Remove the compatibility alias only when it names this session."""
+    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(
+        os,
+        "O_NOFOLLOW",
+        0,
+    )
+    try:
+        descriptor = os.open(STATE_FILE, flags)
+    except OSError:
+        return
+    opened_metadata = os.fstat(descriptor)
+    try:
+        with os.fdopen(descriptor, encoding="utf-8") as state_handle:
+            data = json.load(state_handle)
+    except (json.JSONDecodeError, OSError, UnicodeError):
+        return
+    if isinstance(data, dict) and data.get("session_id") == session_id:
+        try:
+            current_metadata = STATE_FILE.lstat()
+            if (
+                not stat.S_ISREG(current_metadata.st_mode)
+                or current_metadata.st_dev != opened_metadata.st_dev
+                or current_metadata.st_ino != opened_metadata.st_ino
+            ):
+                return
+            STATE_FILE.unlink()
+        except FileNotFoundError:
+            pass
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description="Session edit state tracker")
     sub = parser.add_subparsers(dest="cmd", required=True)
@@ -127,9 +231,17 @@ def main(argv: list[str] | None = None) -> int:
 
     was = sub.add_parser("was-edited", help="Exit 0 if path was edited this session")
     was.add_argument("path")
-
-    sub.add_parser("list", help="Print unique edited paths, one per line")
-    sub.add_parser("session-id", help="Print current session id")
+    was.add_argument("--session-id", default=None)
+
+    list_parser = sub.add_parser("list", help="Print unique edited paths, one per line")
+    list_parser.add_argument("--session-id", default=None)
+    session_parser = sub.add_parser("session-id", help="Print current session id")
+    session_parser.add_argument("--session-id", default=None)
+    clean_parser = sub.add_parser(
+        "clean",
+        help="Remove one session-scoped edit state file",
+    )
+    clean_parser.add_argument("--session-id", required=True)
 
     args = parser.parse_args(argv)
 
@@ -138,11 +250,13 @@ def main(argv: list[str] | None = None) -> int:
     if args.cmd == "append":
         return cmd_append(args.tool, args.path, args.session_id)
     if args.cmd == "was-edited":
-        return cmd_was_edited(args.path)
+        return cmd_was_edited(args.path, args.session_id)
     if args.cmd == "list":
-        return cmd_list()
+        return cmd_list(args.session_id)
     if args.cmd == "session-id":
-        return cmd_session_id()
+        return cmd_session_id(args.session_id)
+    if args.cmd == "clean":
+        return cmd_clean(args.session_id)
     return 2
 
 

package/scripts/tool_output_filter/__init__.py

@@ -0,0 +1,33 @@
+"""Dependency-free post-execution tool-output filtering."""
+
+from .contracts import FilterMode, FilterRequest, FilterResult
+from .engine import filter_output
+from .invariants import SessionCircuitBreaker
+from .recovery import (
+    EphemeralRecoveryStore,
+    RecoveryStore,
+    RecoveryUnavailableError,
+    clean_owned_recovery_tree,
+    clean_owned_repo_recovery,
+    clean_session,
+    count_owned_recovery_artifacts,
+    recover_by_handle,
+)
+from .telemetry import TelemetrySink
+
+__all__ = [
+    "EphemeralRecoveryStore",
+    "FilterMode",
+    "FilterRequest",
+    "FilterResult",
+    "RecoveryStore",
+    "RecoveryUnavailableError",
+    "SessionCircuitBreaker",
+    "TelemetrySink",
+    "clean_owned_recovery_tree",
+    "clean_owned_repo_recovery",
+    "clean_session",
+    "count_owned_recovery_artifacts",
+    "filter_output",
+    "recover_by_handle",
+]

package/scripts/tool_output_filter/contracts.py

@@ -0,0 +1,173 @@
+"""Public data contracts for the tool-output filter."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+DEFAULT_MAX_INPUT_BYTES = 8 * 1024 * 1024
+DEFAULT_MIN_SAVINGS_BYTES = 1024
+DEFAULT_MIN_SAVINGS_RATIO = 0.15
+
+
+class _ImmutableSlots:
+    """Allow one assignment per declared slot."""
+
+    __slots__ = ()
+
+    def __setattr__(self, name: str, value: object) -> None:
+        if hasattr(self, name):
+            raise AttributeError(f"{type(self).__name__} is immutable")
+        object.__setattr__(self, name, value)
+
+
+class FilterMode(str, Enum):
+    """Supported activation modes."""
+
+    OFF = "off"
+    OBSERVE = "observe"
+    SAFE = "safe"
+
+
+class FilterRequest(_ImmutableSlots):
+    """Normalized successful textual tool output."""
+
+    __slots__ = (
+        "interrupted",
+        "is_image",
+        "is_streaming",
+        "max_input_bytes",
+        "min_savings_bytes",
+        "min_savings_ratio",
+        "mode",
+        "output",
+        "profile_id",
+        "raw_response",
+        "stderr",
+        "successful",
+    )
+
+    def __init__(
+        self,
+        output: str,
+        mode: FilterMode,
+        profile_id: str,
+        raw_response: object | None = None,
+        successful: bool = True,
+        stderr: str = "",
+        interrupted: bool = False,
+        is_image: bool = False,
+        is_streaming: bool = False,
+        max_input_bytes: int = DEFAULT_MAX_INPUT_BYTES,
+        min_savings_bytes: int = DEFAULT_MIN_SAVINGS_BYTES,
+        min_savings_ratio: float = DEFAULT_MIN_SAVINGS_RATIO,
+    ) -> None:
+        self.output = output
+        self.mode = mode
+        self.profile_id = profile_id
+        self.raw_response = raw_response
+        self.successful = successful
+        self.stderr = stderr
+        self.interrupted = interrupted
+        self.is_image = is_image
+        self.is_streaming = is_streaming
+        self.max_input_bytes = max_input_bytes
+        self.min_savings_bytes = min_savings_bytes
+        self.min_savings_ratio = min_savings_ratio
+
+
+class FilterTelemetry(_ImmutableSlots):
+    """Content-free measurements for one filter decision."""
+
+    __slots__ = (
+        "duration_ms",
+        "fallback_reason",
+        "input_bytes",
+        "input_lines",
+        "outcome",
+        "output_bytes",
+        "output_lines",
+        "profile_id",
+        "profile_version",
+    )
+
+    def __init__(
+        self,
+        profile_id: str,
+        profile_version: int,
+        input_bytes: int,
+        output_bytes: int,
+        input_lines: int,
+        output_lines: int,
+        duration_ms: float = 0.0,
+        outcome: str = "",
+        fallback_reason: str | None = None,
+    ) -> None:
+        self.profile_id = profile_id
+        self.profile_version = profile_version
+        self.input_bytes = input_bytes
+        self.output_bytes = output_bytes
+        self.input_lines = input_lines
+        self.output_lines = output_lines
+        self.duration_ms = duration_ms
+        self.outcome = outcome
+        self.fallback_reason = fallback_reason
+
+    def with_runtime(
+        self,
+        *,
+        duration_ms: float,
+        outcome: str,
+        fallback_reason: str | None,
+    ) -> FilterTelemetry:
+        return FilterTelemetry(
+            self.profile_id,
+            self.profile_version,
+            self.input_bytes,
+            self.output_bytes,
+            self.input_lines,
+            self.output_lines,
+            duration_ms,
+            outcome,
+            fallback_reason,
+        )
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            slot: getattr(self, slot)
+            for slot in self.__slots__
+        }
+
+
+class FilterResult(_ImmutableSlots):
+    """Observable result returned by the filtering engine."""
+
+    __slots__ = (
+        "changed",
+        "fallback_reason",
+        "outcome",
+        "output",
+        "telemetry",
+    )
+
+    def __init__(
+        self,
+        output: str,
+        changed: bool,
+        outcome: str,
+        telemetry: FilterTelemetry | None = None,
+        fallback_reason: str | None = None,
+    ) -> None:
+        self.output = output
+        self.changed = changed
+        self.outcome = outcome
+        self.telemetry = telemetry
+        self.fallback_reason = fallback_reason
+
+    def with_telemetry(self, telemetry: FilterTelemetry) -> FilterResult:
+        return FilterResult(
+            self.output,
+            self.changed,
+            self.outcome,
+            telemetry,
+            self.fallback_reason,
+        )