@kontourai/flow-agents 0.1.1 → 0.2.0

package/integrations/strands/flow_agents_strands/hooks.py

@@ -0,0 +1,194 @@
+"""
+hooks.py — FlowAgentsHooks: the main HookProvider for AWS Strands Agents.
+
+Design: duck-typed so strands-agents is NOT required at import time.
+The class uses TYPE_CHECKING guards and string-based isinstance() avoidance so
+the full module tree is importable and unit-testable without the SDK installed.
+
+When strands-agents IS installed, FlowAgentsHooks is a valid HookProvider
+because it implements the register_hooks(registry, **kwargs) protocol method.
+
+Usage (with strands installed):
+
+    from strands import Agent
+    from flow_agents_strands import FlowAgentsHooks
+
+    hooks = FlowAgentsHooks(workspace=".")
+    system_prompt = "You are a helpful agent." + hooks.steering_context()
+    agent = Agent(system_prompt=system_prompt, hooks=[hooks])
+
+Usage (without strands, e.g. in tests):
+
+    from flow_agents_strands import FlowAgentsHooks
+    hooks = FlowAgentsHooks()
+    ctx = hooks.steering_context()   # works without strands
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, Optional, TYPE_CHECKING
+
+from .telemetry import TelemetrySink, STRANDS_TO_CANONICAL
+from .policy import PolicyGate
+from .steering import SteeringContext
+
+if TYPE_CHECKING:
+    # These imports only run during static type-checking (mypy/pyright).
+    # At runtime the try/except below handles the optional SDK.
+    from strands.hooks import (  # type: ignore[import]
+        HookRegistry,
+        BeforeInvocationEvent,
+        AfterInvocationEvent,
+        BeforeToolCallEvent,
+        AfterToolCallEvent,
+    )
+
+
+class FlowAgentsHooks:
+    """
+    Flow Agents HookProvider for AWS Strands Agents.
+
+    Implements the strands HookProvider protocol (register_hooks) via duck
+    typing.  When strands-agents is not installed the class still fully
+    constructs and is usable for telemetry emission and steering context
+    loading.
+
+    Args:
+        sink_path:   Directory or file path for JSONL telemetry output.
+                     Default: <workspace>/.flow-agents/.telemetry/full.jsonl
+        workspace:   Root of the workspace to discover .flow-agents/ from.
+                     Default: current working directory.
+        agent_name:  Agent identifier embedded in telemetry events.
+        runtime:     Runtime label embedded in telemetry events.
+        policy_gate: Optional PolicyGate instance; defaults to PolicyGate().
+    """
+
+    def __init__(
+        self,
+        sink_path: Optional[str] = None,
+        workspace: Optional[str] = None,
+        agent_name: str = "strands-agent",
+        runtime: str = "strands",
+        policy_gate: Optional[PolicyGate] = None,
+    ) -> None:
+        self._sink = TelemetrySink(
+            sink_path=sink_path,
+            workspace=workspace,
+            agent_name=agent_name,
+            runtime=runtime,
+        )
+        self._policy = policy_gate if policy_gate is not None else PolicyGate()
+        self._steering = SteeringContext(workspace=workspace)
+        self._session_start_ts: Optional[float] = None
+
+    # ------------------------------------------------------------------
+    # Public API available WITHOUT strands installed
+    # ------------------------------------------------------------------
+
+    def steering_context(self) -> str:
+        """
+        Return workflow-steering context text for the current workspace.
+
+        Callers should append this to the Agent's system prompt at construction
+        time — e.g.:
+
+            system_prompt = base_prompt + hooks.steering_context()
+
+        This is the documented spike approach because Strands'
+        BeforeInvocationEvent does not expose a mutable system_prompt.
+        See README.md § Limitations.
+        """
+        text = self._steering.load()
+        if text:
+            self._sink.emit_steering(text)
+        return text
+
+    # ------------------------------------------------------------------
+    # HookProvider protocol (register_hooks)
+    # ------------------------------------------------------------------
+
+    def register_hooks(self, registry: Any, **kwargs: Any) -> None:
+        """
+        Register Flow Agents callbacks with a Strands HookRegistry.
+
+        This method is the sole method required by the HookProvider protocol.
+        The registry parameter is typed as Any so the module compiles without
+        strands-agents installed; at runtime the real HookRegistry is passed.
+        """
+        # Import lazily — only reachable when strands IS installed.
+        try:
+            from strands.hooks import (  # type: ignore[import]
+                BeforeInvocationEvent,
+                AfterInvocationEvent,
+                BeforeToolCallEvent,
+                AfterToolCallEvent,
+                AgentInitializedEvent,
+            )
+        except ImportError as exc:
+            raise ImportError(
+                "strands-agents is required to register hooks. "
+                "Install it with: pip install flow-agents-strands[strands]"
+            ) from exc
+
+        registry.add_callback(AgentInitializedEvent, self._on_agent_initialized)
+        registry.add_callback(BeforeInvocationEvent, self._on_before_invocation)
+        registry.add_callback(AfterInvocationEvent, self._on_after_invocation)
+        registry.add_callback(BeforeToolCallEvent, self._on_before_tool_call)
+        registry.add_callback(AfterToolCallEvent, self._on_after_tool_call)
+
+    # ------------------------------------------------------------------
+    # Private callbacks
+    # ------------------------------------------------------------------
+
+    def _on_agent_initialized(self, event: Any) -> None:
+        """AgentInitializedEvent → agentSpawn / session.start"""
+        self._session_start_ts = time.monotonic()
+        self._sink.emit_session_start()
+
+    def _on_before_invocation(self, event: Any) -> None:
+        """BeforeInvocationEvent → userPromptSubmit / turn.user"""
+        if self._session_start_ts is None:
+            self._session_start_ts = time.monotonic()
+        self._sink.emit("userPromptSubmit")
+
+    def _on_after_invocation(self, event: Any) -> None:
+        """AfterInvocationEvent → stop / session.end"""
+        duration_s = 0.0
+        if self._session_start_ts is not None:
+            duration_s = time.monotonic() - self._session_start_ts
+        self._sink.emit_session_end(duration_s=duration_s)
+
+    def _on_before_tool_call(self, event: Any) -> None:
+        """
+        BeforeToolCallEvent → preToolUse / tool.invoke + policy gate.
+
+        If the policy gate blocks the call, sets event.cancel_tool to the
+        block reason (Strands will cancel the tool and return the message
+        as the tool result).
+        """
+        tool_use = getattr(event, "tool_use", {}) or {}
+        tool_name = tool_use.get("name", "")
+        tool_input = tool_use.get("input", {}) or {}
+
+        # Emit telemetry first (fail-open: policy check follows)
+        self._sink.emit_tool_invoke(tool_name=tool_name, tool_input=tool_input)
+
+        # Policy gate
+        block_reason = self._policy.check_tool_call(
+            tool_name=tool_name,
+            tool_input=tool_input,
+        )
+        if block_reason:
+            try:
+                event.cancel_tool = block_reason
+            except AttributeError:
+                # Some event mock or future SDK change; log and continue
+                pass
+
+    def _on_after_tool_call(self, event: Any) -> None:
+        """AfterToolCallEvent → postToolUse / tool.result"""
+        tool_use = getattr(event, "tool_use", {}) or {}
+        tool_name = tool_use.get("name", "")
+        result = getattr(event, "result", None)
+        self._sink.emit_tool_result(tool_name=tool_name, tool_output=result)

package/integrations/strands/flow_agents_strands/policy.py

@@ -0,0 +1,348 @@
+"""
+policy.py — Policy gates for BeforeToolCallEvent.
+
+Primary binding: subprocess to the canonical Node.js engine
+(scripts/hooks/run-hook.js → config-protection.js) for the authoritative
+policy decision.  The tool-name pre-filter (write-like tools only) is applied
+in Python before calling the engine, since the engine itself does not filter by
+tool name — it blocks on the file basename alone.
+
+Fallback: if Node.js is absent or the engine script cannot be located, the gate
+degrades to the pure-Python implementation of the same logic and emits a
+one-time RuntimeWarning.  See README.md §Limitations.
+
+Engine contract (contract_version "1.0"):
+  - Payload: JSON on stdin with hook_event_name, tool_name, tool_input fields.
+  - Exit code 0 = allow, exit code 2 = block, other = error (fail-open).
+  - Stderr carries the block reason when exit code is 2.
+  - See docs/spec/runtime-hook-surface.md §8 for the full contract.
+
+Custom protected_files: when the caller passes a non-default ``protected_files``
+frozenset, the engine subprocess is bypassed and the Python evaluation is used
+directly (the subprocess cannot receive a runtime-custom set).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import warnings
+from pathlib import Path
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# Locate the canonical engine — supports both installed-package and repo layouts.
+# ---------------------------------------------------------------------------
+
+def _find_engine_paths() -> tuple[Optional[str], Optional[str]]:
+    """
+    Return (node_executable, run_hook_path) or (None, None) if unavailable.
+
+    Search order for run-hook.js:
+      1. Env var FLOW_AGENTS_ENGINE_PATH (explicit override).
+      2. Relative to this file: ../../../../scripts/hooks/run-hook.js
+         (works when running from the source repo checkout).
+      3. Installed via npm: walk up from CWD looking for
+         node_modules/@kontourai/flow-agents/scripts/hooks/run-hook.js
+    """
+    node = shutil.which("node")
+    if not node:
+        return None, None
+
+    # 1. Explicit override
+    env_path = os.environ.get("FLOW_AGENTS_ENGINE_PATH")
+    if env_path:
+        p = Path(env_path)
+        if p.is_file():
+            return node, str(p)
+
+    # 2. Relative to this source file (repo checkout: integrations/strands/flow_agents_strands/)
+    candidate = Path(__file__).parent.parent.parent.parent / "scripts" / "hooks" / "run-hook.js"
+    if candidate.is_file():
+        return node, str(candidate)
+
+    # 3. npm-installed package layout
+    cwd = Path.cwd()
+    for parent in [cwd, *cwd.parents]:
+        candidate = (
+            parent / "node_modules" / "@kontourai" / "flow-agents" / "scripts" / "hooks" / "run-hook.js"
+        )
+        if candidate.is_file():
+            return node, str(candidate)
+
+    return node, None
+
+
+# Resolved at module import time; callers can override via constructor parameters.
+_NODE_BIN, _RUN_HOOK_PATH = _find_engine_paths()
+
+
+# Sentinel for "not provided" constructor parameters
+_UNSET = object()
+
+# ---------------------------------------------------------------------------
+# Pure-Python fallback — mirrors config-protection.js PROTECTED_FILES
+# ---------------------------------------------------------------------------
+
+PROTECTED_FILES = frozenset(
+    [
+        # ESLint
+        ".eslintrc",
+        ".eslintrc.js",
+        ".eslintrc.cjs",
+        ".eslintrc.json",
+        ".eslintrc.yml",
+        ".eslintrc.yaml",
+        "eslint.config.js",
+        "eslint.config.mjs",
+        "eslint.config.cjs",
+        "eslint.config.ts",
+        "eslint.config.mts",
+        "eslint.config.cts",
+        # Prettier
+        ".prettierrc",
+        ".prettierrc.js",
+        ".prettierrc.cjs",
+        ".prettierrc.json",
+        ".prettierrc.yml",
+        ".prettierrc.yaml",
+        "prettier.config.js",
+        "prettier.config.cjs",
+        "prettier.config.mjs",
+        # Biome
+        "biome.json",
+        "biome.jsonc",
+        # Ruff
+        ".ruff.toml",
+        "ruff.toml",
+        # Others
+        ".shellcheckrc",
+        ".stylelintrc",
+        ".stylelintrc.json",
+        ".stylelintrc.yml",
+        ".markdownlint.json",
+        ".markdownlint.yaml",
+        ".markdownlintrc",
+    ]
+)
+
+_BLOCK_REASON_TEMPLATE = (
+    "BLOCKED: Modifying {basename} is not allowed. "
+    "Fix the source code to satisfy linter/formatter rules instead of "
+    "weakening the config. If this is a legitimate config change, "
+    "disable the config-protection policy gate temporarily."
+)
+
+# Write-like tool names — both the engine and the Python fallback only gate
+# write-like tools.  Reads on protected files are always allowed.
+_WRITE_TOOLS = frozenset(
+    {
+        "edit",
+        "write",
+        "fs_write",
+        "apply_patch",
+        "create_file",
+        "str_replace_editor",
+    }
+)
+
+
+def _python_config_protection(
+    tool_name: str,
+    tool_input: dict,
+    protected: frozenset = PROTECTED_FILES,
+) -> Optional[str]:
+    """
+    Pure-Python evaluation of config-protection.
+
+    Mirrors the logic in scripts/hooks/config-protection.js.
+    Called when Node.js is unavailable or a custom protected set is in use.
+    """
+    if tool_name.lower() not in _WRITE_TOOLS:
+        return None
+    file_path = tool_input.get("path") or tool_input.get("file_path") or ""
+    if not file_path:
+        return None
+    basename = Path(file_path).name
+    if basename in protected:
+        return _BLOCK_REASON_TEMPLATE.format(basename=basename)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Subprocess binding to the engine contract
+# ---------------------------------------------------------------------------
+
+def _invoke_engine(
+    hook_id: str,
+    hook_script: str,
+    payload: dict,
+    *,
+    node_bin: str,
+    run_hook_path: str,
+    extra_env: Optional[dict] = None,
+) -> tuple[int, str, str]:
+    """
+    Invoke the canonical engine via subprocess.
+
+    Returns (exit_code, stdout, stderr).
+    On subprocess errors returns (1, "", "<error>") so callers can fail-open.
+    """
+    env = dict(os.environ)
+    if extra_env:
+        env.update(extra_env)
+    env["FLOW_AGENTS_HOOK_RUNTIME"] = "strands"
+
+    # run-hook.js resolves hook_script relative to its own directory
+    hooks_dir = str(Path(run_hook_path).parent)
+
+    try:
+        result = subprocess.run(
+            [node_bin, run_hook_path, hook_id, hook_script],
+            input=json.dumps(payload),
+            capture_output=True,
+            text=True,
+            timeout=15,
+            env=env,
+            cwd=hooks_dir,
+        )
+        return result.returncode, result.stdout, result.stderr
+    except subprocess.TimeoutExpired:
+        return 1, "", "[policy] engine subprocess timed out"
+    except OSError as exc:
+        return 1, "", f"[policy] engine subprocess failed: {exc}"
+
+
+# ---------------------------------------------------------------------------
+# PolicyGate
+# ---------------------------------------------------------------------------
+
+
+class PolicyGate:
+    """
+    Evaluates tool-call policy gates.
+
+    Designed for use inside BeforeToolCallEvent callbacks; does NOT depend on
+    any Strands import so it is fully testable without the SDK installed.
+
+    Primary mode: spawns ``node run-hook.js config-protection.js`` to delegate
+    to the engine contract (contract_version "1.0").  The tool-name pre-filter
+    is applied in Python before calling the engine.
+
+    Fallback mode: if Node.js or the engine script is unavailable, degrades to
+    the built-in Python implementation and emits a one-time RuntimeWarning.
+
+    Custom protected_files: if a non-default frozenset is passed, Python
+    evaluation is used directly (the engine subprocess cannot accept a
+    runtime-custom set).  This is intended for tests and local override only.
+
+    The ``_node_bin`` and ``_run_hook_path`` constructor parameters allow tests
+    to inject fakes without touching the filesystem.
+    """
+
+    def __init__(
+        self,
+        protected_files: Optional[frozenset] = None,
+        _node_bin: object = _UNSET,
+        _run_hook_path: object = _UNSET,
+    ) -> None:
+        # Allow tests to inject explicit values (including None to force fallback).
+        # _UNSET means "use the module-level resolved value".
+        self._node_bin: Optional[str] = (
+            _node_bin if _node_bin is not _UNSET else _NODE_BIN  # type: ignore[assignment]
+        )
+        self._run_hook_path: Optional[str] = (
+            _run_hook_path if _run_hook_path is not _UNSET else _RUN_HOOK_PATH  # type: ignore[assignment]
+        )
+        # Custom protected set: bypass engine subprocess, use Python directly.
+        self._custom_protected: Optional[frozenset] = protected_files
+        self._warned_fallback = False
+
+    @property
+    def _engine_available(self) -> bool:
+        return bool(self._node_bin and self._run_hook_path)
+
+    def _warn_fallback(self) -> None:
+        if not self._warned_fallback:
+            self._warned_fallback = True
+            warnings.warn(
+                "flow-agents-strands: Node.js or the Flow Agents engine script is "
+                "not available. Policy gates are degrading to the built-in Python "
+                "fallback (fail-open for unknown cases). Install Node.js and ensure "
+                "the @kontourai/flow-agents package is reachable to use the canonical "
+                "engine contract. See README.md §Limitations.",
+                RuntimeWarning,
+                stacklevel=4,
+            )
+
+    def check_tool_call(
+        self,
+        tool_name: str,
+        tool_input: dict,
+    ) -> Optional[str]:
+        """
+        Evaluate policy for a tool call.
+
+        Returns None if the call is allowed, or a block-reason string if it
+        should be cancelled (the string becomes the cancel_tool message).
+        """
+        return self._check_config_protection(tool_name, tool_input)
+
+    def _check_config_protection(
+        self,
+        tool_name: str,
+        tool_input: dict,
+    ) -> Optional[str]:
+        """
+        Invoke config-protection.
+
+        Tool-name pre-filter: only write-like tools are gated.  Reads on
+        protected files are always allowed (this is the same rule as the JS
+        engine — the engine short-circuits for the same reason; the pre-filter
+        avoids the subprocess round-trip for non-write tools).
+
+        If a custom protected_files set was passed to the constructor, Python
+        evaluation is used instead of the engine subprocess.
+
+        If Node.js or the engine script is unavailable, falls back to Python
+        evaluation with the default PROTECTED_FILES set.
+        """
+        # Tool-name pre-filter (read tools always allowed)
+        if tool_name.lower() not in _WRITE_TOOLS:
+            return None
+
+        # Custom protected set → Python evaluation only
+        if self._custom_protected is not None:
+            return _python_config_protection(tool_name, tool_input, self._custom_protected)
+
+        # Engine subprocess → authoritative decision
+        if self._engine_available:
+            payload = {
+                "hook_event_name": "PreToolUse",
+                "tool_name": tool_name,
+                "tool_input": tool_input,
+            }
+
+            exit_code, stdout, stderr = _invoke_engine(
+                hook_id="config-protection",
+                hook_script="config-protection.js",
+                payload=payload,
+                node_bin=self._node_bin,
+                run_hook_path=self._run_hook_path,
+            )
+
+            if exit_code == 2:
+                reason = stderr.strip() or stdout.strip() or "BLOCKED: config-protection policy blocked this action."
+                return reason
+
+            if exit_code == 0:
+                return None
+
+            # Engine error (exit_code not 0 or 2) → fail-open
+            return None
+
+        # No engine available → Python fallback
+        self._warn_fallback()
+        return _python_config_protection(tool_name, tool_input)