@kontourai/flow-agents 0.1.2 → 0.2.0

package/integrations/strands/flow_agents_strands/telemetry.py

@@ -0,0 +1,238 @@
+"""
+telemetry.py — Canonical Flow Agents telemetry event builder and JSONL sink.
+
+Event taxonomy mirrors the JS telemetry hooks exactly:
+
+  claude-telemetry-hook.js  →  canonicalEvent() mapping:
+    SessionStart            → agentSpawn
+    UserPromptSubmit        → userPromptSubmit
+    PreToolUse              → preToolUse
+    PostToolUse             → postToolUse
+    PostToolUseFailure      → postToolUse
+    Stop / SessionEnd       → stop
+    SubagentStart           → subagentStart
+    SubagentStop            → subagentStop
+
+  telemetry.sh  →  schema_event_type():
+    agentSpawn / SessionStart           → session.start
+    stop / Stop / SessionEnd            → session.end
+    userPromptSubmit / UserPromptSubmit → turn.user
+    preToolUse / PreToolUse             → tool.invoke
+    postToolUse / PostToolUse           → tool.result
+
+Strands hook events are mapped to the same canonical names so the emitted
+JSONL records are structurally identical to those produced by the Claude Code
+and Codex telemetry hooks.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+# ---------------------------------------------------------------------------
+# Strands → canonical event-name mapping
+# (module-level dict so it is inspectable / documented)
+# ---------------------------------------------------------------------------
+
+STRANDS_TO_CANONICAL: Dict[str, str] = {
+    # Strands event class name  →  canonical Flow Agents event name
+    "AgentInitializedEvent":  "agentSpawn",
+    "BeforeInvocationEvent":  "userPromptSubmit",
+    "AfterInvocationEvent":   "stop",
+    "BeforeToolCallEvent":    "preToolUse",
+    "AfterToolCallEvent":     "postToolUse",
+    "AfterModelCallEvent":    "postToolUse",   # closest analogue; no tool name
+    "MessageAddedEvent":      "userPromptSubmit",
+}
+
+# Canonical → schema event type  (mirrors telemetry.sh schema_event_type())
+_CANONICAL_TO_SCHEMA: Dict[str, str] = {
+    "agentSpawn":        "session.start",
+    "userPromptSubmit":  "turn.user",
+    "preToolUse":        "tool.invoke",
+    "permissionRequest": "tool.permission_request",
+    "postToolUse":       "tool.result",
+    "stop":              "session.end",
+    "subagentStart":     "agent.delegate",
+    "subagentStop":      "agent.delegate",
+}
+
+
+def _schema_event_type(canonical: str) -> str:
+    return _CANONICAL_TO_SCHEMA.get(canonical, "unknown")
+
+
+# ---------------------------------------------------------------------------
+# JSONL sink
+# ---------------------------------------------------------------------------
+
+class TelemetrySink:
+    """
+    Writes canonical Flow Agents telemetry events to a JSONL file.
+
+    Default path: <workspace>/.flow-agents/.telemetry/full.jsonl
+    This matches the local-files sink convention from config.sh:
+      TELEMETRY_CHANNEL_FULL_LOG_FILE = <data_dir>/full.jsonl
+      where data_dir defaults to <repo_root>/.telemetry/
+
+    For the Strands adapter we follow the harness convention of writing
+    inside .flow-agents/.telemetry/ to keep everything under one dot-dir.
+    """
+
+    DEFAULT_SUBDIR = Path(".flow-agents") / ".telemetry"
+    DEFAULT_FILENAME = "full.jsonl"
+    SCHEMA_VERSION = "0.3.0"
+
+    def __init__(
+        self,
+        sink_path: Optional[str] = None,
+        workspace: Optional[str] = None,
+        agent_name: str = "strands-agent",
+        runtime: str = "strands",
+    ) -> None:
+        self.agent_name = agent_name
+        self.runtime = runtime
+        self._session_id: Optional[str] = None
+
+        ws = Path(workspace) if workspace else Path.cwd()
+        if sink_path:
+            p = Path(sink_path)
+            # If given a directory, append default filename
+            if p.suffix == "":
+                self._log_file = p / self.DEFAULT_FILENAME
+            else:
+                self._log_file = p
+        else:
+            self._log_file = ws / self.DEFAULT_SUBDIR / self.DEFAULT_FILENAME
+
+        self._log_file.parent.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def session_id(self) -> str:
+        if self._session_id is None:
+            self._session_id = str(uuid.uuid4())
+        return self._session_id
+
+    def _base_event(self, schema_event_type: str) -> Dict[str, Any]:
+        """Build the base event envelope matching telemetry.sh build_base_event()."""
+        return {
+            "schema_version": self.SCHEMA_VERSION,
+            "timestamp": str(int(time.time() * 1000)),
+            "session_id": self.session_id,
+            "event_id": str(uuid.uuid4()),
+            "event_type": schema_event_type,
+            "agent": {
+                "name": self.agent_name,
+                "runtime": self.runtime,
+                "version": "unknown",
+            },
+        }
+
+    def emit(
+        self,
+        canonical_event: str,
+        extra: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Build and write a canonical telemetry event.
+
+        Returns the emitted dict (useful for tests / callers that need the
+        event for further processing).
+        """
+        schema_type = _schema_event_type(canonical_event)
+        event = self._base_event(schema_type)
+
+        # Attach hook context stub (mirrors add_hook_context() in telemetry.sh)
+        event["hook"] = {
+            "event_name": canonical_event,
+            "runtime_session_id": "",
+            "turn_id": "",
+            "transcript_path": "",
+            "model": "",
+            "source": "strands",
+            "stop_hook_active": None,
+            "last_assistant_message": "",
+            "raw_input": None,
+        }
+
+        if extra:
+            event.update(extra)
+
+        try:
+            with self._log_file.open("a", encoding="utf-8") as fh:
+                fh.write(json.dumps(event) + "\n")
+        except OSError:
+            pass  # fail-open: telemetry must never block agent work
+
+        return event
+
+    def emit_session_start(self, extra: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return self.emit("agentSpawn", extra)
+
+    def emit_session_end(self, duration_s: float = 0.0) -> Dict[str, Any]:
+        return self.emit("stop", {"session": {"duration_s": duration_s}})
+
+    def emit_tool_invoke(
+        self,
+        tool_name: str,
+        tool_input: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        return self.emit(
+            "preToolUse",
+            {
+                "tool": {
+                    "name": tool_name,
+                    "normalized_name": _normalize_tool_name(tool_name),
+                    "input": tool_input,
+                }
+            },
+        )
+
+    def emit_tool_result(
+        self,
+        tool_name: str,
+        tool_output: Any = None,
+    ) -> Dict[str, Any]:
+        return self.emit(
+            "postToolUse",
+            {
+                "tool": {
+                    "name": tool_name,
+                    "normalized_name": _normalize_tool_name(tool_name),
+                    "output": tool_output,
+                }
+            },
+        )
+
+    def emit_steering(self, steering_text: str) -> Dict[str, Any]:
+        """Emit a synthetic userPromptSubmit event carrying steering context."""
+        return self.emit(
+            "userPromptSubmit",
+            {"turn": {"prompt_text": "", "steering_context": steering_text}},
+        )
+
+
+def _normalize_tool_name(name: str) -> str:
+    """
+    Mirror telemetry.sh normalize_tool_name() for the most common cases.
+    """
+    _MAP = {
+        "bash": "execute_bash",
+        "execute_bash": "execute_bash",
+        "shell": "execute_bash",
+        "edit": "fs_write",
+        "write": "fs_write",
+        "fs_write": "fs_write",
+        "apply_patch": "fs_write",
+        "read": "fs_read",
+        "fs_read": "fs_read",
+        "task": "use_subagent",
+        "agent": "use_subagent",
+        "use_subagent": "use_subagent",
+    }
+    return _MAP.get(name.lower(), name)

package/integrations/strands/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.backends.legacy:build"
+
+[project]
+name = "flow-agents-strands"
+version = "0.0.1"
+description = "Flow Agents framework adapter for AWS Strands Agents — telemetry, policy gates, and workflow steering via the Strands hook surface."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["flow-agents", "strands", "aws", "agents", "telemetry", "hooks"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+# No runtime dependencies — strands-agents is optional
+dependencies = []
+
+[project.optional-dependencies]
+# Install the real Strands SDK when you want to wire into a live Agent
+strands = [
+    "strands-agents>=0.1.0",
+]
+# Development / test extras
+dev = [
+    "strands-agents>=0.1.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["flow_agents_strands*"]

package/integrations/strands/tests/test_hooks.py

@@ -0,0 +1,304 @@
+"""
+Tests for FlowAgentsHooks — fake registry + fake event objects.
+
+These tests exercise the full hook-wiring path without requiring
+strands-agents to be installed.  A minimal fake registry / event surface
+mirrors the Strands API contract described in the mission brief.
+"""
+
+import json
+import sys
+import tempfile
+import types
+import unittest
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Fake Strands hook infrastructure (no SDK required)
+# ---------------------------------------------------------------------------
+
+class FakeHookRegistry:
+    """Minimal stand-in for strands.hooks.HookRegistry."""
+
+    def __init__(self):
+        self._callbacks: Dict[str, List[Callable]] = {}
+
+    def add_callback(self, event_cls, callback: Callable) -> None:
+        # Use the class's __name__ as the dispatch key
+        key = event_cls.__name__
+        self._callbacks.setdefault(key, []).append(callback)
+
+    def fire(self, event) -> None:
+        key = type(event).__name__
+        for cb in self._callbacks.get(key, []):
+            cb(event)
+
+
+# Fake event classes — named to match what register_hooks imports from strands.hooks
+class AgentInitializedEvent:
+    pass
+
+
+class BeforeInvocationEvent:
+    pass
+
+
+class AfterInvocationEvent:
+    pass
+
+
+class BeforeToolCallEvent:
+    cancel_tool: Optional[str] = None
+
+    def __init__(self, tool_name: str, tool_input: Optional[dict] = None):
+        self.tool_use = {"name": tool_name, "input": tool_input or {}}
+        self.cancel_tool = None
+
+
+class AfterToolCallEvent:
+    def __init__(self, tool_name: str, result: Any = None):
+        self.tool_use = {"name": tool_name, "input": {}}
+        self.result = result
+        self.retry = False
+
+
+# ---------------------------------------------------------------------------
+# Install fake strands module into sys.modules so FlowAgentsHooks can import
+# from strands.hooks without the real SDK being installed.
+# ---------------------------------------------------------------------------
+
+def _install_fake_strands() -> None:
+    """Install minimal fake strands.hooks module into sys.modules."""
+    strands_mod = types.ModuleType("strands")
+    hooks_mod = types.ModuleType("strands.hooks")
+
+    # Register each class using its canonical Strands name (the class __name__)
+    for cls in [
+        AgentInitializedEvent,
+        BeforeInvocationEvent,
+        AfterInvocationEvent,
+        BeforeToolCallEvent,
+        AfterToolCallEvent,
+    ]:
+        setattr(hooks_mod, cls.__name__, cls)
+
+    strands_mod.hooks = hooks_mod  # type: ignore[attr-defined]
+    sys.modules["strands"] = strands_mod
+    sys.modules["strands.hooks"] = hooks_mod
+
+
+_install_fake_strands()
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+class TestFlowAgentsHooksRegistration(unittest.TestCase):
+    """Verify register_hooks wires callbacks without raising."""
+
+    def _make_hooks(self, tmp_dir: str):
+        from flow_agents_strands import FlowAgentsHooks
+        return FlowAgentsHooks(sink_path=tmp_dir, agent_name="test-agent")
+
+    def test_register_hooks_runs_without_error(self):
+        with tempfile.TemporaryDirectory() as d:
+            hooks = self._make_hooks(d)
+            registry = FakeHookRegistry()
+            hooks.register_hooks(registry)
+            self.assertTrue(len(registry._callbacks) > 0)
+
+    def test_all_five_event_types_registered(self):
+        with tempfile.TemporaryDirectory() as d:
+            hooks = self._make_hooks(d)
+            registry = FakeHookRegistry()
+            hooks.register_hooks(registry)
+            expected = {
+                "AgentInitializedEvent",
+                "BeforeInvocationEvent",
+                "AfterInvocationEvent",
+                "BeforeToolCallEvent",
+                "AfterToolCallEvent",
+            }
+            self.assertEqual(expected, set(registry._callbacks.keys()))
+
+
+class TestFlowAgentsHooksTelemetry(unittest.TestCase):
+    """Verify telemetry events are emitted with correct shape."""
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self._tmp_path = Path(self._tmp.name)
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def _make_hooks(self):
+        from flow_agents_strands import FlowAgentsHooks
+        return FlowAgentsHooks(
+            sink_path=str(self._tmp_path),
+            agent_name="test-agent",
+        )
+
+    def _read_events(self):
+        log_file = self._tmp_path / "full.jsonl"
+        if not log_file.exists():
+            return []
+        return [
+            json.loads(line)
+            for line in log_file.read_text(encoding="utf-8").splitlines()
+            if line.strip()
+        ]
+
+    def test_session_start_emitted_on_agent_initialized(self):
+        hooks = self._make_hooks()
+        hooks._on_agent_initialized(AgentInitializedEvent())
+        events = self._read_events()
+        self.assertEqual(1, len(events))
+        self.assertEqual("session.start", events[0]["event_type"])
+
+    def test_tool_invoke_emitted_on_before_tool_call(self):
+        hooks = self._make_hooks()
+        event = BeforeToolCallEvent("read", {"path": "README.md"})
+        hooks._on_before_tool_call(event)
+        events = self._read_events()
+        self.assertEqual(1, len(events))
+        self.assertEqual("tool.invoke", events[0]["event_type"])
+        self.assertEqual("read", events[0]["tool"]["name"])
+
+    def test_tool_result_emitted_on_after_tool_call(self):
+        hooks = self._make_hooks()
+        event = AfterToolCallEvent("read", result="file content")
+        hooks._on_after_tool_call(event)
+        events = self._read_events()
+        self.assertEqual(1, len(events))
+        self.assertEqual("tool.result", events[0]["event_type"])
+        self.assertEqual("file content", events[0]["tool"]["output"])
+
+    def test_session_end_emitted_on_after_invocation(self):
+        hooks = self._make_hooks()
+        hooks._on_agent_initialized(AgentInitializedEvent())
+        hooks._on_after_invocation(AfterInvocationEvent())
+        events = self._read_events()
+        types_ = [e["event_type"] for e in events]
+        self.assertIn("session.end", types_)
+
+    def test_full_lifecycle_produces_correct_sequence(self):
+        hooks = self._make_hooks()
+        hooks._on_agent_initialized(AgentInitializedEvent())
+        hooks._on_before_invocation(BeforeInvocationEvent())
+        hooks._on_before_tool_call(BeforeToolCallEvent("bash", {"command": "ls"}))
+        hooks._on_after_tool_call(AfterToolCallEvent("bash", result="file1.py"))
+        hooks._on_after_invocation(AfterInvocationEvent())
+
+        events = self._read_events()
+        types_ = [e["event_type"] for e in events]
+        self.assertEqual(
+            ["session.start", "turn.user", "tool.invoke", "tool.result", "session.end"],
+            types_,
+        )
+
+
+class TestFlowAgentsHooksPolicyGate(unittest.TestCase):
+    """
+    Verify tool-call cancellation on protected-config writes.
+
+    This is the key spike proof-point: a BeforeToolCallEvent targeting a
+    protected config file must result in event.cancel_tool being set.
+    """
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def _make_hooks(self):
+        from flow_agents_strands import FlowAgentsHooks
+        return FlowAgentsHooks(sink_path=self._tmp.name, agent_name="test")
+
+    def test_cancel_tool_set_for_protected_write(self):
+        hooks = self._make_hooks()
+        event = BeforeToolCallEvent("write", {"path": ".eslintrc.json"})
+        hooks._on_before_tool_call(event)
+        self.assertIsNotNone(event.cancel_tool)
+        self.assertIn("BLOCKED", event.cancel_tool)
+
+    def test_cancel_tool_not_set_for_safe_write(self):
+        hooks = self._make_hooks()
+        event = BeforeToolCallEvent("write", {"path": "src/main.py"})
+        hooks._on_before_tool_call(event)
+        self.assertIsNone(event.cancel_tool)
+
+    def test_cancel_tool_not_set_for_read_on_protected_file(self):
+        hooks = self._make_hooks()
+        event = BeforeToolCallEvent("read", {"path": ".eslintrc.json"})
+        hooks._on_before_tool_call(event)
+        self.assertIsNone(event.cancel_tool)
+
+    def test_cancel_tool_covers_all_protected_files(self):
+        from flow_agents_strands.policy import PROTECTED_FILES
+        hooks = self._make_hooks()
+        for fname in PROTECTED_FILES:
+            with self.subTest(file=fname):
+                event = BeforeToolCallEvent("write", {"path": f"/repo/{fname}"})
+                hooks._on_before_tool_call(event)
+                self.assertIsNotNone(
+                    event.cancel_tool,
+                    f"Expected cancel_tool for {fname} but got None",
+                )
+
+    def test_telemetry_still_emitted_even_when_cancelled(self):
+        """Policy block must not suppress telemetry."""
+        hooks = self._make_hooks()
+        event = BeforeToolCallEvent("write", {"path": "biome.json"})
+        hooks._on_before_tool_call(event)
+        log_file = Path(self._tmp.name) / "full.jsonl"
+        lines = log_file.read_text(encoding="utf-8").strip().splitlines()
+        self.assertEqual(1, len(lines))
+        parsed = json.loads(lines[0])
+        self.assertEqual("tool.invoke", parsed["event_type"])
+
+
+class TestFlowAgentsHooksSteeringContext(unittest.TestCase):
+    """Verify steering context loads without error in an empty workspace."""
+
+    def test_steering_context_returns_string(self):
+        with tempfile.TemporaryDirectory() as d:
+            from flow_agents_strands import FlowAgentsHooks
+            hooks = FlowAgentsHooks(sink_path=d, workspace=d)
+            ctx = hooks.steering_context()
+            self.assertIsInstance(ctx, str)
+
+    def test_steering_context_empty_when_no_flow_agents_dir(self):
+        with tempfile.TemporaryDirectory() as d:
+            from flow_agents_strands import FlowAgentsHooks
+            hooks = FlowAgentsHooks(sink_path=d, workspace=d)
+            ctx = hooks.steering_context()
+            self.assertEqual("", ctx)
+
+    def test_steering_context_with_active_state(self):
+        """If .flow-agents/task/state.json has active status, context is returned."""
+        with tempfile.TemporaryDirectory() as d:
+            state_dir = Path(d) / ".flow-agents" / "my-task"
+            state_dir.mkdir(parents=True)
+            state = {
+                "task_slug": "my-task",
+                "status": "in_progress",
+                "phase": "execute",
+                "next_action": {"summary": "Run tests", "target_phase": "verify"},
+            }
+            (state_dir / "state.json").write_text(
+                json.dumps(state), encoding="utf-8"
+            )
+            from flow_agents_strands import FlowAgentsHooks
+            hooks = FlowAgentsHooks(sink_path=d, workspace=d)
+            ctx = hooks.steering_context()
+            self.assertIn("my-task", ctx)
+            self.assertIn("in_progress", ctx)
+
+
+if __name__ == "__main__":
+    unittest.main()