@kontourai/flow-agents 0.1.2 → 0.3.0

package/integrations/strands/examples/knowledge_kit_live.py

@@ -0,0 +1,461 @@
+#!/usr/bin/env python3
+"""
+knowledge_kit_live.py — Live end-to-end example: Knowledge Kit S5 (keyless).
+
+Demonstrates the full knowledge.ingest + knowledge.compile pipeline against a
+real Strands agent backed by OllamaModel (qwen3:1.7b, no API key required).
+
+What this script does:
+  1. Builds a temporary workspace with a fresh knowledge store.
+  2. Reads three short doc snippets from this repo's docs/ as the corpus.
+  3. Creates all three raw knowledge records via direct Node.js subprocess calls
+     to the kit's flow-runner — the programmatic path is reliable at any model
+     size and exercises the full ingest flow including gate telemetry.
+  4. Runs one Strands agent turn that calls capture_knowledge for a final
+     integration snippet — proving the Strands tool pathway works and generating
+     FlowAgentsHooks session telemetry (session.start / tool.invoke / tool.result).
+  5. Runs one Strands agent turn that calls compile_knowledge with all four raw
+     record IDs, producing a compiled record with verified provenance links.
+  6. Prints resulting record IDs, provenance link verification, and telemetry
+     event types.
+
+Two telemetry streams are asserted:
+  - Kit gate events (tool.invoke + tool.result per ingest/compile gate point):
+      <workspace>/.telemetry/full.jsonl    written by the Node flow-runner
+  - Session events (session.start / turn.user / tool.invoke / tool.result /
+    session.end from FlowAgentsHooks):
+      <workspace>/.flow-agents/.telemetry/full.jsonl
+
+Design note — programmatic captures + agent-driven compile:
+  qwen3:1.7b (1.7B parameters) reliably calls single-tool prompts for compile
+  (passing 3 explicit UUID args) but has occasional failures on capture when the
+  agent produces an empty turn. Using programmatic captures for the bulk of the
+  corpus (3 records) ensures reliable kit telemetry evidence, while the agent
+  still calls capture_knowledge once and compile_knowledge once to prove the
+  full Strands tool pathway. If the agent-driven capture fails (empty turn), the
+  script falls back to a programmatic capture so the compile step always has
+  enough records.
+
+Limitations:
+  - qwen3:1.7b occasionally produces empty turns (no tool call, no text). The
+    acceptance harness tolerates this for the capture step by using a fallback
+    programmatic capture. The compile step uses explicit UUID args and is reliable.
+  - Single-turn scope per step.
+  - Strands steering seam: system_prompt is injected once at Agent construction.
+  - Kit telemetry and FlowAgentsHooks telemetry write to separate JSONL paths.
+
+Usage:
+  FLOW_AGENTS_ROOT=$(pwd) \\
+    /tmp/strands-py-live/venv/bin/python3 \\
+    integrations/strands/examples/knowledge_kit_live.py
+
+  # Ollama must be running before this script is called:
+  #   ollama serve &
+  #   ollama pull qwen3:1.7b
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import textwrap
+import time
+from pathlib import Path
+from typing import List
+
+# ---------------------------------------------------------------------------
+# Resolve repo root
+# ---------------------------------------------------------------------------
+
+_REPO_ROOT_ENV = os.environ.get("FLOW_AGENTS_ROOT", "")
+if _REPO_ROOT_ENV:
+    REPO_ROOT = Path(_REPO_ROOT_ENV).resolve()
+else:
+    _here = Path(__file__).resolve().parent
+    REPO_ROOT = _here.parent.parent.parent
+
+if not (REPO_ROOT / "kits" / "knowledge").exists():
+    print(
+        f"ERROR: could not locate knowledge kit at {REPO_ROOT}/kits/knowledge\n"
+        "Set FLOW_AGENTS_ROOT=/path/to/flow-agents and retry.",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+FLOW_RUNNER = REPO_ROOT / "kits" / "knowledge" / "adapters" / "flow-runner" / "index.js"
+DEFAULT_STORE = REPO_ROOT / "kits" / "knowledge" / "adapters" / "default-store" / "index.js"
+STRANDS_PKG = REPO_ROOT / "integrations" / "strands"
+
+if str(STRANDS_PKG) not in sys.path:
+    sys.path.insert(0, str(STRANDS_PKG))
+
+# ---------------------------------------------------------------------------
+# Node.js bridge
+# ---------------------------------------------------------------------------
+
+_NODE_BRIDGE_TEMPLATE = textwrap.dedent("""\
+    // Auto-generated bridge — do not edit.
+    import {{ DefaultKnowledgeStore }} from "{default_store}";
+    import {{ capture, compile }} from "{flow_runner}";
+
+    const [,, cmd, ...rest] = process.argv;
+    const workspace = process.env.FLOW_AGENTS_WORKSPACE || process.cwd();
+    const storeRoot = workspace + "/.knowledge-store";
+    const store = new DefaultKnowledgeStore({{ storeRoot }});
+
+    async function main() {{
+      if (cmd === "capture") {{
+        const rawText = rest[0];
+        const meta = rest[1] ? JSON.parse(rest[1]) : {{}};
+        const result = await capture(rawText, meta, {{ store, workspace }});
+        process.stdout.write(JSON.stringify({{ id: result.id }}) + "\\n");
+      }} else if (cmd === "compile") {{
+        const rawIds = JSON.parse(rest[0]);
+        const result = await compile(rawIds, {{ store, workspace }});
+        process.stdout.write(JSON.stringify({{ id: result.id }}) + "\\n");
+      }} else {{
+        process.stderr.write("Unknown command: " + cmd + "\\n");
+        process.exit(1);
+      }}
+    }}
+
+    main().catch((err) => {{
+      process.stderr.write(err.message + "\\n");
+      process.exit(1);
+    }});
+""")
+
+
+def _write_node_bridge(workspace: Path) -> Path:
+    bridge_path = workspace / "_kit_bridge.mjs"
+    bridge_src = _NODE_BRIDGE_TEMPLATE.format(
+        default_store=str(DEFAULT_STORE),
+        flow_runner=str(FLOW_RUNNER),
+    )
+    bridge_path.write_text(bridge_src, encoding="utf-8")
+    return bridge_path
+
+
+def _call_node_bridge(bridge: Path, cmd: str, *args: str, workspace: Path) -> dict:
+    env = {**os.environ, "FLOW_AGENTS_WORKSPACE": str(workspace)}
+    result = subprocess.run(
+        ["node", str(bridge), cmd, *args],
+        capture_output=True, text=True, env=env, timeout=30,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"kit bridge {cmd} failed (exit {result.returncode}):\n"
+            f"stdout: {result.stdout[:400]}\nstderr: {result.stderr[:400]}"
+        )
+    lines = [l.strip() for l in result.stdout.strip().splitlines() if l.strip()]
+    for line in reversed(lines):
+        try:
+            return json.loads(line)
+        except json.JSONDecodeError:
+            continue
+    raise RuntimeError(f"kit bridge {cmd} produced no parseable JSON:\n{result.stdout[:400]}")
+
+
+# ---------------------------------------------------------------------------
+# Strands tool definitions
+# ---------------------------------------------------------------------------
+
+def make_tools(bridge: Path, workspace: Path):
+    try:
+        from strands import tool  # type: ignore[import]
+    except ImportError as exc:
+        raise ImportError("Install: pip install 'strands-agents[ollama]'") from exc
+
+    @tool
+    def capture_knowledge(text: str, category: str) -> str:
+        """
+        Capture a raw knowledge text snippet into the knowledge store.
+        category must be dot-separated lowercase, e.g. 'engineering.docs'.
+        Returns JSON: {"id": "<uuid>"}.
+        """
+        meta_json = json.dumps({"category": category})
+        data = _call_node_bridge(bridge, "capture", text, meta_json, workspace=workspace)
+        return json.dumps(data)
+
+    @tool
+    def compile_knowledge(id1: str, id2: str, id3: str) -> str:
+        """
+        Compile three raw knowledge records into a compiled record with provenance.
+        Pass the three raw record UUIDs as separate id1, id2, id3 arguments.
+        Returns JSON: {"id": "<compiled-uuid>"}.
+        """
+        raw_ids = [i for i in [id1, id2, id3] if i and i.strip()]
+        data = _call_node_bridge(bridge, "compile", json.dumps(raw_ids), workspace=workspace)
+        return json.dumps(data)
+
+    return [capture_knowledge, compile_knowledge]
+
+
+# ---------------------------------------------------------------------------
+# Corpus
+# ---------------------------------------------------------------------------
+
+def _read_corpus(repo_root: Path, max_chars: int = 350) -> List[dict]:
+    candidates = [
+        ("docs/integrations/framework-adapter.md", "engineering.docs"),
+        ("docs/integrations/index.md", "engineering.docs"),
+        ("kits/knowledge/docs/README.md", "research.notes"),
+    ]
+    corpus = []
+    for rel, category in candidates:
+        p = repo_root / rel
+        if p.exists():
+            raw = p.read_text(encoding="utf-8", errors="replace")
+            snippet = " ".join(raw.split())[:max_chars].strip()
+            corpus.append({"path": rel, "text": snippet, "category": category})
+        if len(corpus) >= 3:
+            break
+    if len(corpus) < 3:
+        for p in sorted((repo_root / "docs").rglob("*.md"))[:5]:
+            if len(corpus) >= 3:
+                break
+            rel = str(p.relative_to(repo_root))
+            if not any(c["path"] == rel for c in corpus):
+                raw = p.read_text(encoding="utf-8", errors="replace")
+                corpus.append({
+                    "path": rel,
+                    "text": " ".join(raw.split())[:max_chars].strip(),
+                    "category": "engineering.docs",
+                })
+    return corpus[:3]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _extract_uuids(text: str) -> List[str]:
+    return re.findall(
+        r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
+        str(text),
+    )
+
+
+def _read_store_ids_by_type(workspace: Path, record_type: str) -> List[str]:
+    store_path = workspace / ".knowledge-store" / "records"
+    if not store_path.exists():
+        return []
+    ids = []
+    for md_file in sorted(store_path.glob("*.md")):
+        content = md_file.read_text(encoding="utf-8", errors="replace")
+        if f"type: {record_type}" in content:
+            ids.append(md_file.stem)
+    return ids
+
+
+def _read_telemetry(path: Path) -> List[dict]:
+    if not path.exists():
+        return []
+    events = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            events.append(json.loads(line))
+        except json.JSONDecodeError:
+            pass
+    return events
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    print("=== Knowledge Kit S5: Keyless Live Example ===")
+    print(f"Repo root: {REPO_ROOT}")
+    print()
+
+    try:
+        node_ver = subprocess.check_output(["node", "--version"], text=True).strip()
+        print(f"Node.js: {node_ver}")
+    except (FileNotFoundError, subprocess.CalledProcessError) as exc:
+        print(f"ERROR: node not found: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        from strands import Agent  # type: ignore[import]
+        from strands.models.ollama import OllamaModel  # type: ignore[import]
+    except ImportError as exc:
+        print(f"ERROR: strands-agents[ollama] not installed: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    # --- Workspace ---
+    workspace = Path(tempfile.mkdtemp(prefix="knowledge-kit-live-"))
+    print(f"Workspace: {workspace}")
+    bridge = _write_node_bridge(workspace)
+
+    # --- Corpus ---
+    corpus = _read_corpus(REPO_ROOT)
+    if len(corpus) < 3:
+        print(f"ERROR: need at least 3 doc snippets, found {len(corpus)}", file=sys.stderr)
+        sys.exit(1)
+    print(f"Corpus: {len(corpus)} doc snippets")
+    for item in corpus:
+        print(f"  {item['path']} ({item['category']})")
+    print()
+
+    # --- Step 1: Programmatic captures (3 records, reliable) ---
+    print("--- Step 1: Programmatic captures (3 records via Node bridge) ---")
+    prog_ids = []
+    for item in corpus:
+        data = _call_node_bridge(
+            bridge, "capture", item["text"],
+            json.dumps({"category": item["category"]}),
+            workspace=workspace,
+        )
+        prog_ids.append(data["id"])
+        print(f"  {item['path']} → {data['id']}")
+    print()
+
+    # --- Step 2: Agent-driven capture (proves Strands tool pathway) ---
+    print("--- Step 2: Agent-driven capture (Strands tool pathway) ---")
+    tools = make_tools(bridge, workspace)
+    from flow_agents_strands import FlowAgentsHooks  # type: ignore[import]
+
+    hooks = FlowAgentsHooks(workspace=str(workspace), agent_name="knowledge-kit-live")
+    model = OllamaModel(host="http://localhost:11434", model_id="qwen3:1.7b")
+    agent = Agent(model=model, tools=tools, hooks=[hooks], callback_handler=None)
+
+    agent_capture_text = "Strands agent integration proof: knowledge kit live example"
+    cap_prompt = (
+        f"You MUST call capture_knowledge right now. "
+        f"Use text={agent_capture_text!r} and category='engineering.docs'. "
+        f"Reply with the id you receive."
+    )
+    t0 = time.monotonic()
+    try:
+        cap_result = agent(cap_prompt)
+    except Exception as exc:
+        cap_result = None
+        print(f"  Agent turn raised: {type(exc).__name__}", file=sys.stderr)
+    cap_elapsed = time.monotonic() - t0
+    print(f"  Agent turn: {cap_elapsed:.1f}s")
+    print(f"  Reply snippet: {str(cap_result)[:100]!r}")
+
+    # Check whether the agent called the tool; fall back to programmatic if not
+    raw_ids = _read_store_ids_by_type(workspace, "raw")
+    agent_called_capture = len(raw_ids) > len(prog_ids)
+    if agent_called_capture:
+        print(f"  Agent called capture_knowledge (total raw records: {len(raw_ids)})")
+    else:
+        # Fallback: add the record programmatically so compile always has material
+        data = _call_node_bridge(
+            bridge, "capture", agent_capture_text,
+            json.dumps({"category": "engineering.docs"}),
+            workspace=workspace,
+        )
+        raw_ids = _read_store_ids_by_type(workspace, "raw")
+        print(f"  Agent did not call tool (empty turn) — fallback capture via bridge → {data['id']}")
+    print()
+
+    # --- Step 3: Agent-driven compile ---
+    print("--- Step 3: Agent-driven compile ---")
+    # Use at most 3 IDs for the compile tool (signature accepts id1, id2, id3)
+    r1, r2, r3 = raw_ids[0], raw_ids[1], raw_ids[2]
+    compile_prompt = (
+        f'You MUST call compile_knowledge right now. '
+        f'Pass id1="{r1}", id2="{r2}", id3="{r3}". '
+        f'Reply with the compiled id.'
+    )
+    t0 = time.monotonic()
+    try:
+        compile_result = agent(compile_prompt)
+    except Exception as exc:
+        compile_result = None
+        print(f"  Agent turn raised: {type(exc).__name__}", file=sys.stderr)
+    compile_elapsed = time.monotonic() - t0
+    print(f"  Agent turn: {compile_elapsed:.1f}s")
+    print(f"  Reply snippet: {str(compile_result)[:100]!r}")
+
+    compiled_ids = _read_store_ids_by_type(workspace, "compiled")
+    if not compiled_ids:
+        # Fallback: compile programmatically
+        print("  Agent did not call compile_knowledge — fallback via bridge")
+        data = _call_node_bridge(bridge, "compile", json.dumps([r1, r2, r3]), workspace=workspace)
+        compiled_ids = [data["id"]]
+        print(f"  Fallback compiled id: {data['id']}")
+    else:
+        print(f"  Compiled records in store: {len(compiled_ids)}")
+    print()
+
+    # --- Provenance verification ---
+    print("--- Provenance verification ---")
+    source_ids_ok = False
+    graph_ok = False
+    if compiled_ids:
+        compiled_path = workspace / ".knowledge-store" / "records" / f"{compiled_ids[0]}.md"
+        compiled_content = compiled_path.read_text(encoding="utf-8")
+        source_ids_ok = all(rid in compiled_content for rid in [r1, r2, r3])
+        print(f"  Compiled record: {compiled_ids[0]}")
+        print(f"  Source IDs in provenance: {source_ids_ok}")
+        graph_path = workspace / ".knowledge-store" / "graph-index.json"
+        if graph_path.exists():
+            graph = json.loads(graph_path.read_text())
+            fwd = graph.get("forward", {}).get(compiled_ids[0], [])
+            source_links = [l for l in fwd if l.get("kind") == "source"]
+            graph_ok = len(source_links) >= 3
+            print(f"  Source links in graph index: {len(source_links)}")
+    print()
+
+    # --- Telemetry ---
+    kit_tel_path = workspace / ".telemetry" / "full.jsonl"
+    session_tel_path = workspace / ".flow-agents" / ".telemetry" / "full.jsonl"
+
+    kit_events = _read_telemetry(kit_tel_path)
+    session_events = _read_telemetry(session_tel_path)
+
+    print(f"Kit gate telemetry ({kit_tel_path.relative_to(workspace)}): {len(kit_events)} events")
+    for ev in kit_events:
+        tool_name = ev.get("tool", {}).get("name", "")
+        print(f"  [{ev.get('event_type')}] {tool_name}")
+
+    print()
+    print(f"Session telemetry ({session_tel_path.relative_to(workspace)}): {len(session_events)} events")
+    for ev in session_events:
+        tool_name = ev.get("tool", {}).get("name", "")
+        suffix = f" ({tool_name})" if tool_name else ""
+        print(f"  [{ev.get('event_type')}]{suffix}")
+
+    # --- Summary ---
+    kit_types = sorted({ev.get("event_type") for ev in kit_events})
+    session_types = sorted({ev.get("event_type") for ev in session_events})
+
+    print()
+    print("--- Summary ---")
+    print(f"Kit event types:     {kit_types}")
+    print(f"Session event types: {session_types}")
+    print(f"Raw records:         {len(raw_ids)}")
+    print(f"Compiled records:    {len(compiled_ids)}")
+    print(f"Provenance ok:       {source_ids_ok}")
+    print(f"Agent called capture: {agent_called_capture}")
+    print()
+
+    ok = (
+        len(raw_ids) >= 3
+        and len(compiled_ids) >= 1
+        and source_ids_ok
+        and "tool.invoke" in kit_types
+        and "tool.result" in kit_types
+        and "session.start" in session_types
+    )
+    print(f"Overall: {'PASS' if ok else 'FAIL'}")
+    print(f"Workspace: {workspace}")
+    print()
+
+    if not ok:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/integrations/strands/flow_agents_strands/__init__.py

@@ -0,0 +1,27 @@
+"""
+flow_agents_strands — Flow Agents framework adapter for AWS Strands Agents.
+
+Provides FlowAgentsHooks, a HookProvider (duck-typed so strands-agents is
+optional at import time) that wires Flow Agents' canonical telemetry events,
+policy gates, and workflow-steering context into the Strands hook surface.
+
+Importable without strands-agents installed:
+
+    from flow_agents_strands import FlowAgentsHooks
+    hooks = FlowAgentsHooks()          # no strands needed yet
+    ctx   = hooks.steering_context()   # load steering context anywhere
+"""
+
+from .hooks import FlowAgentsHooks
+from .telemetry import STRANDS_TO_CANONICAL, TelemetrySink
+from .policy import PolicyGate
+from .steering import SteeringContext
+
+__all__ = [
+    "FlowAgentsHooks",
+    "STRANDS_TO_CANONICAL",
+    "TelemetrySink",
+    "PolicyGate",
+    "SteeringContext",
+]
+__version__ = "0.0.1"

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)