@kontourai/flow-agents 0.2.0 → 0.4.0

package/docs/integrations/knowledge-kit-live.md

@@ -0,0 +1,211 @@
+---
+title: Knowledge Kit Live Example
+---
+
+# Knowledge Kit Live Example
+
+This page documents `integrations/strands/examples/knowledge_kit_live.py`: a keyless, ollama-backed end-to-end proof of the Knowledge Kit's ingest and compile flows running against a real Strands agent.
+
+Everything on this page is grounded in the source files and in the acceptance test that was run to validate the commands. Limitations are documented honestly.
+
+## What it proves
+
+The example exercises the full `knowledge.ingest` → `knowledge.compile` pipeline in a temporary workspace:
+
+- Two raw records are created programmatically via direct Node.js subprocess calls to the kit's flow-runner (`kits/knowledge/adapters/flow-runner/index.js`).
+- One raw record is created by the Strands agent calling the `capture_knowledge` tool.
+- The Strands agent calls `compile_knowledge` with all three raw record IDs, producing a compiled record with verified provenance links.
+
+Two telemetry streams are asserted:
+
+| Stream | Path | Contents |
+| --- | --- | --- |
+| Kit gate telemetry | `<workspace>/.telemetry/full.jsonl` | `tool.invoke` + `tool.result` per ingest/compile gate point |
+| Session telemetry | `<workspace>/.flow-agents/.telemetry/full.jsonl` | `session.start`, `turn.user`, `tool.invoke`, `tool.result`, `session.end` from FlowAgentsHooks |
+
+## Prerequisites
+
+- ollama installed and `qwen3:1.7b` pulled:
+
+  ```bash
+  ollama pull qwen3:1.7b
+  ```
+
+- Python venv with `strands-agents[ollama]` at `/tmp/strands-py-live/venv`:
+
+  ```bash
+  python3 -m venv /tmp/strands-py-live/venv
+  /tmp/strands-py-live/venv/bin/pip install 'strands-agents[ollama]'
+  ```
+
+- Node.js on PATH (for the kit's ESM flow-runner and bridge script).
+
+## Running the example
+
+```bash
+# From the repo root:
+ollama serve &
+FLOW_AGENTS_ROOT=$(pwd) \
+  /tmp/strands-py-live/venv/bin/python3 \
+  integrations/strands/examples/knowledge_kit_live.py
+```
+
+Expected output (session IDs and UUIDs vary):
+
+```
+=== Knowledge Kit S5: Keyless Live Example ===
+Repo root: /path/to/flow-agents
+
+Node.js: v24.16.0
+Workspace: /tmp/knowledge-kit-live-xxxxxxxx
+Corpus: 3 doc snippets
+  docs/integrations/framework-adapter.md (engineering.docs)
+  docs/integrations/index.md (engineering.docs)
+  kits/knowledge/docs/README.md (research.notes)
+
+--- Step 1: Programmatic captures (2 records) ---
+  docs/integrations/framework-adapter.md → <raw-id-1>
+  docs/integrations/index.md → <raw-id-2>
+
+--- Step 2: Agent-driven capture ---
+  Agent turn: 2.9s
+  Reply snippet: 'The captured knowledge record has been successfully stored with ID: ...'
+  Raw records in store: 3
+
+--- Step 3: Agent-driven compile ---
+  Agent turn: 4.3s
+  Reply snippet: 'The compiled knowledge record has been successfully created with ID: ...'
+  Compiled records in store: 1
+
+--- Provenance verification ---
+  Compiled record: <compiled-id>
+  Source IDs present in provenance: True
+  Source links in graph index: 3
+
+Kit gate telemetry (.telemetry/full.jsonl): 18 events
+  [tool.invoke] knowledge.ingest.classify-gate
+  [tool.result] knowledge.ingest.classify-gate
+  ...
+  [tool.invoke] knowledge.compile.link-gate
+  [tool.result] knowledge.compile.link-gate
+
+Session telemetry (.flow-agents/.telemetry/full.jsonl): 9 events
+  [session.start]
+  [turn.user]
+  [tool.invoke] (capture_knowledge)
+  [tool.result] (capture_knowledge)
+  [session.end]
+  [turn.user]
+  [tool.invoke] (compile_knowledge)
+  [tool.result] (compile_knowledge)
+  [session.end]
+
+--- Summary ---
+Kit event types:     ['tool.invoke', 'tool.result']
+Session event types: ['session.end', 'session.start', 'tool.invoke', 'tool.result', 'turn.user']
+Raw records:         3
+Compiled records:    1
+Provenance ok:       True
+
+Overall: PASS
+```
+
+## Running the acceptance test
+
+The acceptance harness gates on ollama binary, model presence, and venv presence. If any gate is absent it skips cleanly.
+
+```bash
+# Run the knowledge-kit-live acceptance test directly:
+bash evals/acceptance/test_knowledge_kit_live.sh
+
+# Or through the acceptance runner:
+bash evals/acceptance/run.sh knowledge-kit-live
+```
+
+The harness asserts:
+
+| Assertion | What is checked |
+| --- | --- |
+| A1 | Example script exits 0 |
+| A2 | `<workspace>/.telemetry/full.jsonl` contains `tool.invoke` + `tool.result` |
+| A3 | `<workspace>/.flow-agents/.telemetry/full.jsonl` contains `session.start`, `tool.invoke`, `tool.result` |
+| A4 | No `.telemetry` directory leaked to the workspace parent |
+| A5 | At least 1 compiled record in the knowledge store |
+| A6 | Compiled record has `source_ids` provenance referencing raw records |
+
+## How the kit tools work
+
+The example defines two Strands `@tool` functions that call the kit's flow-runner via Node.js subprocess:
+
+```python
+@tool
+def capture_knowledge(text: str, category: str) -> str:
+    """Capture raw knowledge text. 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 records into a compiled record. Returns JSON: {"id": ...}."""
+    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)
+```
+
+The bridge script (`_kit_bridge.mjs`) is written into the workspace at runtime. It imports the kit's ESM modules using absolute paths resolved from `FLOW_AGENTS_ROOT`:
+
+```javascript
+import { DefaultKnowledgeStore } from "<FLOW_AGENTS_ROOT>/kits/knowledge/adapters/default-store/index.js";
+import { capture, compile } from "<FLOW_AGENTS_ROOT>/kits/knowledge/adapters/flow-runner/index.js";
+```
+
+Kit gate telemetry is written by the Node flow-runner to `<workspace>/.telemetry/full.jsonl` (via the `FLOW_AGENTS_WORKSPACE` env var). This path is separate from the FlowAgentsHooks telemetry path (`<workspace>/.flow-agents/.telemetry/full.jsonl`) — both files are asserted in the acceptance test.
+
+## Why two programmatic + one agent-driven capture
+
+`qwen3:1.7b` (1.7B parameters) reliably calls single-tool prompts, but complex multi-capture prompts cause it to loop or produce unexpected output. The example uses programmatic captures for the first two records to keep runtime bounded (~30 seconds total), and agent-driven calls for the third capture and the compile step. This gives evidence that:
+
+- The `capture_knowledge` and `compile_knowledge` tools are callable from a real Strands agent.
+- FlowAgentsHooks records session events for those calls.
+- The kit's gate telemetry is written correctly for all operations regardless of call path.
+
+The acceptance harness asserts on filesystem evidence, not on model output quality.
+
+## console.telemetry.json mapping
+
+A `knowledge` flow entry is registered in `console.telemetry.json` to make knowledge flow events visible in the Flow Agents Console:
+
+```json
+{
+  "id": "knowledge",
+  "label": "Knowledge flows",
+  "match": { "attribute": "flow", "includes": "knowledge." },
+  "titleAttribute": "title",
+  "detailAttributes": { ... }
+}
+```
+
+This matches telemetry events where the `flow` attribute includes `"knowledge."` — for example, the kit gate events emitted by the flow-runner use `knowledge.ingest` and `knowledge.compile` as the flow identifiers.
+
+## Documented limitations
+
+1. **Model quality**: `qwen3:1.7b` is a 1.7B parameter model. It works for single-tool prompts but has limited reliability for complex multi-step instructions. Larger models will work more reliably but require API keys or more memory.
+
+2. **Single-turn scope**: Each agent invocation covers one operation. Multi-turn chaining with full context tracking across many captures is out of scope for this sprint.
+
+3. **Steering seam**: The `FlowAgentsHooks` spike injects workflow steering context once at `Agent` construction time. Per-turn steering re-evaluation is not implemented. See `docs/integrations/framework-adapter.md` § Limitations for details.
+
+4. **Kit telemetry path**: The kit's flow-runner writes telemetry to `<workspace>/.telemetry/full.jsonl` (not the `.flow-agents/.telemetry/` subdirectory used by `FlowAgentsHooks`). Both paths are separate by design: kit telemetry captures gate-point evidence, session telemetry captures agent lifecycle events.
+
+5. **compile_knowledge tool signature**: The tool takes three separate `id1`, `id2`, `id3` parameters instead of a JSON array. This is because `qwen3:1.7b` does not reliably produce valid JSON array syntax when prompted. This signature change is limited to this example and does not affect the kit's flow-runner API.
+
+## Related references
+
+- `integrations/strands/examples/knowledge_kit_live.py` — the example script
+- `evals/acceptance/test_knowledge_kit_live.sh` — the acceptance test
+- `kits/knowledge/adapters/flow-runner/index.js` — the kit flow-runner (capture + compile)
+- `kits/knowledge/adapters/default-store/index.js` — the store adapter
+- `kits/knowledge/kit.json` — kit manifest
+- <a href="framework-adapter.html">Framework Adapter</a> — `FlowAgentsHooks` documentation and limitations
+- <a href="../spec/runtime-hook-surface.html">Runtime Hook Surface spec</a> — canonical event taxonomy

package/docs/kit-authoring-guide.md

@@ -0,0 +1,169 @@
+---
+title: Flow Kit Authoring Guide
+---
+
+# Flow Kit Authoring Guide
+
+A Flow Kit is a portable workflow bundle you author once and install into any Flow Agents workspace. It lets you package one or more Flow Definitions — plus optional skills, docs, adapters, evals, and assets — under a single validated manifest. The same install, validation, and activation path that ships the built-in Builder Kit is available to your own kits.
+
+This guide walks you from an empty directory to a validated, locally installed kit.
+
+## Concepts
+
+- **Kit** — a directory with a root `kit.json` manifest and the assets it declares. The manifest is the contract; Flow Agents validates it before anything is copied.
+- **Flow Definition** — a `.flow.json` file that declares steps, gates, and expected evidence. Validation of the Flow Definition semantics belongs to [Kontour Flow](https://kontourai.github.io/flow/); the kit contract delegates to it.
+- **Activation** — the step that reads the installed kit and writes runtime-local files into your workspace. Today the `codex-local` adapter is the only adapter, and it activates only Flow Definition assets.
+
+## Directory layout
+
+```text
+my-kit/
+  kit.json            ← required manifest
+  flows/
+    review.flow.json  ← at least one Flow Definition
+  docs/               ← optional
+    README.md
+```
+
+All paths declared in `kit.json` must be relative to the kit directory and must not contain `..`. The kit must be fully self-contained so it can be installed from any machine or worktree.
+
+## Minimal kit.json
+
+```json
+{
+  "schema_version": "1.0",
+  "id": "my-kit",
+  "name": "My Kit",
+  "description": "A minimal kit that adds a review flow.",
+  "flows": [
+    {
+      "id": "my-kit.review",
+      "path": "flows/review.flow.json",
+      "description": "Review a change against agreed criteria."
+    }
+  ]
+}
+```
+
+Required fields:
+
+| Field | Rule |
+|---|---|
+| `schema_version` | Must be `"1.0"` |
+| `id` | Stable kebab-case string, e.g. `review-kit` |
+| `name` | Non-empty display name |
+| `flows` | Non-empty list; each entry must have `id` and `path` |
+
+Optional fields: `product_name`, `description`, `skills`, `docs`, `adapters`, `evals`, `assets`. Optional fields list relative asset paths or objects with `id`, `path`, and optional `description`. They are declared for provenance but only Flow Definition assets are activated today; others appear in diagnostics as `skipped_assets`.
+
+## Minimal flow file
+
+A Flow Definition at minimum needs `id`, `version`, `steps`, and `gates`. Steps form a linked list; each gate names the step it guards and the evidence it expects.
+
+```json
+{
+  "id": "my-kit.review",
+  "version": "1.0",
+  "steps": [
+    { "id": "review", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "review-gate": {
+      "step": "review",
+      "expects": [
+        {
+          "id": "review-finding",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The change was reviewed and findings were recorded.",
+          "claim": {
+            "type": "my-kit.review.finding",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+The `id` in the flow file should match the `id` declared in `kit.json`'s `flows` list. Look at `kits/builder/flows/shape.flow.json` and `kits/builder/flows/build.flow.json` in this repository for fuller examples of multi-step flows with required and optional gate evidence.
+
+## Validate
+
+Before installing or sharing a kit, run validation from the flow-agents checkout:
+
+```bash
+npm run validate:source -- --kit path/to/my-kit
+```
+
+This runs the same repository contract validation used by `install-local`. A validation failure exits nonzero with a diagnostic. Fix errors and re-run until it passes cleanly.
+
+The full source-tree validation (no `--kit` flag) additionally validates the built-in catalog and Builder Kit:
+
+```bash
+npm run validate:source --
+```
+
+## Install locally
+
+Once validation passes, install the kit into a target workspace:
+
+```bash
+npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to/workspace
+```
+
+`--dest` is the installed Flow Agents bundle root. When omitted the command uses the current directory. From a contributor checkout of this repository, the equivalent form is `npm run flow-kit -- <command>`.
+
+Confirm the install:
+
+```bash
+npx @kontourai/flow-agents flow-kit list --dest /path/to/workspace
+npx @kontourai/flow-agents flow-kit status my-kit --dest /path/to/workspace
+```
+
+`list` prints one summary line per installed kit. `status` prints JSON provenance including the SHA256 content hash and `installed` or `missing` state.
+
+To replace an existing install after you update the kit source:
+
+```bash
+npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to/workspace --update
+```
+
+## Activate
+
+After installing, run activate to write runtime-local files into the workspace:
+
+```bash
+npx @kontourai/flow-agents flow-kit activate --dest /path/to/workspace --format json
+```
+
+The `codex-local` adapter is selected automatically. It writes Flow Definition copies under `.flow-agents/runtime/codex/flows/<kit-id>/` and an `activation.json` manifest. Declared `skills`, `docs`, `adapters`, `evals`, and `assets` are recorded as `skipped_assets` — they are not an error, just not activated yet.
+
+When installing through `npx @kontourai/flow-agents init` with the Codex runtime, pass `--activate-kits` to run activation as part of init:
+
+```bash
+npx @kontourai/flow-agents init --runtime codex --dest /path/to/workspace --activate-kits --yes
+```
+
+## Troubleshooting
+
+Common validation errors and fixes are documented in the [Flow Kit Repository Contract](flow-kit-repository-contract.md#common-failures). The most frequent:
+
+- `kit.json: .schema_version must be "1.0"` — update the manifest.
+- `kit.json: .id must be a stable kebab-case string` — use a lowercase id like `review-kit`.
+- `kit.json: .flows must be a non-empty list` — declare at least one Flow Definition.
+- `kit.json: flows[0].path points at missing Flow Definition` — add the file or fix the path.
+- `kit.json: docs[0].path points at missing asset` — add the asset or remove the entry.
+
+For path errors: all declared paths must be relative, must not contain `..`, and must point at existing files. Absolute paths are rejected because a kit must be portable between machines.
+
+For conflicts on re-install: if you install a different source with an existing kit id, the command fails unless you pass `--update`. Use `--force` to re-copy an existing same-source install after validation.
+
+See the [Flow Kit Repository Contract](flow-kit-repository-contract.md) for the full validation rules, registry schema, activation diagnostics, and the install/update/force semantics.
+
+## Direction
+
+Flow Kits are designed to be shareable workflow units — authored once, carried across teams and workspaces. The intended growth path is distribution from git remotes and a curated Kontour kit catalog of Kontour-authored kits covering work modes beyond software delivery. Today install is local-path only; remote fetch is explicitly a non-goal in this version.

package/docs/spec/runtime-hook-surface.md

@@ -207,7 +207,7 @@ The following tables show the canonical Flow Agents events and their correspondi
 
 | Canonical Event | Claude Code | Codex | Kiro | opencode | pi |
 | --- | --- | --- | --- | --- | --- |
-| `agentSpawn` | `SessionStart` | `SessionStart` | `SessionStart` | `session.created` | `session_start` |
+| `agentSpawn` | `SessionStart` | `SessionStart` | `SessionStart` | `session.created` (interactive mode only — NOT delivered to plugin hooks in `run`/non-interactive mode; verified v1.16.2) | `session_start` |
 | `userPromptSubmit` | `UserPromptSubmit` | `UserPromptSubmit` | `UserPromptSubmit` | No native equivalent | `input` (closest; fires on user input, not confirmed submission) |
 | `preToolUse` | `PreToolUse` | `PreToolUse` | `PreToolUse` | `tool.execute.before` | `tool_call` (blockable) |
 | `permissionRequest` | `PermissionRequest` | `PermissionRequest` | No native equivalent | No native equivalent | No native equivalent |
@@ -333,7 +333,9 @@ Each adapter must include a conformance declaration in its adapter documentation
 conformance_level: L1
 host: opencode
 event_coverage:
-  agentSpawn: session.created (full fidelity)
+  agentSpawn: session.created — delivered in interactive mode; NOT delivered to plugin
+    hooks in run (non-interactive) mode (verified v1.16.2, 2026-06-11). agentSpawn
+    telemetry is absent from run-mode sessions; tool.invoke/tool.result are present.
   userPromptSubmit: no native equivalent — workflow steering unavailable at turn boundary
   preToolUse: tool.execute.before (full fidelity, blocking available)
   postToolUse: tool.execute.after (full fidelity)
@@ -342,10 +344,14 @@ event_coverage:
   subagentStart: no native equivalent
   subagentStop: no native equivalent
 policy_coverage:
-  workflow_steering: partial — injected at session.created only, not at each turn
+  workflow_steering: partial — injected at session.created only (interactive mode); unavailable in run mode
   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)
+named_gaps:
+  session.created_run_mode: In opencode run mode, session.created is not delivered
+    to plugin hooks. This is an opencode runtime limitation with no known workaround
+    at the plugin API level. agentSpawn telemetry is NOT_VERIFIED for run-mode sessions.
 ```
 
 ---
@@ -470,3 +476,50 @@ node packaging/conformance/run-conformance.js \
 ```
 
 See `packaging/conformance/README.md` for the full fixture inventory and declaration format.
+
+---
+
+## 9. Framework-Path Kit Activation (strands-local adapter)
+
+**Added**: Issue #32 — Knowledge Kit S4: framework-path kit activation.
+
+### 9.1 Decision record (Q3)
+
+Kit flow activation for Strands workspaces is implemented as a new runtime adapter id (`strands-local`) in `src/runtime-adapters.ts`, not as kit-flow loading inside `FlowAgentsHooks`. This keeps the `FlowAgentsHooks` class free of catalog-layout knowledge and reuses the `readKitInventory` + `safeSegment` helpers from the `codex-local` path.
+
+The CLI command is:
+
+```bash
+flow-kit activate --adapter strands-local [--dest DIR] [--source-root DIR]
+```
+
+This writes activated flow files to `.flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json` and produces a parity-diagnostic `activation.json` (same schema as codex-local: `schema_version`, `adapter`, `supported_asset_classes`, `generated_runtime_files`, `skipped_assets`, `warnings`, `errors`).
+
+### 9.2 Steering context surfacing (AC2)
+
+`FlowAgentsHooks.steering_context()` (Python) and `FlowAgentsHooks.steeringContext()` (TypeScript) read the runtime flow files written by `strands-local` activation and include a `KIT FLOWS:` section in the steering context text. This section lists each activated kit flow by id and description so the agent is aware of available workflow guidance without the hooks needing to know the catalog layout at construction time.
+
+**Python usage** (see ):
+
+```
+hooks = FlowAgentsHooks(workspace=".")
+system_prompt = base_prompt + hooks.steering_context()
+# steering_context() includes KIT FLOWS section if .flow-agents/runtime/strands/flows/ is populated
+```
+
+**TypeScript usage**:
+
+```typescript
+const hooks = new FlowAgentsHooks({ workspace: "." });
+const systemPrompt = basePrompt + hooks.steeringContext();
+// steeringContext() includes KIT FLOWS section if .flow-agents/runtime/strands/flows/ is populated
+```
+
+### 9.3 Co-existence with codex-local
+
+The `codex-local` and `strands-local` runtime directories are independent:
+
+- `codex-local` writes to `.flow-agents/runtime/codex/`
+- `strands-local` writes to `.flow-agents/runtime/strands/`
+
+Running either adapter does not affect the other's runtime directory. Both adapters skip non-flow asset classes (skills, docs, adapters, evals, assets) with `reason: "asset class is diagnostic-only for <adapter>"`.

package/evals/acceptance/run.sh

@@ -11,10 +11,18 @@ run_one() {
   bash "$ACCEPT_DIR/test_${name}_harness.sh"
 }
 
+run_knowledge_kit_live() {
+  echo ""
+  bash "$ACCEPT_DIR/test_knowledge_kit_live.sh"
+}
+
 case "$TARGET" in
   kiro|claude|codex|opencode|pi)
     run_one "$TARGET"
     ;;
+  knowledge-kit-live)
+    run_knowledge_kit_live
+    ;;
   all)
     status=0
     run_one kiro || status=1
@@ -22,10 +30,11 @@ case "$TARGET" in
     run_one codex || status=1
     run_one opencode || status=1
     run_one pi || status=1
+    run_knowledge_kit_live || status=1
     exit "$status"
     ;;
   *)
-    echo "Usage: bash evals/acceptance/run.sh [all|kiro|claude|codex|opencode|pi]"
+    echo "Usage: bash evals/acceptance/run.sh [all|kiro|claude|codex|opencode|pi|knowledge-kit-live]"
     exit 1
     ;;
 esac