@kontourai/flow-agents 0.1.1 → 0.2.0

package/evals/static/test_universal_bundles.sh

@@ -57,7 +57,7 @@ fi
 
 echo ""
 echo "--- Bundle Layout ---"
-for dir in "$DIST_DIR/kiro" "$DIST_DIR/claude-code" "$DIST_DIR/codex"; do
+for dir in "$DIST_DIR/kiro" "$DIST_DIR/claude-code" "$DIST_DIR/codex" "$DIST_DIR/opencode" "$DIST_DIR/pi"; do
   if [[ -d "$dir" ]]; then
     _pass "$(basename "$dir") bundle exists"
   else
@@ -80,6 +80,8 @@ codex_agents=$(find "$DIST_DIR/codex/.codex/agents" -maxdepth 1 -name '*.toml' 2
 [[ "$kiro_agents" == "$source_agents" ]] && _pass "Kiro agent count matches source ($kiro_agents)" || _fail "Kiro agent count mismatch: source=$source_agents dist=$kiro_agents"
 [[ "$claude_agents" == "$source_agents" ]] && _pass "Claude agent count matches source ($claude_agents)" || _fail "Claude agent count mismatch: source=$source_agents dist=$claude_agents"
 [[ "$codex_agents" == "$expected_codex_agents" ]] && _pass "Codex agent count matches source minus manifest exclusions ($codex_agents)" || _fail "Codex agent count mismatch: expected=$expected_codex_agents dist=$codex_agents"
+opencode_agents=$(find "$DIST_DIR/opencode/.opencode/agents" -maxdepth 1 -name '*.md' 2>/dev/null | wc -l | tr -d ' ')
+[[ "$opencode_agents" == "$source_agents" ]] && _pass "opencode agent count matches source ($opencode_agents)" || _fail "opencode agent count mismatch: source=$source_agents dist=$opencode_agents"
 
 echo ""
 echo "--- Kiro JSON ---"
@@ -226,9 +228,142 @@ else
   _fail "Codex hooks missing telemetry/policy lifecycle coverage or CODEX_HOME root resolution"
 fi
 
+echo ""
+echo "--- opencode Export Shape ---"
+if node - "$DIST_DIR/opencode/.opencode/agents" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+const required = new Set(["description", "mode", "model"]);
+const validModes = new Set(["subagent", "primary", "all"]);
+for (const name of fs.readdirSync(process.argv[2]).filter((file) => file.endsWith(".md"))) {
+  const text = fs.readFileSync(path.join(process.argv[2], name), "utf8");
+  if (!text.startsWith("---\n")) throw new Error(`${name}: missing frontmatter start`);
+  const parts = text.split("\n---\n");
+  if (parts.length < 2) throw new Error(`${name}: missing frontmatter end`);
+  const fmLines = parts[0].replace("---\n", "").split(/\r?\n/).filter((line) => line.includes(":"));
+  const keys = new Set(fmLines.map((line) => line.split(":", 1)[0].trim()));
+  const missing = [...required].filter((key) => !keys.has(key));
+  if (missing.length) throw new Error(`${name}: missing frontmatter keys ${missing.join(", ")}`);
+  const modeMatch = fmLines.find((line) => line.trim().startsWith("mode:"));
+  if (modeMatch) {
+    const mode = modeMatch.split(":", 2)[1].trim();
+    if (!validModes.has(mode)) throw new Error(`${name}: invalid mode value: ${mode}`);
+  }
+  if (!parts.slice(1).join("\n---\n").trim()) throw new Error(`${name}: empty body`);
+}
+console.log("ok");
+NODE
+then
+  _pass "opencode agent markdown has valid YAML frontmatter with description, mode, model"
+else
+  _fail "opencode agent markdown frontmatter/shape check failed"
+fi
+
+if [[ -f "$DIST_DIR/opencode/.opencode/plugins/flow-agents.js" ]]; then
+  _pass "opencode bundle includes Flow Agents plugin"
+else
+  _fail "opencode bundle missing .opencode/plugins/flow-agents.js"
+fi
+
+if [[ -f "$DIST_DIR/opencode/opencode.json" ]]; then
+  if node - "$DIST_DIR/opencode/opencode.json" <<'NODE'
+const fs = require("node:fs");
+const data = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+if (!data || typeof data !== "object") throw new Error("opencode.json must be an object");
+// opencode's config schema rejects non-array `instructions` and aborts
+// startup (caught by live acceptance smoke 2026-06-11). Pin the constraint.
+if ("instructions" in data && !Array.isArray(data.instructions)) {
+  throw new Error("opencode.json instructions must be an array of file paths when present");
+}
+console.log("ok");
+NODE
+  then
+    _pass "opencode.json is valid JSON and schema-safe (instructions array-or-absent)"
+  else
+    _fail "opencode.json is invalid or violates opencode config schema"
+  fi
+else
+  _fail "opencode bundle missing opencode.json"
+fi
+
+# Generated hook artifacts must PARSE in their host language. The pi live
+# smoke (2026-06-11) caught the generator emitting an unterminated string
+# (template-literal escaping) that pi's loader rejected at startup.
+if node --check "$DIST_DIR/opencode/.opencode/plugins/flow-agents.js" 2>/dev/null; then
+  _pass "generated opencode plugin parses as JavaScript"
+else
+  _fail "generated opencode plugin has a JavaScript syntax error"
+fi
+
+# Semantic errors (TS2xxx: unresolved modules/types) are expected without the
+# host's node_modules; only syntax-class errors (TS1xxx) mean a broken artifact.
+PI_TS_SYNTAX_ERRORS=$(npx tsc --ignoreConfig --noEmit --noResolve --skipLibCheck --target esnext --module esnext \
+    "$DIST_DIR/pi/.pi/extensions/flow-agents.ts" 2>&1 | grep -c "error TS1" || true)
+if [[ "$PI_TS_SYNTAX_ERRORS" -eq 0 ]]; then
+  _pass "generated pi extension parses as TypeScript (no TS1xxx syntax errors)"
+else
+  _fail "generated pi extension has $PI_TS_SYNTAX_ERRORS TypeScript syntax errors"
+fi
+
+if [[ -d "$DIST_DIR/opencode/.opencode/skills" ]] && [[ $(find "$DIST_DIR/opencode/.opencode/skills" -name "SKILL.md" | wc -l | tr -d ' ') -gt 0 ]]; then
+  _pass "opencode bundle includes skills in .opencode/skills/"
+else
+  _fail "opencode bundle missing skills in .opencode/skills/"
+fi
+
+echo ""
+echo "--- pi Export Shape ---"
+if [[ -f "$DIST_DIR/pi/.pi/extensions/flow-agents.ts" ]]; then
+  _pass "pi bundle includes Flow Agents extension"
+else
+  _fail "pi bundle missing .pi/extensions/flow-agents.ts"
+fi
+
+if [[ -d "$DIST_DIR/pi/.pi/skills" ]] && [[ $(find "$DIST_DIR/pi/.pi/skills" -name "SKILL.md" | wc -l | tr -d ' ') -gt 0 ]]; then
+  _pass "pi bundle includes skills in .pi/skills/"
+else
+  _fail "pi bundle missing skills in .pi/skills/"
+fi
+
+if node - "$DIST_DIR/pi/.pi/extensions/flow-agents.ts" <<'NODE'
+const fs = require("node:fs");
+const text = fs.readFileSync(process.argv[2], "utf8");
+if (!text.includes("pi-hook-adapter.js")) throw new Error("pi extension does not reference pi-hook-adapter.js");
+if (!text.includes("pi-telemetry-hook.js")) throw new Error("pi extension does not reference pi-telemetry-hook.js");
+if (!text.includes("workflow-steering.js")) throw new Error("pi extension missing workflow-steering.js reference");
+if (!text.includes("config-protection.js")) throw new Error("pi extension missing config-protection.js reference");
+if (!text.includes("stop-goal-fit.js")) throw new Error("pi extension missing stop-goal-fit.js reference");
+if (!text.includes("before_agent_start")) throw new Error("pi extension missing before_agent_start event handler");
+if (!text.includes("tool_call")) throw new Error("pi extension missing tool_call event handler");
+console.log("ok");
+NODE
+then
+  _pass "pi extension references correct hook adapters and event handlers"
+else
+  _fail "pi extension is missing required hook adapter or event handler references"
+fi
+
+if node - "$DIST_DIR/opencode/.opencode/plugins/flow-agents.js" <<'NODE'
+const fs = require("node:fs");
+const text = fs.readFileSync(process.argv[2], "utf8");
+if (!text.includes("opencode-hook-adapter.js")) throw new Error("opencode plugin does not reference opencode-hook-adapter.js");
+if (!text.includes("opencode-telemetry-hook.js")) throw new Error("opencode plugin does not reference opencode-telemetry-hook.js");
+if (!text.includes("workflow-steering.js")) throw new Error("opencode plugin missing workflow-steering.js reference");
+if (!text.includes("config-protection.js")) throw new Error("opencode plugin missing config-protection.js reference");
+if (!text.includes("stop-goal-fit.js")) throw new Error("opencode plugin missing stop-goal-fit.js reference");
+if (!text.includes("session.created")) throw new Error("opencode plugin missing session.created event handler");
+if (!text.includes("tool.execute.before")) throw new Error("opencode plugin missing tool.execute.before event handler");
+console.log("ok");
+NODE
+then
+  _pass "opencode plugin references correct hook adapters and event handlers"
+else
+  _fail "opencode plugin is missing required hook adapter or event handler references"
+fi
+
 echo ""
 echo "--- Shared Task Dirs ---"
-for dir in "$DIST_DIR/claude-code/.flow-agents" "$DIST_DIR/codex/.flow-agents"; do
+for dir in "$DIST_DIR/claude-code/.flow-agents" "$DIST_DIR/codex/.flow-agents" "$DIST_DIR/opencode/.flow-agents" "$DIST_DIR/pi/.flow-agents"; do
   if [[ -d "$dir" ]]; then
     _pass "$(realpath "$dir" 2>/dev/null || echo "$dir") exists"
   else

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"