@kontourai/flow-agents 0.1.2 → 0.2.0

package/docs/integrations/conformance.md

@@ -0,0 +1,246 @@
+---
+title: Conformance
+---
+
+# Conformance
+
+This page explains how a third-party adapter self-certifies against the Flow Agents policy engine contract. It covers the engine contract version 1.0, how to run the conformance kit, what each conformance level requires, and how to declare gaps using the opencode and pi built-in examples as the pattern.
+
+Everything in this page is grounded in `packaging/conformance/` and `docs/spec/runtime-hook-surface.md`. No behavior is inferred.
+
+## Engine contract 1.0
+
+The engine contract is the versioned public interface between Flow Agents policy scripts and adapters. Third-party adapters bind to this contract. Breaking changes will increment the major version and be announced via CHANGELOG.
+
+The contract is defined in <a href="../spec/runtime-hook-surface.html">the spec, section 8</a>. In summary:
+
+**Invocation — subprocess form** (standard, used by all current adapters):
+
+```bash
+echo '<JSON payload>' | node scripts/hooks/run-hook.js <hookId> <scriptRelativePath> [profilesCsv]
+```
+
+- `hookId`: identifier for the hook (e.g., `config-protection`). Used for profile/disable checks.
+- `scriptRelativePath`: path relative to `scripts/hooks/` (e.g., `config-protection.js`).
+- `profilesCsv`: comma-separated profile names. Hooks not in the current `SA_HOOK_PROFILE` are skipped.
+- Payload is read from stdin. Max 1 MiB. If truncated, `SA_HOOK_INPUT_TRUNCATED=1` is set.
+
+**Invocation — native import form** (for Node.js adapters, preferred for performance):
+
+```javascript
+const { run } = require('./scripts/hooks/config-protection.js');
+const output = run(rawJsonString, { truncated: false, maxStdin: 1024 * 1024 });
+```
+
+All four policy scripts export `module.exports = { run }`.
+
+**Version query:**
+
+```bash
+node scripts/hooks/run-hook.js --contract-version
+# → {"contract_version":"1.0","runner":"run-hook.js"}
+```
+
+**Exit code semantics:**
+
+| Exit code | Semantics |
+| --- | --- |
+| `0` | Allow — policy has no objection |
+| `2` | Block — policy vetoes the action |
+| other | Error — treat as allow (fail-open) |
+
+**Fail-open rule**: Hook runtime errors must never block agent work. Every policy except `config-protection` exits 0 always on non-policy errors. `config-protection` exits 2 only on a protected file match or a truncated payload; runtime errors exit 0.
+
+## What each conformance level requires
+
+Conformance levels are defined in <a href="../spec/runtime-hook-surface.html">the spec, section 4</a>.
+
+### L0: Telemetry only
+
+The adapter wires the telemetry script to at least one lifecycle event. No policy hooks are required.
+
+**Required:** At minimum, `agentSpawn` telemetry fires on session start.
+
+**Permitted gaps:** All four policy classes (workflow steering, quality gate, stop-goal-fit, config protection) may be absent.
+
+**Use case:** Framework adapters and runtimes where the telemetry signal is valuable but blocking or context injection is not feasible.
+
+### L1: Steering
+
+The adapter implements L0 plus workflow steering and stop-goal-fit in warning mode.
+
+**Required:**
+- L0 telemetry.
+- Workflow steering fires on `userPromptSubmit` (or the closest equivalent — document which event is used and any fidelity loss).
+- Stop-goal-fit fires on `stop` in warning-only mode (exits 0 always).
+
+**Permitted gaps:** Quality gate and config protection may be absent. Stop-goal-fit runs in warning mode only.
+
+**Use case:** Harness adapters where the runtime supports prompt-submit and stop hooks, but tool-level blocking is not available or desired.
+
+### L2: Enforcing gates
+
+The adapter implements L1 plus all blocking policy classes.
+
+**Required:**
+- L1 steering and stop telemetry.
+- Config protection fires on `preToolUse` and can block (exit 2 translates to a deny response).
+- Quality gate fires on `postToolUse`.
+- Stop-goal-fit fires on `stop` with `FLOW_AGENTS_GOAL_FIT_STRICT` configurable.
+
+**Permitted gaps:** None. All four policy classes must be wired. Any missing host trigger must be documented as a named gap in the conformance declaration.
+
+**Use case:** Claude Code and Codex are L2 reference implementations.
+
+## Running the conformance kit
+
+The conformance kit is in `packaging/conformance/`. It requires no npm dependencies — only Node.js.
+
+**Self-test the canonical engine (must report L2):**
+
+```bash
+node packaging/conformance/run-conformance.js --self
+```
+
+**Test a third-party adapter at L2:**
+
+```bash
+node packaging/conformance/run-conformance.js \
+  --adapter-cmd "node /path/to/your-adapter.js" \
+  --level L2
+```
+
+**Test at L1 only:**
+
+```bash
+node packaging/conformance/run-conformance.js \
+  --adapter-cmd "node /path/to/your-adapter.js" \
+  --level L1
+```
+
+**CLI reference:**
+
+```
+node packaging/conformance/run-conformance.js [options]
+
+  --self              Run against the canonical engine (target L2)
+  --adapter-cmd CMD   Shell command to pipe fixtures to (adapter under test)
+  --level L0|L1|L2    Minimum conformance level to enforce (default: L2 for --self, L0 for --adapter-cmd)
+  --fixtures DIR      Override fixture directory (default: packaging/conformance/fixtures/)
+  --verbose           Print fixture payloads and full output in per-fixture results
+```
+
+Exit codes: `0` = target level reached, `1` = target level not reached, `2` = usage error.
+
+### Adapter contract for the runner
+
+Your adapter command:
+- Receives a canonical JSON payload on stdin (one JSON object).
+- Writes the input JSON (or augmented form) to stdout on allow.
+- Exits `0` to allow, `2` to block, any other code for error (treated as allow, fail-open).
+
+The runner invokes your command exactly once per fixture via `sh -c "<your-cmd>"`.
+
+### Fixture inventory
+
+The fixtures in `packaging/conformance/fixtures/` cover all four policy classes:
+
+| Fixture | Policy class | Event | Level |
+| --- | --- | --- | --- |
+| `config-protection--block-eslintrc.json` | config-protection | preToolUse | L2 |
+| `config-protection--block-biome.json` | config-protection | preToolUse | L2 |
+| `config-protection--allow-safe-file.json` | config-protection | preToolUse | L2 |
+| `config-protection--allow-no-path.json` | config-protection | preToolUse | L2 |
+| `quality-gate--allow-nonexistent-file.json` | quality-gate | postToolUse | L2 |
+| `quality-gate--allow-no-path.json` | quality-gate | postToolUse | L2 |
+| `stop-goal-fit--allow-clean-cwd.json` | stop-goal-fit | stop | L1 |
+| `stop-goal-fit--warn-active-delivery.json` | stop-goal-fit | stop | L1 |
+| `stop-goal-fit--block-strict-mode.json` | stop-goal-fit | stop | L2 |
+| `workflow-steering--allow-no-state.json` | workflow-steering | userPromptSubmit | L1 |
+| `workflow-steering--inject-active-state.json` | workflow-steering | userPromptSubmit | L1 |
+| `workflow-steering--inject-subagent-steering.json` | workflow-steering | postToolUse | L1 |
+
+Fixtures with `workspace_setup` create a temporary directory with the listed files before invoking the adapter and clean up afterward. The `cwd` field in those payloads is replaced with the temp directory path at runtime.
+
+## How to declare gaps
+
+If your adapter legitimately cannot satisfy a fixture — because the host runtime has no blocking `preToolUse` equivalent, or no stop hook — declare the gap explicitly in your adapter documentation. The opencode and pi adapters are the reference pattern.
+
+### opencode: no prompt-submit hook
+
+opencode has no native `prompt.submit`-equivalent event. Workflow steering cannot fire at each user turn. The gap is declared in the plugin source comment and in the conformance declaration:
+
+```yaml
+conformance_level: L1
+host: opencode
+event_coverage:
+  agentSpawn: session.created (full fidelity)
+  userPromptSubmit: no native equivalent — workflow steering fires at session.created only
+  preToolUse: tool.execute.before (full fidelity, blocking available via thrown Error)
+  postToolUse: tool.execute.after (full fidelity)
+  stop: session.idle (reduced fidelity — fires on idle, not on completion)
+  permissionRequest: permission.asked (telemetry only — no blocking capability)
+policy_coverage:
+  workflow_steering: partial — injected at session.created only, not at each turn
+  quality_gate: wired at tool.execute.after
+  stop_goal_fit: degraded — session.idle does not reliably fire at completion
+  config_protection: wired at tool.execute.before (blocking)
+gaps:
+  - event: userPromptSubmit
+    reason: opencode has no prompt.submit equivalent
+    degradation: Workflow steering fires once at session.created instead of at each user turn
+  - event: stop
+    reason: session.idle is the closest event but is not a true completion signal
+    degradation: stop-goal-fit warnings may not fire reliably at session end
+```
+
+### pi: no stop hook
+
+pi has no stop hook. Stop-goal-fit cannot fire at session end. The gap is declared in the extension source comment and in the conformance declaration:
+
+```yaml
+conformance_level: L1
+host: pi
+event_coverage:
+  agentSpawn: session_start (full fidelity)
+  userPromptSubmit: before_agent_start (reduced fidelity — fires at agent start, not per-turn)
+  preToolUse: tool_call (full fidelity, blockable via return { block: true })
+  postToolUse: tool_result (full fidelity)
+  stop: no native equivalent — session_shutdown used as closest analogue
+policy_coverage:
+  workflow_steering: partial — injected at before_agent_start, not at each user turn
+  quality_gate: wired at tool_result
+  stop_goal_fit: degraded — session_shutdown does not reliably carry stop semantics
+  config_protection: wired at tool_call (blocking)
+gaps:
+  - event: stop
+    reason: pi has no stop hook
+    degradation: stop-goal-fit cannot fire; agent may complete without the check
+    workaround: Run stop-goal-fit checks explicitly in CI or via a post-session script
+```
+
+## Including a conformance declaration in your adapter
+
+After running the conformance kit, include a declaration in your adapter documentation:
+
+```yaml
+conformance_level: L2          # or L0 / L1
+engine_contract_version: "1.0"
+runner_version: "run-conformance.js"
+test_date: 2026-06-11
+verdict: PASS
+fixture_count: 12
+fixtures_passed: 12
+gaps: []
+```
+
+If any fixtures fail, list them under `gaps` with a description of the degradation behavior. Declared gaps do not prevent reaching a lower conformance level — they make the adapter's behavior honest and auditable.
+
+## Related references
+
+- `packaging/conformance/run-conformance.js` — conformance runner
+- `packaging/conformance/fixtures/` — golden fixtures
+- `packaging/conformance/README.md` — conformance kit README
+- <a href="../spec/runtime-hook-surface.html">Runtime Hook Surface spec §8</a> — engine contract 1.0 in full
+- <a href="harness-install.html">Harness Install</a> — worked install examples for opencode and pi
+- <a href="framework-adapter.html">Framework Adapter</a> — worked example of a language-native adapter

package/docs/integrations/framework-adapter.md

@@ -0,0 +1,275 @@
+---
+title: Framework Adapter
+---
+
+# Framework Adapter
+
+This page walks through the `integrations/strands/` reference implementation: a Python `HookProvider` for AWS Strands Agents. It covers how to construct `FlowAgentsHooks`, what telemetry it emits, how the policy gate binds to the canonical engine contract, and the documented limitations of this spike.
+
+Everything in this page is grounded in the files under `integrations/strands/`. No behavior is inferred or aspirational unless explicitly labeled as direction.
+
+## Harness adapters vs. framework adapters
+
+Harness adapters (Claude Code, Codex, Kiro, opencode, pi) integrate with coding-agent runtimes that have their own hook format: JSON on stdin, exit codes, and lifecycle events named by the harness. Each harness adapter normalizes its runtime's hook payloads into the canonical Flow Agents telemetry taxonomy and delegates to `scripts/telemetry/telemetry.sh`.
+
+Framework adapters are in-process packages. 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. There is no stdin/stdout protocol and no process exit codes as block signals. Hook callbacks receive typed Python event objects and can mutate them in place.
+
+Despite the 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`.
+
+## Constructing FlowAgentsHooks
+
+`FlowAgentsHooks` is the main entry point. It implements the Strands `HookProvider` protocol via duck typing, so `strands-agents` is not required at import time.
+
+```python
+from flow_agents_strands import FlowAgentsHooks
+
+hooks = FlowAgentsHooks(
+    workspace=".",           # root of your project (reads .flow-agents/)
+    agent_name="my-agent",   # appears in telemetry events
+)
+```
+
+Constructor parameters (all optional):
+
+| Parameter | Default | Purpose |
+| --- | --- | --- |
+| `sink_path` | `<workspace>/.flow-agents/.telemetry/full.jsonl` | JSONL telemetry output path or directory |
+| `workspace` | `os.getcwd()` | Root of the workspace; used to discover `.flow-agents/` |
+| `agent_name` | `"strands-agent"` | Agent identifier embedded in telemetry events |
+| `runtime` | `"strands"` | Runtime label embedded in telemetry events |
+| `policy_gate` | `PolicyGate()` | Optional custom `PolicyGate` instance (for testing) |
+
+`FlowAgentsHooks` is usable without `strands-agents` installed. Telemetry emission and `steering_context()` work in any Python environment. The `register_hooks` method (which wires callbacks into a `HookRegistry`) requires `strands-agents` and raises `ImportError` if the SDK is absent.
+
+## Wiring into an Agent
+
+```python
+from strands import Agent
+from strands.models import BedrockModel
+from flow_agents_strands import FlowAgentsHooks
+
+hooks = FlowAgentsHooks(workspace=".")
+
+# Load steering context BEFORE constructing the agent.
+# Strands' BeforeInvocationEvent does not expose a mutable system prompt,
+# so steering must be injected at construction time.
+system_prompt = (
+    "You are a helpful assistant.\n"
+    + hooks.steering_context()
+)
+
+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.")
+```
+
+`register_hooks` is called by the Strands runtime when `hooks=[hooks]` is passed to `Agent`. It registers five callbacks:
+
+| Strands event | Canonical event | What fires |
+| --- | --- | --- |
+| `AgentInitializedEvent` | `agentSpawn` | `emit_session_start()` — records `session.start` |
+| `BeforeInvocationEvent` | `userPromptSubmit` | `emit("userPromptSubmit")` — records `turn.user` |
+| `AfterInvocationEvent` | `stop` | `emit_session_end(duration_s=…)` — records `session.end` |
+| `BeforeToolCallEvent` | `preToolUse` | Telemetry + policy gate (config-protection) |
+| `AfterToolCallEvent` | `postToolUse` | `emit_tool_result(…)` — records `tool.result` |
+
+This mapping is the `STRANDS_TO_CANONICAL` dict exposed at module level by `integrations/strands/flow_agents_strands/telemetry.py`:
+
+```python
+STRANDS_TO_CANONICAL = {
+    "AgentInitializedEvent":  "agentSpawn",
+    "BeforeInvocationEvent":  "userPromptSubmit",
+    "AfterInvocationEvent":   "stop",
+    "BeforeToolCallEvent":    "preToolUse",
+    "AfterToolCallEvent":     "postToolUse",
+    "AfterModelCallEvent":    "postToolUse",   # closest analogue; no tool name
+    "MessageAddedEvent":      "userPromptSubmit",
+}
+```
+
+## Telemetry emitted
+
+Events are written to `.flow-agents/.telemetry/full.jsonl` by default. The record shape matches `build_base_event()` in `scripts/telemetry/telemetry.sh`:
+
+```json
+{
+  "schema_version": "0.3.0",
+  "timestamp": "1718000000000",
+  "session_id": "<uuid>",
+  "event_id": "<uuid>",
+  "event_type": "tool.invoke",
+  "agent": { "name": "my-agent", "runtime": "strands", "version": "unknown" },
+  "hook": {
+    "event_name": "preToolUse",
+    "source": "strands",
+    "stop_hook_active": null,
+    "raw_input": null
+  },
+  "tool": { "name": "edit", "normalized_name": "fs_write", "input": { ... } }
+}
+```
+
+Canonical names map to schema `event_type` values via `_CANONICAL_TO_SCHEMA` in `telemetry.py`:
+
+| 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 is always fail-open: if the JSONL file cannot be written (`OSError`), the exception is swallowed silently. Telemetry must never block agent work.
+
+## Policy gate: config-protection
+
+The config-protection policy binds to the canonical Node.js engine via subprocess. The binding is in `integrations/strands/flow_agents_strands/policy.py` in the `PolicyGate` class.
+
+**Primary mode — engine subprocess:**
+
+On `BeforeToolCallEvent`, if the tool name is a write-like tool (one of `edit`, `write`, `fs_write`, `apply_patch`, `create_file`, `str_replace_editor`), the gate serializes the event to a canonical JSON payload and spawns:
+
+```bash
+echo '{"hook_event_name":"PreToolUse","tool_name":"edit","tool_input":{"path":"biome.json"}}' \
+  | node scripts/hooks/run-hook.js config-protection config-protection.js
+```
+
+The engine exits 2 (block) or 0 (allow). Exit code 2 causes `event.cancel_tool` to be set to the block reason from stderr. Strands cancels the call and surfaces the message as the tool result. All other exit codes fail open.
+
+The engine is located by `_find_engine_paths()` in this priority order:
+
+1. `FLOW_AGENTS_ENGINE_PATH` environment variable (explicit override).
+2. Relative to the package source file: `../../../../scripts/hooks/run-hook.js` (works from a repo checkout).
+3. Walked up from `os.getcwd()` looking for `node_modules/@kontourai/flow-agents/scripts/hooks/run-hook.js` (npm-installed package).
+
+**Fallback mode — Python evaluation:**
+
+If `node` is not on PATH or `run-hook.js` cannot be located, the gate degrades to a built-in Python implementation of the same logic and emits a one-time `RuntimeWarning`. The Python fallback uses the same `PROTECTED_FILES` frozenset as `config-protection.js` and is auditable. This is not silent: the warning is printed once to stderr.
+
+**Custom protected set:**
+
+If a `PolicyGate` is constructed with a custom `protected_files` frozenset, Python evaluation is used directly (the engine subprocess cannot receive a runtime-custom set). This path is intended for tests and local override only.
+
+## Workflow steering
+
+Strands' `BeforeInvocationEvent` does not expose a mutable system prompt at callback time.
+
+The spike approach: call `hooks.steering_context()` at `Agent` construction time and append the result to the system prompt. `steering_context()` reads the current workflow state from `.flow-agents/` and returns a text block. It also emits a `turn.user` telemetry event so the injection is recorded in the JSONL log.
+
+This is a one-shot snapshot. It does not re-evaluate on every turn the way `workflow-steering.js` does at `UserPromptSubmit`. See the Limitations section for the productization path.
+
+## Documented limitations
+
+The following limitations are from `integrations/strands/README.md` and reflect the current spike state. They are not defects to be worked around silently — they are honest gaps.
+
+1. **Node.js subprocess dependency**: The primary policy binding spawns a Node.js subprocess for each `BeforeToolCallEvent` involving a write-like tool. If `node` is not on PATH or the package is not installed, the gate degrades to the Python fallback with a one-time `RuntimeWarning`. 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. 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. The Strands `AfterInvocationEvent` does not expose token-usage data in the hook payload, so this event is not emitted.
+
+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.
+
+5. **No Console/HTTP sink**: The bash transport supports POSTing events to a Console endpoint. This adapter writes JSONL only.
+
+6. **Runtime version is "unknown"**: Strands does not expose its version through the hook event; `agent.version` is hardcoded to `"unknown"`.
+
+7. **No subagent/delegation event**: The Strands SDK does not have a built-in delegation tool; the `subagentStart`/`subagentStop` telemetry path is not wired.
+
+8. **Quality-gate policy omitted**: `quality-gate.js` invokes ruff/biome after edits. There is no clear Strands analogue yet.
+
+## Conformance declaration
+
+The Strands adapter is L0 plus config protection via `BeforeToolCallEvent` cancellation. A full conformance declaration would read:
+
+```
+conformance_level: L0  (+ config-protection via BeforeToolCallEvent)
+host: AWS Strands Agents
+event_coverage:
+  agentSpawn: AgentInitializedEvent (full fidelity)
+  userPromptSubmit: BeforeInvocationEvent (no per-turn injection — spike limitation)
+  preToolUse: BeforeToolCallEvent (full fidelity, cancellable)
+  postToolUse: AfterToolCallEvent (full fidelity)
+  stop: AfterInvocationEvent (full fidelity)
+  permissionRequest: no native equivalent
+  subagentStart: no native equivalent
+  subagentStop: no native equivalent
+policy_coverage:
+  workflow_steering: partial — injected once at Agent construction, not per-turn
+  quality_gate: omitted — no current Strands analogue
+  stop_goal_fit: omitted — AfterInvocationEvent used for telemetry only
+  config_protection: wired at BeforeToolCallEvent (blocking via event.cancel_tool)
+```
+
+## Running tests
+
+The spike ships 50 unit tests that require no Strands SDK:
+
+```bash
+cd integrations/strands
+python3 -m unittest discover
+```
+
+## Related references
+
+- `integrations/strands/flow_agents_strands/hooks.py` — `FlowAgentsHooks` and `register_hooks`
+- `integrations/strands/flow_agents_strands/telemetry.py` — `TelemetrySink`, `STRANDS_TO_CANONICAL`
+- `integrations/strands/flow_agents_strands/policy.py` — `PolicyGate`, engine subprocess binding
+- `integrations/strands/flow_agents_strands/steering.py` — `SteeringContext`
+- `integrations/strands/README.md` — spike README with quickstart and full limitations list
+- <a href="../spec/runtime-hook-surface.html">Runtime Hook Surface spec §6.2</a> — framework adapter contract and minimum viable adapter pseudocode
+- <a href="conformance.html">Conformance</a> — how to self-certify using the conformance kit
+
+---
+
+## TypeScript native-import adapter (`integrations/strands-ts/`)
+
+`@kontourai/flow-agents-strands` is the first **native-import** consumer of the policy engine contract. Where the Python adapter spawns a subprocess for each `BeforeToolCallEvent` policy check, the TS adapter calls `config-protection.js`'s exported `run()` function directly — zero subprocess overhead on the hot path.
+
+### Key differences from the Python adapter
+
+| | Python adapter | TypeScript adapter |
+|--|----------------|-------------------|
+| Engine binding | subprocess (`node run-hook.js …`) | `require("config-protection.js").run()` — in-process |
+| Strands SDK | `register_hooks(registry)` → `registry.add_callback` | `registerHooks(registry)` → `registry.addCallback` |
+| Cancel signal | `event.cancel_tool = reason` | `event.cancel = reason` (TS variant) |
+| Conformance | L0 + config-protection | L2 (all four policy classes via shim) |
+| Test framework | stdlib unittest (Python) | node:test (no extra deps) |
+
+### Constructing FlowAgentsHooks (TypeScript)
+
+```typescript
+import { FlowAgentsHooks } from "@kontourai/flow-agents-strands";
+
+const hooks = new FlowAgentsHooks({
+  workspace: ".",        // root of your project
+  agentName: "my-agent",
+  // engineRoot: "/path/to/flow-agents"  // optional: explicit engine path
+});
+```
+
+### Event mapping
+
+The TS adapter exports `STRANDS_TO_CANONICAL` matching the Python adapter's dict:
+
+| Strands TS Event | Canonical event |
+|------------------|-----------------|
+| `BeforeInvocationEvent` | `userPromptSubmit` |
+| `AfterInvocationEvent` | `stop` |
+| `BeforeToolCallEvent` | `preToolUse` |
+| `AfterToolCallEvent` | `postToolUse` |
+| `AgentInitializedEvent` | `agentSpawn` |
+
+### Conformance
+
+The TS adapter achieves **L2** via `bin/conformance-shim.mjs`:
+
+```bash
+node packaging/conformance/run-conformance.js \
+  --adapter-cmd "node integrations/strands-ts/bin/conformance-shim.mjs" \
+  --level L2
+```
+
+12/12 fixtures pass. See `integrations/strands-ts/README.md` for the full conformance declaration and limitations.