fix: wire plugin lifecycle hooks across surfaces

Fixes #18

Author: EvanProgramming

Makefile

@@ -45,7 +45,7 @@ clean:
 
 # Syntax check
 lint:
-	$(VENV_PYTHON) -m compileall -q main.py server.py tools.py memory.py event_store.py task_engine.py learning_engine.py learning_benchmark.py migration.py scheduler.py skill_registry.py browser_manager.py instruction_loader.py subagents.py capability_tokens.py tool_registry.py dynamic_tools.py
+	$(VENV_PYTHON) -m compileall -q main.py server.py tools.py memory.py event_store.py task_engine.py learning_engine.py learning_benchmark.py migration.py scheduler.py skill_registry.py browser_manager.py instruction_loader.py subagents.py capability_tokens.py tool_registry.py dynamic_tools.py plugin_runtime.py
 	@echo "Python syntax OK."
 	@echo "All files pass syntax check."
 
@@ -56,7 +56,7 @@ test:
 # Quick verification
 check:
 	@echo "Checking Python syntax..."
-	@$(VENV_PYTHON) -m py_compile main.py server.py tools.py memory.py event_store.py task_engine.py learning_engine.py learning_benchmark.py migration.py scheduler.py skill_registry.py browser_manager.py instruction_loader.py subagents.py capability_tokens.py tool_registry.py dynamic_tools.py
+	@$(VENV_PYTHON) -m py_compile main.py server.py tools.py memory.py event_store.py task_engine.py learning_engine.py learning_benchmark.py migration.py scheduler.py skill_registry.py browser_manager.py instruction_loader.py subagents.py capability_tokens.py tool_registry.py dynamic_tools.py plugin_runtime.py
 	@echo "  Python modules: OK"
 	@echo "Checking git tools..."
 	@$(VENV_PYTHON) -c "from tools import AVAILABLE_TOOLS; git = [k for k in AVAILABLE_TOOLS if k.startswith('git_')]; print(f'  {len(git)} git tools, {len(AVAILABLE_TOOLS)} total tools')"

README.md

@@ -551,6 +551,23 @@ def register():
 
 Available hooks: `on_startup`, `on_turn_start`, `on_turn_end`, `on_tool_execute`.
 
+The shared runtime loads `plugins/*.py` once per execution surface (`cli` and
+`web`) in deterministic filename order. Hook failures are isolated, recorded
+as `plugin.hook_failed` events, and never fail the user turn. Hook arguments
+are keyword arguments and are bounded/redacted before a plugin sees them:
+
+| Hook | Required kwargs | Additional context |
+|------|-----------------|--------------------|
+| `on_startup` | — | `agent`, `surface`, `user_id`, `workspace_id` |
+| `on_turn_start` | `user_input` | `surface`, `user_id`, `workspace_id`, `session_id`, `profile` |
+| `on_turn_end` | `reply`, `success` | `error` plus the turn context |
+| `on_tool_execute` | `action`, `args`, `result`, `success` | `error`, `surface`, and scope context |
+
+`on_tool_execute` fires once for every attempted action, including unknown,
+unauthorized, malformed, and approval-denied actions. `turn_logger.py` writes
+to `kyrozen_turns.log`; set `KYROZEN_TURN_LOG` to choose another path for a
+service or test.
+
 See `plugins/turn_logger.py` for a working example.
 
 ---

main.py

@@ -102,6 +102,7 @@ def _terminal_supports_unicode() -> bool:
 from subagents import AgentProfile, SubAgentManager
 from capability_tokens import issue_capability_token
 from dynamic_tools import SAFE_BUILTINS, validate_tool_source
+from plugin_runtime import get_plugin_runtime
 from tools import (AVAILABLE_TOOLS, set_workspace_root as _set_tools_workspace_root,
                    resolve_capabilities, tool_capability)
 from providers import (
@@ -1875,6 +1876,23 @@ def _system_prompt(tools_list: str) -> str:
 _learning_notices: list[str] = []
 
 
+def _record_plugin_event(event_type: str, payload: dict[str, Any]) -> None:
+    """Persist plugin runtime diagnostics without allowing them to break work."""
+    try:
+        memory_bank.store.append_event(
+            event_type, payload, user_id=memory_bank.user_id,
+            workspace_id=memory_bank.workspace_id, session_id=memory_bank.session_id,
+        )
+    except Exception:
+        pass
+
+
+def _plugin_runtime_for_surface(surface: str | None = None):
+    return get_plugin_runtime(
+        surface or _EXECUTION_SURFACE, event_recorder=_record_plugin_event,
+    )
+
+
 def _subagent_action_arguments(action: str, args: Any) -> Any:
     """Normalise common structured action arguments without widening access."""
     if not isinstance(args, dict):
@@ -1914,12 +1932,17 @@ def _run_subagent_tool(profile: AgentProfile, action: str, args: Any, tools: set
     canonical = TOOL_ALIASES.get(str(action).strip(), str(action).strip())
     receipt_id = f"subagent_receipt_{uuid.uuid4().hex}"
     if canonical not in tools:
+        _notify_tool_execute(
+            canonical, args,
+            f"Error: tool '{canonical}' is not authorized for the '{profile.name}' profile.",
+        )
         return {
             "receipt_id": receipt_id, "action": canonical, "args": str(args)[:500],
             "result": f"Error: tool '{canonical}' is not authorized for the '{profile.name}' profile.",
             "success": False, "authorized": False,
         }
     if not isinstance(args, (str, dict)):
+        _notify_tool_execute(canonical, args, "Error: Action args must be a plain string or supported object.")
         return {
             "receipt_id": receipt_id, "action": canonical, "args": str(args)[:500],
             "result": "Error: Action args must be a plain string or supported object.",
@@ -1978,6 +2001,10 @@ def _run_subagent_llm(profile: AgentProfile, task: str, context: list[dict[str,
             if unknown or malformed:
                 executed_steps += 1
                 rejected_action = unknown or "malformed"
+                _notify_tool_execute(
+                    str(rejected_action), "",
+                    "Error: malformed or unknown Action rejected; no tool was executed.",
+                )
                 tool_records.append({
                     "receipt_id": f"subagent_receipt_{uuid.uuid4().hex}",
                     "action": str(rejected_action), "args": "",
@@ -2561,6 +2588,22 @@ def _add(data: dict) -> None:
     return calls
 
 
+def _notify_tool_execute(action: str, args: Any, result: Any) -> None:
+    """Emit exactly one isolated plugin hook for every attempted tool call."""
+    result_text = str(result)
+    try:
+        _plugin_runtime_for_surface().tool_execute(
+            action=action, args=args, result=result_text,
+            success=not _is_tool_error(result_text),
+            error=None if not _is_tool_error(result_text) else result_text,
+            user_id=memory_bank.user_id, workspace_id=memory_bank.workspace_id,
+            session_id=memory_bank.session_id,
+        )
+    except Exception:
+        # A plugin is an observer and cannot change tool semantics.
+        pass
+
+
 def _run_tool(action: str, args: str) -> str:
     # Map aliases
     action = TOOL_ALIASES.get(action, action)
@@ -2593,15 +2636,21 @@ def _run_tool(action: str, args: str) -> str:
             pass
     fn = AVAILABLE_TOOLS.get(action)
     if not fn:
-        return f"Error: unknown tool '{action}'"
+        result = f"Error: unknown tool '{action}'"
+        _notify_tool_execute(action, args, result)
+        return result
     required_capability = tool_capability(action)
     if not _execution_capability_token.allows(required_capability):
-        return f"Error: tool '{action}' requires capability '{required_capability}'"
+        result = f"Error: tool '{action}' requires capability '{required_capability}'"
+        _notify_tool_execute(action, args, result)
+        return result
     if not _confirm_tool_action(action, str(args)):
-        return (
+        result = (
             f"Error: {action} requires confirmation. "
             "Approve it interactively or set KYROZEN_APPROVAL_MODE=never for an explicitly automated CLI."
         )
+        _notify_tool_execute(action, args, result)
+        return result
     start = time.time()
     try:
         result = str(fn(args))
@@ -2611,6 +2660,7 @@ def _run_tool(action: str, args: str) -> str:
         result = f"Error: {e}"
     elapsed = time.time() - start
     _track_tool_performance(action, result, elapsed)
+    _notify_tool_execute(action, args, result)
     return result
 
 
@@ -3115,8 +3165,8 @@ def _classify_complexity(user_input: str) -> str:
     return "medium"
 
 
-def _chat_turn(user_input: str, clear_tasks: bool = False, profile: str | None = None,
-               memory_context: dict[str, Any] | None = None) -> str:
+def _chat_turn_impl(user_input: str, clear_tasks: bool = False, profile: str | None = None,
+                    memory_context: dict[str, Any] | None = None) -> str:
     """One user turn: build context, get LLM reply, execute tool calls
     with automatic retries and failure memory."""
 
@@ -3189,6 +3239,9 @@ def _chat_turn(user_input: str, clear_tasks: bool = False, profile: str | None =
         if not unknown_action:
             break
         _unknown_retries += 1
+        _notify_tool_execute(
+            unknown_action, "", f"Error: unknown tool '{unknown_action}'",
+        )
         msg = (
             f"System: Action '{unknown_action}' is not recognized. "
             "You must use one of the following actions: "
@@ -3315,6 +3368,7 @@ def _chat_turn(user_input: str, clear_tasks: bool = False, profile: str | None =
                 "Example: `\"args\": \"python3 process_logs.py\"`\n"
                 "Do NOT use `\"args\": {\"cmd\": ...}`.\n"
             )
+            _notify_tool_execute(action, args, result)
         else:
             if not isinstance(args, str):
                 args = str(args)
@@ -3581,6 +3635,7 @@ def _chat_turn(user_input: str, clear_tasks: bool = False, profile: str | None =
                     "Example: `\"args\": \"python3 process_logs.py\"`\n"
                     "Do NOT use `\"args\": {\"cmd\": ...}`.\n"
                 )
+                _notify_tool_execute(action, args, result2)
             else:
                 if not isinstance(args, str):
                     args = str(args)
@@ -3697,6 +3752,30 @@ def _chat_turn(user_input: str, clear_tasks: bool = False, profile: str | None =
     )
 
 
+def _chat_turn(user_input: str, clear_tasks: bool = False, profile: str | None = None,
+               memory_context: dict[str, Any] | None = None) -> str:
+    """Run one chat turn with failure-isolated plugin lifecycle hooks."""
+    runtime = _plugin_runtime_for_surface()
+    context = {
+        "user_id": memory_bank.user_id,
+        "workspace_id": memory_bank.workspace_id,
+        "session_id": memory_bank.session_id,
+        "profile": profile or _agent_profile_mode,
+    }
+    runtime.turn_start(user_input=user_input, **context)
+    try:
+        reply = _chat_turn_impl(
+            user_input, clear_tasks=clear_tasks, profile=profile,
+            memory_context=memory_context,
+        )
+    except Exception as exc:
+        runtime.turn_end(reply="", success=False,
+                         error=f"{type(exc).__name__}: {exc}", **context)
+        raise
+    runtime.turn_end(reply=reply, success=True, **context)
+    return reply
+
+
 def _split_reply(text: str) -> tuple[str, str]:
     text = text.strip()
     thought_match = re.search(r"^Thought:\s*(.*?)(?=\n(?:Action:|(?:\n|$)))", text, re.DOTALL | re.MULTILINE)
@@ -3965,6 +4044,7 @@ def main() -> None:
         sys.exit(1)
     # Set workspace root for sandbox
     _set_workspace_root(os.getcwd())
+    _plugin_runtime_for_surface().load_once()
     task_results = _run_recovered_tasks()
     for item in task_results:
         console.print(f"[{_SUCCESS}]Durable task {item['task']['id']}: {item['status']}[/{_SUCCESS}]")

plugin_runtime.py

@@ -0,0 +1,139 @@
+"""Shared, failure-isolated plugin lifecycle runtime."""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+import threading
+from pathlib import Path
+from typing import Any, Callable
+
+
+_RUNTIMES: dict[str, "PluginRuntime"] = {}
+_RUNTIMES_LOCK = threading.RLock()
+
+_SECRET_PATTERNS = (
+    re.compile(r"(?i)((?:api[_-]?key|password|secret|token)\s*[:=])\s*\S+"),
+    re.compile(r"\bsk-[A-Za-z0-9_-]+"),
+)
+
+
+def _redact(value: Any, limit: int = 500) -> str:
+    text = str(value or "")
+    for pattern in _SECRET_PATTERNS:
+        text = pattern.sub(lambda match: (match.group(1) + "<redacted>")
+                           if match.lastindex else "<redacted>", text)
+    return text.replace("\n", " ")[:limit]
+
+
+class PluginRuntime:
+    """Load plugins once for one execution surface and isolate every hook."""
+
+    def __init__(self, surface: str, *, plugins_dir: Path | None = None,
+                 event_recorder: Callable[[str, dict[str, Any]], None] | None = None):
+        self.surface = str(surface or "unknown")
+        self.plugins_dir = (plugins_dir or Path(__file__).parent / "plugins").resolve()
+        self.event_recorder = event_recorder
+        self._loaded = False
+        self._plugins: list[tuple[str, Any]] = []
+        self._lock = threading.RLock()
+
+    @property
+    def loaded(self) -> bool:
+        return self._loaded
+
+    @property
+    def plugin_names(self) -> tuple[str, ...]:
+        return tuple(name for name, _plugin in self._plugins)
+
+    def _record(self, event_type: str, **payload: Any) -> None:
+        if not self.event_recorder:
+            return
+        safe_payload = {key: _redact(value, 300) if isinstance(value, str) else value
+                        for key, value in payload.items()}
+        try:
+            self.event_recorder(event_type, safe_payload)
+        except Exception:
+            pass
+
+    def load_once(self) -> tuple[str, ...]:
+        with self._lock:
+            if self._loaded:
+                return self.plugin_names
+            # Set the flag before importing anything: a broken plugin must not
+            # cause another request to retry imports or duplicate registrations.
+            self._loaded = True
+            if not self.plugins_dir.is_dir():
+                self._record("plugin.loaded", plugin="<none>", status="no plugin directory")
+                return self.plugin_names
+            for path in sorted(self.plugins_dir.glob("*.py")):
+                if path.name.startswith("_"):
+                    continue
+                module_name = f"openkyrozen_plugin_{self.surface}_{path.stem}"
+                try:
+                    spec = importlib.util.spec_from_file_location(module_name, path)
+                    if spec is None or spec.loader is None:
+                        raise ImportError("could not create module spec")
+                    module = importlib.util.module_from_spec(spec)
+                    spec.loader.exec_module(module)
+                    register = getattr(module, "register", None)
+                    if not callable(register):
+                        self._record("plugin.load_failed", plugin=path.stem,
+                                     error="register() is missing")
+                        continue
+                    plugin = register()
+                    if plugin is None:
+                        self._record("plugin.load_failed", plugin=path.stem,
+                                     error="register() returned no plugin")
+                        continue
+                    self._plugins.append((path.stem, plugin))
+                    self._record("plugin.loaded", plugin=path.stem, status="loaded")
+                except Exception as exc:
+                    self._record("plugin.load_failed", plugin=path.stem,
+                                 error=f"{type(exc).__name__}: {exc}")
+            return self.plugin_names
+
+    def trigger(self, hook_name: str, **kwargs: Any) -> None:
+        self.load_once()
+        for plugin_name, plugin in tuple(self._plugins):
+            hook = getattr(plugin, hook_name, None)
+            if not callable(hook):
+                continue
+            try:
+                hook(**kwargs)
+            except Exception as exc:
+                self._record(
+                    "plugin.hook_failed", plugin=plugin_name, hook=hook_name,
+                    error=f"{type(exc).__name__}: {exc}",
+                )
+
+    def turn_start(self, *, user_input: str, **context: Any) -> None:
+        self.trigger("on_turn_start", user_input=_redact(user_input, 1000),
+                     surface=self.surface, **context)
+
+    def turn_end(self, *, reply: str, success: bool, error: str | None = None,
+                 **context: Any) -> None:
+        self.trigger("on_turn_end", reply=_redact(reply, 1000), success=bool(success),
+                     error=_redact(error, 300) if error else None,
+                     surface=self.surface, **context)
+
+    def tool_execute(self, *, action: str, args: Any, result: Any, success: bool,
+                     error: str | None = None, **context: Any) -> None:
+        self.trigger(
+            "on_tool_execute", action=_redact(action, 100), args=_redact(args, 500),
+            result=_redact(result, 1000), success=bool(success),
+            error=_redact(error, 300) if error else None,
+            surface=self.surface, **context,
+        )
+
+
+def get_plugin_runtime(surface: str, *, plugins_dir: Path | None = None,
+                       event_recorder: Callable[[str, dict[str, Any]], None] | None = None) -> PluginRuntime:
+    """Return the one runtime instance for a surface in this process."""
+    key = str(surface or "unknown")
+    with _RUNTIMES_LOCK:
+        runtime = _RUNTIMES.get(key)
+        if runtime is None:
+            runtime = PluginRuntime(key, plugins_dir=plugins_dir, event_recorder=event_recorder)
+            _RUNTIMES[key] = runtime
+        return runtime

plugins/turn_logger.py

@@ -4,13 +4,14 @@
 """
 
 import time
+import os
 from pathlib import Path
 
 class TurnLogger:
     """Logs every conversation turn with timestamp."""
 
     def __init__(self):
-        self._log_path = Path("kyrozen_turns.log")
+        self._log_path = Path(os.environ.get("KYROZEN_TURN_LOG", "kyrozen_turns.log"))
 
     def on_turn_start(self, user_input: str, **kwargs):
         ts = time.strftime("%Y-%m-%d %H:%M:%S")

pyproject.toml

@@ -48,7 +48,7 @@ Repository = "https://github.com/EvanProgramming/OpenKyrozen"
 Issues = "https://github.com/EvanProgramming/OpenKyrozen/issues"
 
 [tool.setuptools]
-py-modules = ["main", "memory", "providers", "server", "tools", "event_store", "learning_engine", "learning_benchmark", "migration", "task_engine", "scheduler", "skill_registry", "browser_manager", "instruction_loader", "subagents", "capability_tokens", "tool_registry", "dynamic_tools"]
+py-modules = ["main", "memory", "providers", "server", "tools", "event_store", "learning_engine", "learning_benchmark", "migration", "task_engine", "scheduler", "skill_registry", "browser_manager", "instruction_loader", "subagents", "capability_tokens", "tool_registry", "dynamic_tools", "plugin_runtime"]
 include-package-data = true
 
 [tool.setuptools.packages.find]