@softspark/ai-toolkit 4.24.0 → 4.25.0

package/scripts/generate_cline_skills.py

@@ -10,17 +10,80 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from skill_pointer import POINTER_SKILL_NAME, write_pointer_skill
+from secure_fs import (
+    SecureDestination,
+    SecureTransaction,
+    lexical_absolute,
+    nearest_existing_root,
+    run_secure_transaction,
+)
+from skill_pointer import POINTER_SKILL_NAME, build_pointer_skill
+
+
+def _is_managed(content: bytes | None) -> bool:
+    if content is None:
+        return False
+    return (
+        f"name: {POINTER_SKILL_NAME}".encode() in content
+        and b"This workspace uses ai-toolkit with Cline." in content
+    )
+
+
+def _destination(target_dir: Path, skill_root: str) -> SecureDestination:
+    target = lexical_absolute(target_dir)
+    if target.is_symlink() or not target.is_dir():
+        raise RuntimeError(f"Unsafe Cline target directory: {target}")
+    path = target / skill_root / POINTER_SKILL_NAME / "SKILL.md"
+    return SecureDestination(path, nearest_existing_root(target), "Cline skill pointer")
 
 
 def generate(target_dir: Path, *, emit_skill_pointer: bool = True,
              skill_root: str = ".cline/skills") -> None:
     if not emit_skill_pointer:
         return
-    write_pointer_skill(target_dir, skill_root, "Cline")
+    destination = _destination(target_dir, skill_root)
+
+    def apply(transaction: SecureTransaction) -> None:
+        current = transaction.initial_content(destination)
+        if current is not None and not _is_managed(current):
+            raise RuntimeError(f"Refusing user-owned Cline skill: {destination.path}")
+        transaction.atomic_write(
+            destination,
+            build_pointer_skill("Cline").encode("utf-8"),
+            0o644,
+        )
+
+    run_secure_transaction([destination], apply)
     print(f"  Generated: {skill_root}/{POINTER_SKILL_NAME}/SKILL.md")
 
 
+def discover(target_dir: Path, *, skill_root: str = ".cline/skills") -> int:
+    """Return one when the managed Cline catalogue pointer is present."""
+    destination = _destination(target_dir, skill_root)
+    transaction = SecureTransaction([destination])
+    try:
+        return int(_is_managed(transaction.initial_content(destination)))
+    finally:
+        transaction.close()
+
+
+def cleanup(target_dir: Path, *, skill_root: str = ".cline/skills") -> int:
+    """Remove only the managed Cline catalogue pointer."""
+    destination = _destination(target_dir, skill_root)
+    transaction = SecureTransaction([destination])
+    try:
+        if not _is_managed(transaction.initial_content(destination)):
+            return 0
+        transaction.materialize_parents()
+        transaction.unlink(destination)
+        return 1
+    except BaseException:
+        transaction.rollback()
+        raise
+    finally:
+        transaction.close()
+
+
 def main() -> None:
     target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
     generate(target)

package/scripts/generate_codex_hooks.py

@@ -61,6 +61,7 @@ SUPPORTED_EVENTS = frozenset(
         "PreCompact",
         "PostCompact",
         "SessionStart",
+        "SessionEnd",
         "UserPromptSubmit",
         "SubagentStart",
         "SubagentStop",
@@ -76,6 +77,7 @@ HANDLER_KEYS = frozenset(
         "commandWindows",
         "timeout",
         "statusMessage",
+        "additionalContextLimit",
         "async",
     }
 )
@@ -113,6 +115,9 @@ CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
     "PreCompact": [
         ("", "codex-pre-compact.sh"),
     ],
+    "SessionEnd": [
+        ("", "session-end.sh"),
+    ],
     "Stop": [
         ("", "quality-check.sh"),
         ("", "save-session.sh"),
@@ -166,6 +171,47 @@ if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/n
 fi
 """
 
+CODEX_SESSION_END_ADAPTER = r"""#!/usr/bin/env bash
+# Native Codex SessionEnd handoff. SessionEnd output is advisory, so stay
+# silent and persist the snapshot without attempting to steer the closed thread.
+# The generated asset always ships these helpers beside this script.
+# shellcheck disable=SC1091,SC2034,SC2153
+# shellcheck source=_session-paths.sh
+source "$(dirname "$0")/_session-paths.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(hook_session_id)
+SESSION_STATE_CLI="${AI_TOOLKIT_SESSION_STATE_CLI:-$HOME/.softspark/ai-toolkit/scripts/session_state.py}"
+if [ "$SESSION_ID" != "default" ] &&
+   [ -f "$SESSION_STATE_CLI" ] &&
+   [ ! -L "$SESSION_STATE_CLI" ] &&
+   command -v python3 >/dev/null 2>&1; then
+    python3 -S "$SESSION_STATE_CLI" clean \
+        --session-id "$SESSION_ID" >/dev/null 2>&1 || true
+fi
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+STAMP="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date)"
+mkdir -p "$SESSION_DIR"
+{
+    echo "# Session End Snapshot"
+    echo ""
+    echo "- ended_at: $STAMP"
+    if [ -f "$SESSION_CONTEXT_FILE" ]; then
+        echo "- session_context: present"
+    else
+        echo "- session_context: missing"
+    fi
+    echo "- next_start: re-read AGENTS.md, open tasks, and validation state"
+} > "$SESSION_END_FILE"
+
+exit 0
+"""
+
 CODEX_MCP_HEALTH_ADAPTER = r"""#!/usr/bin/env bash
 # Check documented Codex MCP config layers without starting any MCP server.
 cat >/dev/null || true
@@ -210,6 +256,7 @@ PY
 GENERATED_ADAPTERS = {
     "codex-stop-search-check.sh": CODEX_STOP_SEARCH_ADAPTER,
     "codex-session-start.sh": CODEX_SESSION_START_ADAPTER,
+    "session-end.sh": CODEX_SESSION_END_ADAPTER,
     "codex-pre-compact.sh": CODEX_PRE_COMPACT_ADAPTER,
     "codex-mcp-health.sh": CODEX_MCP_HEALTH_ADAPTER,
 }
@@ -248,13 +295,14 @@ def build_hooks_json(*, global_install: bool = False) -> dict[str, Any]:
     for event, entries in CODEX_HOOKS.items():
         groups: list[dict[str, Any]] = []
         for matcher, script in entries:
+            handler: dict[str, Any] = {
+                "type": "command",
+                "command": _command_for(script, global_install),
+            }
+            if event == "SessionEnd":
+                handler["timeout"] = 3
             group: dict[str, Any] = {
-                "hooks": [
-                    {
-                        "type": "command",
-                        "command": _command_for(script, global_install),
-                    }
-                ]
+                "hooks": [handler]
             }
             if matcher:
                 group["matcher"] = matcher
@@ -266,8 +314,12 @@ def build_hooks_json(*, global_install: bool = False) -> dict[str, Any]:
 
 
 def _validate_hooks_document(data: Any) -> None:
-    if not isinstance(data, dict) or set(data) - {"hooks"}:
-        raise ValueError("Codex hooks.json must contain only the top-level hooks key")
+    if not isinstance(data, dict) or set(data) - {"description", "hooks"}:
+        raise ValueError(
+            "Codex hooks.json supports only description and hooks at the top level"
+        )
+    if "description" in data and not isinstance(data["description"], str):
+        raise ValueError("Codex hooks.json description must be a string")
     hooks = data.get("hooks", {})
     if not isinstance(hooks, dict):
         raise ValueError("Codex hooks.json hooks must be an object")
@@ -320,6 +372,14 @@ def _validate_handler(event: str, handler: Any) -> None:
         timeout = handler["timeout"]
         if type(timeout) is not int or timeout <= 0:
             raise ValueError(f"Codex {event} timeout must be a positive integer")
+        if event == "SessionEnd" and timeout > 3:
+            raise ValueError("Codex SessionEnd timeout cannot exceed 3 seconds")
+    if "additionalContextLimit" in handler:
+        context_limit = handler["additionalContextLimit"]
+        if type(context_limit) is not int or context_limit < 0:
+            raise ValueError(
+                f"Codex {event} additionalContextLimit must be a non-negative integer"
+            )
     for key in ("commandWindows", "statusMessage"):
         if key in handler and not isinstance(handler[key], str):
             raise ValueError(f"Codex {event} {key} must be a string")
@@ -414,6 +474,8 @@ def _is_managed_handler(handler: dict[str, Any]) -> bool:
 
 def _merge_hooks(existing: dict[str, Any], generated: dict[str, Any]) -> dict[str, Any]:
     merged: dict[str, Any] = {"hooks": {}}
+    if "description" in existing:
+        merged["description"] = existing["description"]
     for event, groups in existing.get("hooks", {}).items():
         retained_groups: list[dict[str, Any]] = []
         for group in groups:

package/scripts/generate_gemini_agents.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
+
+"""Generate native Gemini CLI subagents under ``.gemini/agents``."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from emission import agents_dir
+from frontmatter import frontmatter_field
+from secure_fs import (
+    SecureDestination,
+    SecureTransaction,
+    lexical_absolute,
+    nearest_existing_root,
+    run_secure_transaction,
+)
+
+
+AGENT_PREFIX = "ai-toolkit-"
+MANAGED_MARKER = "<!-- ai-toolkit-managed: gemini-agent -->"
+SAFE_NAME = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+
+
+def _body(source: Path) -> str:
+    text = source.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        return text.strip()
+    parts = text.split("---", 2)
+    return (parts[2] if len(parts) == 3 else text).strip()
+
+
+def _quote(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def render_agent(source: Path) -> tuple[str, str]:
+    """Return a Gemini agent name and its native Markdown definition."""
+    if source.is_symlink() or not source.is_file():
+        raise RuntimeError(f"Unsafe Gemini agent source: {source}")
+    name = frontmatter_field(source, "name")
+    description = frontmatter_field(source, "description")
+    if not SAFE_NAME.fullmatch(name):
+        raise ValueError(f"Invalid Gemini agent name in {source}: {name!r}")
+    if not description:
+        raise ValueError(f"Missing Gemini agent description in {source}")
+    lines = [
+        "---",
+        f"name: {name}",
+        f"description: {_quote(description)}",
+        "kind: local",
+        "---",
+        "",
+        MANAGED_MARKER,
+        "",
+        _body(source),
+        "",
+    ]
+    return name, "\n".join(lines)
+
+
+def _is_managed(content: bytes | None) -> bool:
+    return content is not None and MANAGED_MARKER.encode() in content[:2048]
+
+
+def _stale_files(output_dir: Path, expected: set[str]) -> list[Path]:
+    if not output_dir.exists():
+        return []
+    if output_dir.is_symlink() or not output_dir.is_dir():
+        raise RuntimeError(f"Unsafe Gemini agents directory: {output_dir}")
+    stale: list[Path] = []
+    for candidate in sorted(output_dir.glob(f"{AGENT_PREFIX}*.md")):
+        if (
+            candidate.name in expected
+            or candidate.is_symlink()
+            or not candidate.is_file()
+        ):
+            continue
+        try:
+            content = candidate.read_bytes()
+        except OSError:
+            continue
+        if _is_managed(content):
+            stale.append(candidate)
+    return stale
+
+
+def _source_plan(source_root: Path) -> list[tuple[str, str]]:
+    plan: list[tuple[str, str]] = []
+    seen: set[str] = set()
+    for source in sorted(source_root.glob("*.md")):
+        name, rendered = render_agent(source)
+        if name in seen:
+            raise ValueError(f"Duplicate Gemini agent name: {name}")
+        seen.add(name)
+        plan.append((name, rendered))
+    return plan
+
+
+def generate(
+    target_dir: Path,
+    *,
+    source_dir: Path | None = None,
+) -> tuple[int, int]:
+    """Write all native Gemini agents and return ``(written, removed)``."""
+    source_root = lexical_absolute(source_dir or agents_dir)
+    if source_root.is_symlink() or not source_root.is_dir():
+        raise RuntimeError(f"Unsafe Gemini agents source directory: {source_root}")
+    plan = _source_plan(source_root)
+    target_dir = lexical_absolute(target_dir)
+    if target_dir.is_symlink() or not target_dir.is_dir():
+        raise RuntimeError(f"Unsafe Gemini target directory: {target_dir}")
+    gemini_dir = target_dir / ".gemini"
+    output_dir = gemini_dir / "agents"
+    if gemini_dir.is_symlink() or output_dir.is_symlink():
+        raise RuntimeError(f"Unsafe Gemini agents path: {output_dir}")
+    expected = {f"{AGENT_PREFIX}{name}.md" for name, _ in plan}
+    stale = _stale_files(output_dir, expected)
+    trusted_root = nearest_existing_root(target_dir)
+    writes = [
+        (
+            SecureDestination(
+                output_dir / f"{AGENT_PREFIX}{name}.md",
+                trusted_root,
+                f"Gemini agent {name}",
+            ),
+            rendered.encode(),
+        )
+        for name, rendered in plan
+    ]
+    stale_destinations = [
+        SecureDestination(path, trusted_root, f"stale Gemini agent {path.name}")
+        for path in stale
+    ]
+
+    def apply(transaction: SecureTransaction) -> tuple[int, int]:
+        written = 0
+        removed = 0
+        for destination, content in writes:
+            existing = transaction.initial_content(destination)
+            if existing is not None and not _is_managed(existing):
+                continue
+            transaction.atomic_write(destination, content, 0o644)
+            written += 1
+        for destination in stale_destinations:
+            if _is_managed(transaction.initial_content(destination)):
+                transaction.unlink(destination)
+                removed += 1
+        return written, removed
+
+    return run_secure_transaction(
+        [destination for destination, _ in writes] + stale_destinations,
+        apply,
+    )
+
+
+def cleanup(target_dir: Path) -> int:
+    """Remove only managed Gemini agent files from ``target_dir``."""
+    target = lexical_absolute(target_dir)
+    if target.is_symlink() or not target.is_dir():
+        raise RuntimeError(f"Unsafe Gemini target directory: {target}")
+    output_dir = target / ".gemini" / "agents"
+    stale = _stale_files(output_dir, set())
+    if not stale:
+        return 0
+    trusted_root = nearest_existing_root(target)
+    destinations = [
+        SecureDestination(path, trusted_root, f"Gemini agent {path.name}")
+        for path in stale
+    ]
+
+    def apply(transaction: SecureTransaction) -> int:
+        removed = 0
+        for destination in destinations:
+            if _is_managed(transaction.initial_content(destination)):
+                transaction.unlink(destination)
+                removed += 1
+        return removed
+
+    return run_secure_transaction(destinations, apply)
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    written, removed = generate(target)
+    print(f"Generated: .gemini/agents/ ({written} agents, {removed} stale removed)")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_gemini_hooks.py

@@ -14,10 +14,10 @@ Gemini CLI hook events (per docs/hooks/reference.md, google-gemini/gemini-cli):
     BeforeToolSelection, AfterModel, SessionStart, SessionEnd,
     Notification, PreCompress
 
-The ai-toolkit registry nominally includes `Stop`, but the upstream Gemini CLI
-does not implement it; `AfterAgent` is the closest equivalent (fires once per
-turn after the model's final response) and we wire our `save-session.sh` /
-`quality-check.sh` there.
+Claude Code's source lifecycle includes `Stop`, but Gemini CLI does not
+implement it. `AfterAgent` is the closest equivalent (fires once per turn
+after the model's final response), so we wire our `save-session.sh` and
+`quality-check.sh` there without advertising a non-existent Gemini event.
 
 Hook scripts are shared with Claude Code / Codex and live under
 `~/.softspark/ai-toolkit/hooks/`. This generator does NOT duplicate shell code.
@@ -37,6 +37,19 @@ from pathlib import Path
 
 HOOKS_PREFIX = 'AI_TOOLKIT_HOOK_FORMAT=json "$HOME/.softspark/ai-toolkit/hooks/'
 SOURCE_TAG = "ai-toolkit"
+GEMINI_SUPPORTED_HOOK_EVENTS = (
+    "BeforeTool",
+    "AfterTool",
+    "BeforeToolSelection",
+    "BeforeAgent",
+    "AfterAgent",
+    "BeforeModel",
+    "AfterModel",
+    "Notification",
+    "PreCompress",
+    "SessionStart",
+    "SessionEnd",
+)
 
 # Event -> list of (matcher, script) pairs. Matcher semantics:
 #   - Tool events (BeforeTool/AfterTool): regex over tool_name
@@ -77,6 +90,13 @@ GEMINI_HOOKS: dict[str, list[tuple[str, str]]] = {
     ],
 }
 
+_unsupported_events = set(GEMINI_HOOKS) - set(GEMINI_SUPPORTED_HOOK_EVENTS)
+if _unsupported_events:
+    raise RuntimeError(
+        "Unsupported Gemini hook event mapping(s): "
+        + ", ".join(sorted(_unsupported_events))
+    )
+
 
 def build_hook_entry(matcher: str, script: str) -> dict:
     """Build a single Gemini hook entry (merge-safe shape)."""