@kontourai/flow-agents 0.1.1 → 0.2.0

package/integrations/strands/flow_agents_strands/steering.py

@@ -0,0 +1,172 @@
+"""
+steering.py — Workflow-steering context loader.
+
+Mirrors the logic in scripts/hooks/workflow-steering.js for reading
+.flow-agents/*/state.json and producing a steering text blob.
+
+Unlike the JS version this module does NOT inject into a prompt directly —
+Strands' BeforeInvocationEvent does not expose a mutable system_prompt at
+callback time.  Instead, the caller is expected to call
+FlowAgentsHooks.steering_context() at Agent construction and prepend the
+result to the system prompt.  See README.md § Limitations for details.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+# Active statuses that warrant surfacing steering context (mirrors workflow-steering.js)
+_ACTIVE_STATUSES = frozenset(
+    [
+        "new",
+        "planning",
+        "planned",
+        "in_progress",
+        "blocked",
+        "verifying",
+        "verified",
+        "needs_decision",
+        "not_verified",
+        "failed",
+        "delivered",
+    ]
+)
+
+_AMBIENT_STATUSES = frozenset(["blocked", "failed", "needs_decision", "not_verified"])
+
+
+def _find_repo_root(start: Optional[str] = None) -> Path:
+    """Walk up from start until .git or AGENTS.md is found."""
+    current = Path(start).resolve() if start else Path.cwd()
+    for _ in range(40):
+        if (current / ".git").exists() or (current / "AGENTS.md").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+    return Path(start).resolve() if start else Path.cwd()
+
+
+def _walk_state_files(flow_agents_dir: Path) -> List[Path]:
+    """Recursively find all state.json files, skipping archive/ dirs."""
+    results: List[Path] = []
+    if not flow_agents_dir.exists():
+        return results
+    for entry in flow_agents_dir.rglob("state.json"):
+        if "archive" in entry.parts:
+            continue
+        results.append(entry)
+    return results
+
+
+def _read_json(path: Path) -> Optional[Dict[str, Any]]:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def _safe_text(value: Any, max_length: int = 240) -> str:
+    text = " ".join(str(value or "").split()).strip()
+    if len(text) <= max_length:
+        return text
+    return text[: max_length - 3] + "..."
+
+
+class SteeringContext:
+    """
+    Loads Flow Agents workflow-steering context from .flow-agents/ state files.
+    """
+
+    def __init__(self, workspace: Optional[str] = None) -> None:
+        self._root = _find_repo_root(workspace)
+        self._flow_agents_dir = self._root / ".flow-agents"
+
+    def load(self) -> str:
+        """
+        Return a steering text string (possibly empty) for the current
+        workflow state.  Mirrors the stateSteering() + contextMapSteering()
+        output from workflow-steering.js.
+        """
+        parts: List[str] = []
+
+        state_hint = self._state_steering()
+        if state_hint:
+            parts.append(state_hint)
+
+        ctx_hint = self._context_map_steering()
+        if ctx_hint:
+            parts.append(ctx_hint)
+
+        if not parts:
+            return ""
+
+        return "\n\n---\n" + "\n".join(parts) + "\n---"
+
+    def _latest_active_state(self) -> Optional[Dict[str, Any]]:
+        candidates = []
+        for path in _walk_state_files(self._flow_agents_dir):
+            payload = _read_json(path)
+            if not payload:
+                continue
+            if payload.get("status") not in _ACTIVE_STATUSES:
+                continue
+            try:
+                mtime = path.stat().st_mtime_ns
+            except OSError:
+                continue
+            candidates.append((mtime, path, payload))
+
+        if not candidates:
+            return None
+        candidates.sort(key=lambda t: t[0], reverse=True)
+        _, path, payload = candidates[0]
+        return {"file": str(path), "payload": payload}
+
+    def _state_steering(self) -> str:
+        current = self._latest_active_state()
+        if not current:
+            return ""
+        state = current["payload"]
+        next_action = state.get("next_action") or {}
+
+        if next_action.get("status") == "done":
+            return ""
+        if state.get("status") in ("archived", "accepted"):
+            return ""
+
+        task_slug = state.get("task_slug") or Path(current["file"]).parent.name
+        parts = [
+            f"STATE: {task_slug} is status:{state.get('status')} phase:{state.get('phase')}."
+        ]
+        if next_action.get("summary"):
+            parts.append(
+                f"Recorded next_action.summary: \"{_safe_text(next_action['summary'])}\""
+            )
+        if next_action.get("target_phase"):
+            parts.append(f"Target phase: {_safe_text(next_action['target_phase'], 80)}.")
+        if (
+            next_action.get("status") == "needs_user"
+            or state.get("status") in ("needs_decision", "not_verified")
+        ):
+            parts.append(
+                "Do not deliver as complete until the user decision or accepted gap is recorded."
+            )
+        if state.get("status") == "failed":
+            parts.append("Route back through execution, then re-review and re-verify.")
+
+        return " ".join(parts)
+
+    def _context_map_steering(self) -> str:
+        map_path = self._root / "docs" / "context-map.md"
+        if not map_path.exists():
+            return ""
+        return (
+            "CONTEXT MAP: use docs/context-map.md before broad repo rediscovery. "
+            "If structure, commands, schemas, skills, agents, or packs changed, "
+            "run `npm run context-map -- --check`."
+        )

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*"]