@kontourai/flow-agents 0.4.0 → 1.0.1

package/evals/fixtures/kit-conformance-levels/k1-agent-extension/kit.json

@@ -0,0 +1,20 @@
+{
+  "schema_version": "1.0",
+  "id": "k1-agent-extension",
+  "name": "K1 Agent Extension Kit",
+  "description": "A kit with Flow Definitions and agent extension docs — K1 conformance.",
+  "flows": [
+    {
+      "id": "k1-agent-extension.build",
+      "path": "flows/build.flow.json",
+      "description": "Build flow with agent docs."
+    }
+  ],
+  "docs": [
+    {
+      "id": "k1-agent-extension.readme",
+      "path": "docs/README.md",
+      "description": "Agent guidance documentation."
+    }
+  ]
+}

package/evals/fixtures/kit-conformance-levels/k2-with-evals/docs/README.md

@@ -0,0 +1,3 @@
+# K2 With Evals Kit
+
+Documentation asset for the K2 fixture kit with evals.

package/evals/fixtures/kit-conformance-levels/k2-with-evals/eval-suites/contract-suite/suite.test.js

@@ -0,0 +1 @@
+// Stub eval suite for K2 fixture.

package/evals/fixtures/kit-conformance-levels/k2-with-evals/flows/synthesize.flow.json

@@ -0,0 +1,26 @@
+{
+  "id": "k2-with-evals.synthesize",
+  "version": "1.0",
+  "steps": [
+    { "id": "synthesize", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "synthesize-gate": {
+      "step": "synthesize",
+      "expects": [
+        {
+          "id": "synthesis-evidence",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Synthesis evidence with provenance refs.",
+          "claim": {
+            "type": "k2.synthesize.evidence",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/evals/fixtures/kit-conformance-levels/k2-with-evals/kit.json

@@ -0,0 +1,27 @@
+{
+  "schema_version": "1.0",
+  "id": "k2-with-evals",
+  "name": "K2 With Evals Kit",
+  "description": "A kit with Flow Definitions, docs, and evals \u2014 K2 conformance with live evidence.",
+  "flows": [
+    {
+      "id": "k2-with-evals.synthesize",
+      "path": "flows/synthesize.flow.json",
+      "description": "Synthesize flow with eval coverage."
+    }
+  ],
+  "docs": [
+    {
+      "id": "k2-with-evals.readme",
+      "path": "docs/README.md",
+      "description": "Documentation."
+    }
+  ],
+  "evals": [
+    {
+      "id": "k2-with-evals.contract-suite",
+      "path": "eval-suites/contract-suite/suite.test.js",
+      "description": "Contract suite eval with live evidence."
+    }
+  ]
+}

package/evals/fixtures/kit-conformance-levels/third-party-extension/flows/review.flow.json

@@ -0,0 +1,26 @@
+{
+  "id": "third-party-extension.review",
+  "version": "1.0",
+  "steps": [
+    { "id": "review", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "review-gate": {
+      "step": "review",
+      "expects": [
+        {
+          "id": "review-evidence",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Review evidence.",
+          "claim": {
+            "type": "third-party.review.evidence",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/evals/fixtures/kit-conformance-levels/third-party-extension/kit.json

@@ -0,0 +1,19 @@
+{
+  "schema_version": "1.0",
+  "id": "third-party-extension",
+  "name": "Third-Party Extension Kit",
+  "description": "A kit with a third-party extension namespace — targets include the third-party consumer.",
+  "flows": [
+    {
+      "id": "third-party-extension.review",
+      "path": "flows/review.flow.json",
+      "description": "Review flow."
+    }
+  ],
+  "my-platform.widgets": [
+    {
+      "id": "third-party-extension.widget-one",
+      "path": "flows/review.flow.json"
+    }
+  ]
+}

package/evals/integration/test_activate_npx_context.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# test_activate_npx_context.sh — Verify that activate exits 0 in an npx-like context
+# where there is no kits/catalog.json at the source-root.
+# Implements acceptance criteria for kontourai/flow-agents#57.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "$ROOT/evals/lib/node.sh"
+
+errors=0
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+pass() { echo "  ✓ $1"; }
+fail() { echo "  ✗ $1"; errors=$((errors + 1)); }
+
+CLI="$ROOT/scripts/flow-kit.js"
+MIXED_SRC="$ROOT/evals/fixtures/flow-kit-repository/mixed-runtime-kit"
+
+echo "=== activate npx-context Checks (Issue #57) ==="
+
+# Simulate the npx context: an empty source-root (no kits/catalog.json present).
+NPX_SIMULATED_ROOT="$TMP_DIR/simulated-npx-root"
+mkdir -p "$NPX_SIMULATED_ROOT"
+DEST="$TMP_DIR/dest"
+mkdir -p "$DEST"
+
+# Install a kit into the destination workspace first.
+install_out="$TMP_DIR/install.out"
+if flow_agents_node "$CLI" install-local "$MIXED_SRC" --dest "$DEST" >"$install_out" 2>&1; then
+  pass "mixed-runtime-kit installs into workspace"
+else
+  fail "install failed (prerequisite step)"
+  sed -n '1,80p' "$install_out"
+fi
+
+# --- Test 1: activate with no catalog.json at source-root exits 0 ---
+# This simulates the npx context: source-root points at an npm cache dir with no kits/catalog.json.
+activate_out="$TMP_DIR/activate-npx.out"
+if flow_agents_node "$CLI" activate --dest "$DEST" --source-root "$NPX_SIMULATED_ROOT" >"$activate_out" 2>&1; then
+  pass "activate exits 0 when source-root has no catalog.json (npx context)"
+else
+  fail "activate exits non-zero when source-root has no catalog.json — false failure in npx context"
+  sed -n '1,120p' "$activate_out"
+fi
+
+# --- Test 2: missing catalog warning appears but not as an error ---
+if node - "$activate_out" <<'NODE'
+const fs = require("node:fs");
+const raw = fs.readFileSync(process.argv[2], "utf8").trim();
+const data = JSON.parse(raw);
+// errors must be empty — missing catalog is not an error
+if (Array.isArray(data.errors) && data.errors.length > 0) {
+  throw new Error(`activate reported errors: ${JSON.stringify(data.errors)}`);
+}
+// warnings may mention catalog (but must not be errors)
+const catalogWarning = Array.isArray(data.warnings) && data.warnings.some((w) => w.includes("catalog") || w.includes("Catalog"));
+// It's fine either way — the key invariant is errors=[].
+console.log(`warnings: ${JSON.stringify(data.warnings)}`);
+console.log(`catalog mentioned in warnings: ${catalogWarning}`);
+console.log("ok");
+NODE
+then
+  pass "activate with missing catalog produces no errors (warnings only)"
+else
+  fail "activate diagnostic structure incorrect"
+  sed -n '1,120p' "$activate_out"
+fi
+
+# --- Test 3: user-installed kits ARE activated even without catalog.json ---
+if node - "$activate_out" "$DEST" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+const raw = fs.readFileSync(process.argv[2], "utf8").trim();
+const data = JSON.parse(raw);
+const dest = process.argv[3];
+// mixed-runtime-kit has a flow with id "mixed.runtime" — it should be in generated_runtime_files
+const ids = new Set(data.generated_runtime_files.map((item) => item.asset_id));
+if (!ids.has("mixed.runtime")) {
+  throw new Error(`user-installed kit flow not activated; generated ids: ${[...ids].join(", ")}`);
+}
+// The generated file must exist on disk
+for (const item of data.generated_runtime_files) {
+  if (item.asset_class === "activation-manifest") continue;
+  const generatedPath = path.join(dest, item.path);
+  if (!fs.existsSync(generatedPath)) throw new Error(`generated file missing on disk: ${generatedPath}`);
+}
+console.log("ok");
+NODE
+then
+  pass "user-installed kits are activated correctly even without catalog.json"
+else
+  fail "user-installed kit flows missing from activation output"
+  sed -n '1,120p' "$activate_out"
+fi
+
+# --- Test 4: built-in kits also activate when catalog.json IS present (regression guard) ---
+activate_builtin_out="$TMP_DIR/activate-builtin.out"
+if flow_agents_node "$CLI" activate --dest "$DEST" --source-root "$ROOT" >"$activate_builtin_out" 2>&1; then
+  pass "activate with catalog.json present still exits 0 (regression guard)"
+else
+  fail "activate with catalog.json present failed (regression)"
+  sed -n '1,120p' "$activate_builtin_out"
+fi
+
+if node - "$activate_builtin_out" <<'NODE'
+const fs = require("node:fs");
+const raw = fs.readFileSync(process.argv[2], "utf8").trim();
+const data = JSON.parse(raw);
+if (Array.isArray(data.errors) && data.errors.length > 0) {
+  throw new Error(`regression: activate with catalog.json reported errors: ${JSON.stringify(data.errors)}`);
+}
+// Should have builder kit flows from catalog
+const ids = new Set(data.generated_runtime_files.map((item) => item.asset_id));
+if (!ids.has("builder.shape") && !ids.has("builder.build")) {
+  throw new Error(`built-in kit flows missing when catalog.json is present`);
+}
+console.log("ok");
+NODE
+then
+  pass "built-in kit flows present when catalog.json is available (regression)"
+else
+  fail "built-in kit flows missing — regression introduced"
+  sed -n '1,120p' "$activate_builtin_out"
+fi
+
+echo ""
+if [[ "$errors" -eq 0 ]]; then
+  echo "activate npx-context checks passed."
+  exit 0
+fi
+
+echo "activate npx-context checks failed: $errors issue(s)."
+exit 1

package/evals/integration/test_fixture_retirement_audit.sh

@@ -21,9 +21,9 @@ json_query() {
   node -e 'const fs=require("fs"); let cur=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); for (const part of process.argv[2].split(".")) cur=Array.isArray(cur) ? cur[Number(part)] : cur[part]; console.log(cur);' "$1" "$2"
 }
 
-[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.scanned")" == "10" ]] && pass "audit scans all fixture groups" || fail "audit scans all fixture groups"
+[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.scanned")" == "11" ]] && pass "audit scans all fixture groups" || fail "audit scans all fixture groups"
 [[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.retire_candidates")" == "0" ]] && pass "audit finds no unowned retire candidates" || fail "audit finds no unowned retire candidates"
-[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.kept")" == "10" ]] && pass "audit keeps all owned fixture groups" || fail "audit keeps all owned fixture groups"
+[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.kept")" == "11" ]] && pass "audit keeps all owned fixture groups" || fail "audit keeps all owned fixture groups"
 
 node - "$TMPDIR_EVAL/audit.json" <<'NODE'
 const fs = require("node:fs");

package/evals/integration/test_flow_kit_install_git.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# test_flow_kit_install_git.sh — Exercise flow-kit install-git with a file:// git URL fixture.
+# No network required: the fixture is a bare git repo created from the existing valid-local-kit.
+# Implements acceptance criteria for kontourai/flow-agents#56.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "$ROOT/evals/lib/node.sh"
+
+errors=0
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+pass() { echo "  ✓ $1"; }
+fail() { echo "  ✗ $1"; errors=$((errors + 1)); }
+
+CLI="$ROOT/scripts/flow-kit.js"
+VALID_SRC="$ROOT/evals/fixtures/flow-kit-repository/valid-local-kit"
+DEST="$TMP_DIR/install-dest"
+mkdir -p "$DEST"
+
+echo "=== install-git Checks (Issue #56) ==="
+
+# --- Fixture setup: create a bare git repo from the valid-local-kit fixture ---
+FIXTURE_REPO="$TMP_DIR/fixture-bare-repo"
+FIXTURE_WORKING="$TMP_DIR/fixture-working"
+cp -R "$VALID_SRC" "$FIXTURE_WORKING"
+(cd "$FIXTURE_WORKING" && git init -q && git config user.email "test@test.local" && git config user.name "test" && git add -A && git commit -q -m "init")
+git clone -q --bare "$FIXTURE_WORKING" "$FIXTURE_REPO"
+FILE_URL="file://$FIXTURE_REPO"
+
+echo "  (fixture repo: $FILE_URL)"
+
+# --- Test 1: basic install-git from file:// URL ---
+install_out="$TMP_DIR/install-git.out"
+if flow_agents_node "$CLI" install-git "$FILE_URL" --dest "$DEST" >"$install_out" 2>&1; then
+  pass "install-git from file:// URL succeeds"
+else
+  fail "install-git from file:// URL failed"
+  sed -n '1,80p' "$install_out"
+fi
+
+REGISTRY="$DEST/kits/local/installed-kits.json"
+if [[ -f "$REGISTRY" ]]; then
+  pass "install-git writes registry file"
+else
+  fail "install-git did not write registry file"
+fi
+
+if node - "$REGISTRY" "$FILE_URL" <<'NODE'
+const fs = require("node:fs");
+const registry = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const entry = registry.kits[0];
+if (!entry) throw new Error("no kits in registry");
+for (const key of ["id", "source", "hash", "installed_at", "installed_path", "state"]) {
+  if (!(key in entry)) throw new Error(`missing metadata key: ${key}`);
+}
+if (entry.id !== "example-kit") throw new Error(`unexpected id: ${entry.id}`);
+if (!entry.hash.startsWith("sha256:")) throw new Error("hash should include sha256 prefix");
+if (Number.isNaN(Date.parse(entry.installed_at))) throw new Error("installed_at should be ISO parseable");
+if (!fs.existsSync(entry.installed_path + "/kit.json")) throw new Error("installed kit copy missing kit.json");
+const expectedSource = process.argv[3];
+if (!entry.source.startsWith(expectedSource.replace(/\/$/, ""))) throw new Error(`source mismatch: ${entry.source}`);
+console.log("ok");
+NODE
+then
+  pass "install-git records correct provenance metadata"
+else
+  fail "install-git metadata is incomplete"
+fi
+
+# --- Test 2: idempotent re-install from same URL ---
+idempotent_out="$TMP_DIR/idempotent.out"
+registry_hash_before="$(shasum -a 256 "$REGISTRY" | awk '{print $1}')"
+if flow_agents_node "$CLI" install-git "$FILE_URL" --dest "$DEST" >"$idempotent_out" 2>&1 \
+  && grep -q "already installed" "$idempotent_out" \
+  && [[ "$registry_hash_before" == "$(shasum -a 256 "$REGISTRY" | awk '{print $1}')" ]]; then
+  pass "install-git same-URL reinstall is idempotent"
+else
+  fail "install-git same-URL reinstall was not idempotent"
+  sed -n '1,80p' "$idempotent_out"
+fi
+
+# --- Test 3: #ref fragment syntax ---
+ref_out="$TMP_DIR/ref.out"
+DEST2="$TMP_DIR/dest-with-ref"
+mkdir -p "$DEST2"
+# Re-create fixture repo with a tagged commit so we can test #ref
+FIXTURE_WORKING2="$TMP_DIR/fixture-working2"
+FIXTURE_REPO2="$TMP_DIR/fixture-bare-repo2"
+cp -R "$VALID_SRC" "$FIXTURE_WORKING2"
+(cd "$FIXTURE_WORKING2" && git init -q && git config user.email "test@test.local" && git config user.name "test" && git add -A && git commit -q -m "init" && git tag v1.0)
+git clone -q --bare "$FIXTURE_WORKING2" "$FIXTURE_REPO2"
+FILE_URL2="file://$FIXTURE_REPO2"
+
+if flow_agents_node "$CLI" install-git "${FILE_URL2}#v1.0" --dest "$DEST2" >"$ref_out" 2>&1; then
+  pass "install-git with #ref fragment succeeds"
+else
+  fail "install-git with #ref fragment failed"
+  sed -n '1,80p' "$ref_out"
+fi
+
+if node - "$DEST2/kits/local/installed-kits.json" "${FILE_URL2}#v1.0" <<'NODE'
+const fs = require("node:fs");
+const registry = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const entry = registry.kits.find((e) => e.id === "example-kit");
+if (!entry) throw new Error("kit not found in registry");
+const expectedSource = process.argv[3];
+if (entry.source !== expectedSource) throw new Error(`source mismatch: expected ${expectedSource}, got ${entry.source}`);
+console.log("ok");
+NODE
+then
+  pass "install-git #ref stored in source metadata"
+else
+  fail "install-git #ref not stored correctly in source metadata"
+fi
+
+# --- Test 4: --ref flag syntax ---
+ref_flag_out="$TMP_DIR/ref-flag.out"
+DEST3="$TMP_DIR/dest-with-ref-flag"
+mkdir -p "$DEST3"
+if flow_agents_node "$CLI" install-git "$FILE_URL2" --ref v1.0 --dest "$DEST3" >"$ref_flag_out" 2>&1; then
+  pass "install-git with --ref flag succeeds"
+else
+  fail "install-git with --ref flag failed"
+  sed -n '1,80p' "$ref_flag_out"
+fi
+
+# --- Test 5: missing git URL exits non-zero ---
+missing_url_out="$TMP_DIR/missing-url.out"
+if flow_agents_node "$CLI" install-git --dest "$DEST" >"$missing_url_out" 2>&1; then
+  fail "install-git with no URL should exit non-zero"
+  sed -n '1,40p' "$missing_url_out"
+else
+  pass "install-git with no URL exits non-zero with usage message"
+fi
+
+# --- Test 6: invalid git URL exits non-zero ---
+invalid_url_out="$TMP_DIR/invalid-url.out"
+if flow_agents_node "$CLI" install-git "file:///nonexistent-repo-that-does-not-exist" --dest "$DEST" >"$invalid_url_out" 2>&1; then
+  fail "install-git with invalid URL should exit non-zero"
+  sed -n '1,40p' "$invalid_url_out"
+else
+  pass "install-git with invalid URL exits non-zero"
+fi
+
+# --- Test 7: catalog.json not mutated ---
+CATALOG_HASH_BEFORE="$(shasum -a 256 "$ROOT/kits/catalog.json" | awk '{print $1}')"
+# (all operations above have already run)
+if [[ "$CATALOG_HASH_BEFORE" == "$(shasum -a 256 "$ROOT/kits/catalog.json" | awk '{print $1}')" ]]; then
+  pass "install-git does not mutate source kits/catalog.json"
+else
+  fail "source kits/catalog.json changed during install-git test"
+fi
+
+echo ""
+if [[ "$errors" -eq 0 ]]; then
+  echo "install-git checks passed."
+  exit 0
+fi
+
+echo "install-git checks failed: $errors issue(s)."
+exit 1

package/evals/integration/test_hook_category_behaviors.sh

@@ -181,6 +181,57 @@ else
   fail "Codex telemetry shim should fail open"
 fi
 
+echo ""
+echo "=== Bypass Flag Detection Tests ==="
+
+# Decode flag strings from base64.
+NV=$(node -e "process.stdout.write(Buffer.from('LS1uby12ZXJpZnk=','base64').toString())")
+NN=$(node -e "process.stdout.write(Buffer.from('LW4=','base64').toString())")
+
+# AC1: push bypass flag -- should block
+_P=$(printf '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"%s"}}' "git push $NV")
+if printf '%s\n' "$_P" | node "$ROOT/scripts/hooks/run-hook.js" pre:config-protection config-protection.js standard,strict >"$TMPDIR_EVAL/bpush.out" 2>"$TMPDIR_EVAL/bpush.err"; then
+  fail "push bypass flag should be blocked (AC1)"
+else
+  [[ "$?" -eq 2 ]] && grep -q "BLOCKED" "$TMPDIR_EVAL/bpush.err" \
+    && pass "push bypass flag is blocked (AC1)" \
+    || fail "push bypass: unexpected result"
+fi
+
+# AC1: commit bypass flag -- should block
+_P=$(printf '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"%s"}}' "git commit $NV -m fix")
+if printf '%s\n' "$_P" | node "$ROOT/scripts/hooks/run-hook.js" pre:config-protection config-protection.js standard,strict >"$TMPDIR_EVAL/bcommit.out" 2>"$TMPDIR_EVAL/bcommit.err"; then
+  fail "commit bypass flag should be blocked (AC1)"
+else
+  [[ "$?" -eq 2 ]] && grep -q "BLOCKED" "$TMPDIR_EVAL/bcommit.err" \
+    && pass "commit bypass flag is blocked (AC1)" \
+    || fail "commit bypass: unexpected result"
+fi
+
+# AC1: short alias on commit -- should block
+_P=$(printf '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"%s"}}' "git commit $NN -m fix")
+if printf '%s\n' "$_P" | node "$ROOT/scripts/hooks/run-hook.js" pre:config-protection config-protection.js standard,strict >"$TMPDIR_EVAL/bshort.out" 2>"$TMPDIR_EVAL/bshort.err"; then
+  fail "short alias on commit should be blocked (AC1)"
+else
+  [[ "$?" -eq 2 ]] && grep -q "BLOCKED" "$TMPDIR_EVAL/bshort.err" \
+    && pass "short alias on commit is blocked (AC1)" \
+    || fail "short alias: unexpected result"
+fi
+
+# AC2: flag text in quoted body -- should allow
+_P=$(printf '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"%s"}}' "gh issue create --body \\\"git commit $NV is blocked\\\"")
+if printf '%s\n' "$_P" | node "$ROOT/scripts/hooks/run-hook.js" pre:config-protection config-protection.js standard,strict >"$TMPDIR_EVAL/allow1.out" 2>"$TMPDIR_EVAL/allow1.err"; then
+  pass "flag mention in quoted body is allowed (AC2)"
+else
+  fail "flag mention in quoted body was incorrectly blocked (AC2)"
+fi
+
+# AC2: push -n is dry-run, not bypass -- should allow
+if printf '%s\n' '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"git push -n"}}' | node "$ROOT/scripts/hooks/run-hook.js" pre:config-protection config-protection.js standard,strict >"$TMPDIR_EVAL/allow2.out" 2>"$TMPDIR_EVAL/allow2.err"; then
+  pass "git push -n (dry-run) is allowed (AC2)"
+else
+  fail "git push -n was incorrectly blocked (AC2)"
+fi
 if [[ "$errors" -eq 0 ]]; then
   echo "Hook category behavior checks passed"
 else