@kontourai/flow-agents 0.1.2 → 0.2.0

package/integrations/strands/README.md

@@ -0,0 +1,256 @@
+# flow-agents-strands
+
+**SPIKE — Framework Adapter Proof of Concept**
+
+This package proves the thesis: Flow Agents' process-discipline layer
+(telemetry events + workflow steering + policy gates) can compile to a
+**framework adapter** hook surface — here, AWS Strands Agents — not just
+coding-agent harnesses.
+
+---
+
+## Harness adapters vs. framework adapters
+
+The existing Flow Agents adapters (`claude-code/`, `codex/`, `kiro/`) are
+**harness adapters**: they integrate with coding-agent runtimes that each have
+their own hook format (JSON on stdin, exit codes, lifecycle events named by
+the harness).  Each adapter normalizes its harness's hook payloads into the
+canonical Flow Agents telemetry taxonomy and then delegates to the shared
+`scripts/telemetry/telemetry.sh` sink.
+
+This package is a **framework adapter**: Strands Agents is not a coding-agent
+harness — it is a general-purpose Python agent SDK.  Its hook surface
+(`HookProvider` / `HookRegistry`) is class-based and synchronous rather than
+process-based.  This means:
+
+- No stdin/stdout protocol.
+- No process exit codes as block signals.
+- Hook callbacks receive typed Python event objects and can mutate them in
+  place (e.g. set `event.cancel_tool` to block a tool call).
+
+Despite these surface differences, the **same canonical event taxonomy** is
+used.  The JSONL output from `FlowAgentsHooks` is structurally identical to
+the output produced by `claude-telemetry-hook.js` and `codex-telemetry-hook.js`.
+
+---
+
+## Canonical event taxonomy
+
+All telemetry events follow the schema defined in `scripts/telemetry/telemetry.sh`.
+The Strands → canonical mapping is exposed as a module-level dict:
+
+```python
+from flow_agents_strands import STRANDS_TO_CANONICAL
+# {
+#   "AgentInitializedEvent":  "agentSpawn",
+#   "BeforeInvocationEvent":  "userPromptSubmit",
+#   "AfterInvocationEvent":   "stop",
+#   "BeforeToolCallEvent":    "preToolUse",
+#   "AfterToolCallEvent":     "postToolUse",
+#   "AfterModelCallEvent":    "postToolUse",
+#   "MessageAddedEvent":      "userPromptSubmit",
+# }
+```
+
+Canonical names map to schema `event_type` values:
+
+| Canonical name        | Schema event_type          |
+|-----------------------|----------------------------|
+| `agentSpawn`          | `session.start`            |
+| `userPromptSubmit`    | `turn.user`                |
+| `preToolUse`          | `tool.invoke`              |
+| `permissionRequest`   | `tool.permission_request`  |
+| `postToolUse`         | `tool.result`              |
+| `stop`                | `session.end`              |
+
+---
+
+## Telemetry sink
+
+Events are written to `.flow-agents/.telemetry/full.jsonl` by default,
+matching the local-files sink convention in `scripts/telemetry/lib/config.sh`:
+
+```
+TELEMETRY_CHANNEL_FULL_LOG_FILE = <data_dir>/full.jsonl
+```
+
+The JSON record shape matches `build_base_event()` in `telemetry.sh`:
+
+```json
+{
+  "schema_version": "0.3.0",
+  "timestamp": "1718000000000",
+  "session_id": "<uuid>",
+  "event_id": "<uuid>",
+  "event_type": "tool.invoke",
+  "agent": { "name": "strands-agent", "runtime": "strands", "version": "unknown" },
+  "hook": { "event_name": "preToolUse", "source": "strands", ... },
+  "tool": { "name": "edit", "normalized_name": "fs_write", "input": {...} }
+}
+```
+
+---
+
+## Policy gates
+
+The config-protection policy binds to the canonical Node.js engine
+(`scripts/hooks/run-hook.js → config-protection.js`) via subprocess, consuming
+the engine contract (contract_version "1.0") rather than reimplementing it.
+
+**How it works:**
+
+1. On `BeforeToolCallEvent`, if the tool name is a write-like tool, the gate
+   serialises the event to the canonical JSON payload and spawns:
+   `node run-hook.js config-protection config-protection.js`
+2. The engine exits 2 (block) or 0 (allow). Exit code 2 causes `event.cancel_tool`
+   to be set to the block reason from stderr.
+3. All other exit codes fail-open (do not block the agent).
+
+**Fallback when Node.js is unavailable:**
+
+If `node` is not on PATH or the engine script (`run-hook.js`) cannot be located,
+the gate degrades to a built-in Python implementation of the same logic and emits
+a `RuntimeWarning`. The pure-Python implementation mirrors `PROTECTED_FILES` from
+`config-protection.js` exactly. See §Limitations for the degradation contract.
+
+**Custom protected_files:** if you pass a custom `frozenset` to `PolicyGate`,
+Python evaluation is used directly (the engine subprocess cannot receive a
+runtime-custom set). This is intended for tests and local override only.
+
+On `BeforeToolCallEvent`, if the tool name is a write-like tool and the target
+file is in the protected set, `event.cancel_tool` is set to the block reason.
+Strands will cancel the call and surface the message as the tool result.
+
+---
+
+## Workflow steering
+
+The JS `workflow-steering.js` hook injects steering text by appending it to
+the prompt payload.  Strands' `BeforeInvocationEvent` does **not** expose a
+mutable system prompt at callback time.
+
+**Spike approach:** call `hooks.steering_context()` at Agent construction and
+append the result to the system prompt:
+
+```python
+hooks = FlowAgentsHooks(workspace=".")
+system_prompt = "You are a helpful agent.\n" + hooks.steering_context()
+agent = Agent(system_prompt=system_prompt, hooks=[hooks])
+```
+
+`steering_context()` also emits a `turn.user` telemetry event so the steering
+injection is recorded in the JSONL log.
+
+---
+
+## Quickstart
+
+```python
+from strands import Agent
+from strands.models import BedrockModel
+from flow_agents_strands import FlowAgentsHooks
+
+# Build hooks — no strands import needed for this step
+hooks = FlowAgentsHooks(
+    workspace=".",           # root of your project (reads .flow-agents/)
+    agent_name="my-agent",   # appears in telemetry events
+)
+
+# Load steering context BEFORE constructing the agent
+system_prompt = (
+    "You are a helpful assistant.\n"
+    + hooks.steering_context()   # appends workflow state reminders if any
+)
+
+# Wire hooks into the Agent
+model = BedrockModel(model_id="anthropic.claude-3-5-sonnet-20241022-v2:0")
+agent = Agent(model=model, system_prompt=system_prompt, hooks=[hooks])
+
+result = agent("List the files in this directory.")
+print(result)
+```
+
+Telemetry is written to `.flow-agents/.telemetry/full.jsonl`.
+
+---
+
+## Installation
+
+```bash
+# Without strands (for telemetry/policy use only, tests, etc.):
+pip install flow-agents-strands
+
+# With strands SDK:
+pip install "flow-agents-strands[strands]"
+```
+
+---
+
+## Running tests
+
+```bash
+cd integrations/strands
+python3 -m unittest discover
+```
+
+Tests use stdlib `unittest` only — no pytest, no strands-agents required.
+
+---
+
+## Limitations (honest spike notes)
+
+1. **Node.js subprocess dependency**: The primary policy binding spawns a Node.js
+   subprocess for each `BeforeToolCallEvent` that involves a write-like tool. If
+   `node` is not on PATH or the `@kontourai/flow-agents` package is not installed,
+   the gate degrades gracefully to the built-in Python fallback with a one-time
+   `RuntimeWarning`. The Python fallback uses the same `PROTECTED_FILES` constant
+   as the engine and is auditable. To force the subprocess path, set
+   `FLOW_AGENTS_ENGINE_PATH` to the absolute path of `run-hook.js`.
+
+2. **Steering seam**: Strands does not allow mutating the system prompt from
+   `BeforeInvocationEvent`.  The workaround (`steering_context()` at Agent
+   construction) is a one-shot snapshot; it does not re-evaluate on every turn
+   the way the JS hook does at `UserPromptSubmit`.  Productization would
+   require either a custom Strands model wrapper that injects context per-turn,
+   or upstream SDK support for mutable system-prompt context in the invocation
+   event.
+
+3. **session.usage event omitted**: The JS harness emits a `session.usage`
+   event on stop with token counts pulled from the transcript.  The Strands
+   `AfterInvocationEvent` does not (yet) expose token-usage data in the hook
+   payload, so this event is not emitted.  Productization would need to read
+   usage from the agent's response object and attach it here.
+
+4. **No analytics channel**: The harness adapters write to two channels
+   (full + analytics) with different redaction profiles.  This spike writes
+   only to the `full` channel.  Adding analytics is straightforward: a second
+   `TelemetrySink` instance pointed at `analytics.jsonl` with the analytics
+   redact list applied.
+
+5. **No Console/HTTP sink**: The bash transport supports POSTing events to a
+   Console endpoint.  This adapter writes JSONL only.  Adding HTTP transport
+   would mean replicating the `console_telemetry_emit()` logic in Python or
+   calling `transport.sh` as a subprocess.
+
+6. **Runtime version is "unknown"**: The harness adapters run
+   `<runtime> --version` to populate `agent.version`.  Strands does not
+   expose its version through the hook event; `importlib.metadata` could
+   provide the SDK version as a proxy.
+
+7. **No subagent / delegation event**: The Strands SDK does not have a
+   built-in InvokeSubagents tool; the delegation telemetry path is not wired.
+
+8. **Quality-gate policy omitted**: `quality-gate.js` invokes ruff/biome
+   after edits.  This is omitted from the spike because it requires executing
+   external formatters and has no clear Strands analogue yet.
+
+
+## What productization would require
+
+- Upstream Strands SDK support for mutable per-turn context injection.
+- Token-usage exposure in `AfterInvocationEvent` for `session.usage` events.
+- Dual-channel JSONL + optional HTTP transport mirroring the bash transport.
+- Packaging as a proper release with semantic versioning once the Strands hook
+  API stabilizes.
+- Integration tests against a live Strands agent (currently blocked by missing
+  AWS credentials in CI).

package/integrations/strands/example.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""
+example.py — Intended usage of FlowAgentsHooks with a real Strands Agent.
+
+Guarded by try/except ImportError so it degrades gracefully when
+strands-agents is not installed (e.g. in CI or unit-test environments).
+
+Run this only when:
+  1. strands-agents is installed: pip install "flow-agents-strands[strands]"
+  2. AWS credentials are configured for Bedrock (or swap to a different model)
+"""
+
+from flow_agents_strands import FlowAgentsHooks
+
+# Step 1: Build hooks — no strands import required
+hooks = FlowAgentsHooks(
+    workspace=".",           # root of your project (reads .flow-agents/)
+    agent_name="example-agent",
+)
+
+# Step 2: Load steering context at agent construction time.
+# This is the documented spike workaround for the system-prompt seam:
+# BeforeInvocationEvent does not expose a mutable system_prompt in Strands,
+# so we snapshot workflow state once and prepend it to the system prompt.
+# See README.md § Limitations for details.
+base_system_prompt = (
+    "You are a helpful assistant. "
+    "Follow the Flow Agents workflow discipline."
+)
+steering = hooks.steering_context()
+system_prompt = base_system_prompt + steering
+
+print("=== Flow Agents Strands Example ===")
+print(f"Steering context ({len(steering)} chars):")
+print(steering or "(none — no active workflow state found)")
+print()
+
+try:
+    from strands import Agent  # type: ignore[import]
+    from strands.models import BedrockModel  # type: ignore[import]
+
+    model = BedrockModel(
+        model_id="anthropic.claude-3-5-sonnet-20241022-v2:0",
+        region_name="us-east-1",
+    )
+
+    agent = Agent(
+        model=model,
+        system_prompt=system_prompt,
+        hooks=[hooks],
+    )
+
+    print("Agent created. Running a simple task...")
+    result = agent("List the Python files in the current directory.")
+    print("Result:", result)
+    print()
+    print("Telemetry written to .flow-agents/.telemetry/full.jsonl")
+
+except ImportError:
+    print(
+        "strands-agents is not installed.\n"
+        "Install it to run against a live agent:\n"
+        "  pip install 'flow-agents-strands[strands]'\n"
+        "\n"
+        "The hooks and telemetry modules work without strands-agents installed.\n"
+        "Run the unit tests with:\n"
+        "  python3 -m unittest discover"
+    )
+except Exception as exc:
+    print(f"Agent run failed (likely missing AWS credentials): {exc}")
+    print(
+        "\nThis example requires AWS credentials configured for Bedrock.\n"
+        "The hooks + telemetry code ran successfully up to the Agent() call."
+    )

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)