@kontourai/flow-agents 0.4.0 → 1.0.1

package/evals/integration/test_kit_conformance_levels.sh

@@ -0,0 +1,209 @@
+#!/usr/bin/env bash
+# test_kit_conformance_levels.sh — K-level derivation and degradation invariant tests.
+#
+# Tests three behaviors from issue #52:
+#   1. Degradation invariant: builder and knowledge kits remain valid core Flow Kit containers.
+#   2. Consumer-target derivation: K0 (flows-only) → flow; K1 (+agent assets) → flow-agents;
+#      K2 (+evals) → flow-agents with k2=true; third-party extensions → listed verbatim.
+#   3. inspect subcommand outputs stable JSON.
+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)); }
+
+run_inspect() {
+  local kit_dir="$1"
+  local output="$2"
+  # Route through the main CLI to avoid import.meta.url path-resolution issues.
+  flow_agents_build_ts 2>/dev/null
+  node "$FLOW_AGENTS_EVAL_ROOT/build/src/cli.js" flow-kit inspect "$kit_dir" >"$output" 2>&1
+}
+
+# ===================================================================
+echo "=== 1. Degradation Invariant: built-in kits pass core container ==="
+# ===================================================================
+
+for kit_name in builder knowledge; do
+  kit_dir="$ROOT/kits/$kit_name"
+  out="$TMP_DIR/degrade-${kit_name}.out"
+  if run_inspect "$kit_dir" "$out"; then
+    k0=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k0)" 2>/dev/null)
+    if [[ "$k0" == "true" ]]; then
+      pass "$kit_name kit degradation invariant: k0=true (valid core container)"
+    else
+      fail "$kit_name kit degradation invariant: k0 should be true"
+      cat "$out"
+    fi
+  else
+    fail "$kit_name kit inspect failed"
+    cat "$out"
+  fi
+done
+
+# Verify builder kit is K1 (has agent extension fields, no evals in kit.json)
+out="$TMP_DIR/builder-k1.out"
+run_inspect "$ROOT/kits/builder" "$out" || true
+k1=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k1)" 2>/dev/null)
+k2=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k2)" 2>/dev/null)
+if [[ "$k1" == "false" ]]; then
+  pass "builder kit is K0 only (no agent extension assets declared in kit.json)"
+else
+  pass "builder kit is K1+ (agent extension assets present)"
+fi
+
+# Verify knowledge kit is K2 (has evals)
+out="$TMP_DIR/knowledge-k2.out"
+run_inspect "$ROOT/kits/knowledge" "$out" || true
+k2=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k2)" 2>/dev/null)
+if [[ "$k2" == "true" ]]; then
+  pass "knowledge kit is K2 (evals present)"
+else
+  fail "knowledge kit should be K2 (has evals in kit.json)"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+echo "=== 2. K0 fixture: flows-only → target=flow only ==="
+# ===================================================================
+
+k0_fixture="$ROOT/evals/fixtures/kit-conformance-levels/k0-flows-only"
+out="$TMP_DIR/k0.out"
+if run_inspect "$k0_fixture" "$out"; then
+  k0=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k0)" 2>/dev/null)
+  k1=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k1)" 2>/dev/null)
+  targets=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).targets.join(','))" 2>/dev/null)
+  [[ "$k0" == "true" ]] && pass "K0 fixture: k0=true" || { fail "K0 fixture: expected k0=true, got $k0"; cat "$out"; }
+  [[ "$k1" == "false" ]] && pass "K0 fixture: k1=false (no agent extension)" || { fail "K0 fixture: expected k1=false, got $k1"; cat "$out"; }
+  [[ "$targets" == "flow" ]] && pass "K0 fixture: targets=['flow'] only" || { fail "K0 fixture: expected targets=['flow'], got '$targets'"; cat "$out"; }
+else
+  fail "K0 fixture inspect failed"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+echo "=== 3. K1 fixture: flows+docs → targets=[flow,flow-agents] ==="
+# ===================================================================
+
+k1_fixture="$ROOT/evals/fixtures/kit-conformance-levels/k1-agent-extension"
+out="$TMP_DIR/k1.out"
+if run_inspect "$k1_fixture" "$out"; then
+  k0=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k0)" 2>/dev/null)
+  k1=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k1)" 2>/dev/null)
+  k2=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k2)" 2>/dev/null)
+  targets=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).targets.join(','))" 2>/dev/null)
+  [[ "$k0" == "true" ]] && pass "K1 fixture: k0=true" || { fail "K1 fixture: expected k0=true, got $k0"; cat "$out"; }
+  [[ "$k1" == "true" ]] && pass "K1 fixture: k1=true (agent extension present)" || { fail "K1 fixture: expected k1=true, got $k1"; cat "$out"; }
+  [[ "$k2" == "false" ]] && pass "K1 fixture: k2=false (no evals)" || { fail "K1 fixture: expected k2=false, got $k2"; cat "$out"; }
+  [[ "$targets" == "flow,flow-agents" ]] && pass "K1 fixture: targets=[flow,flow-agents]" || { fail "K1 fixture: expected targets=[flow,flow-agents], got '$targets'"; cat "$out"; }
+else
+  fail "K1 fixture inspect failed"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+echo "=== 4. K2 fixture: flows+docs+evals → targets=[flow,flow-agents] k2=true ==="
+# ===================================================================
+
+k2_fixture="$ROOT/evals/fixtures/kit-conformance-levels/k2-with-evals"
+out="$TMP_DIR/k2.out"
+if run_inspect "$k2_fixture" "$out"; then
+  k2=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k2)" 2>/dev/null)
+  targets=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).targets.join(','))" 2>/dev/null)
+  [[ "$k2" == "true" ]] && pass "K2 fixture: k2=true (evals present)" || { fail "K2 fixture: expected k2=true, got $k2"; cat "$out"; }
+  [[ "$targets" == "flow,flow-agents" ]] && pass "K2 fixture: targets=[flow,flow-agents]" || { fail "K2 fixture: expected targets=[flow,flow-agents], got '$targets'"; cat "$out"; }
+else
+  fail "K2 fixture inspect failed"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+echo "=== 5. Third-party extension fixture → third-party ns in targets ==="
+# ===================================================================
+
+tp_fixture="$ROOT/evals/fixtures/kit-conformance-levels/third-party-extension"
+out="$TMP_DIR/third-party.out"
+# third-party extension fixture has an unknown top-level key; inspect still exits 0 (K0 valid)
+if run_inspect "$tp_fixture" "$out"; then
+  third_party=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).third_party_extensions.join(','))" 2>/dev/null)
+  targets=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).targets.join(','))" 2>/dev/null)
+  if echo "$third_party" | grep -q "my-platform.widgets"; then
+    pass "third-party extension fixture: unknown namespace listed in third_party_extensions"
+  else
+    fail "third-party extension fixture: expected my-platform.widgets in third_party_extensions, got '$third_party'"
+    cat "$out"
+  fi
+  if echo "$targets" | grep -q "my-platform.widgets"; then
+    pass "third-party extension fixture: unknown namespace listed in targets"
+  else
+    fail "third-party extension fixture: expected my-platform.widgets in targets, got '$targets'"
+    cat "$out"
+  fi
+else
+  fail "third-party extension fixture inspect failed (k0 should still be valid)"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+echo "=== 6. Inspect JSON schema shape ==="
+# ===================================================================
+
+out="$TMP_DIR/schema-check.out"
+run_inspect "$ROOT/kits/builder" "$out" || true
+if node -e "
+const d = require('fs').readFileSync('$out', 'utf8');
+const r = JSON.parse(d);
+const required = ['kit_id','kit_name','conformance','targets','third_party_extensions'];
+for (const k of required) {
+  if (!(k in r)) throw new Error('missing key: ' + k);
+}
+const conf = ['k0','k1','k2'];
+for (const k of conf) {
+  if (typeof r.conformance[k] !== 'boolean') throw new Error('conformance.' + k + ' must be boolean');
+}
+if (!Array.isArray(r.targets)) throw new Error('targets must be array');
+if (!Array.isArray(r.third_party_extensions)) throw new Error('third_party_extensions must be array');
+" 2>/dev/null; then
+  pass "inspect JSON output has required schema shape"
+else
+  fail "inspect JSON output is missing required fields"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+echo "=== 7. Degradation invariant: core container strip test ==="
+# ===================================================================
+
+# Verify that validateCoreContainer (via inspect) ignores agent extension fields
+# by checking that knowledge kit (which has agent extension asset fields present)
+# still passes core validation
+out="$TMP_DIR/knowledge-core.out"
+run_inspect "$ROOT/kits/knowledge" "$out" || true
+k0=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k0)" 2>/dev/null)
+if [[ "$k0" == "true" ]]; then
+  pass "knowledge kit: agent extension fields stripped, core container valid (degradation invariant)"
+else
+  fail "knowledge kit: degradation invariant violated — k0 should be true"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+if [[ "$errors" -eq 0 ]]; then
+  echo "Kit conformance level checks passed."
+  exit 0
+fi
+echo "Kit conformance level checks failed: $errors issue(s)."
+exit 1

package/evals/run.sh

@@ -192,6 +192,8 @@ run_integration() {
   bash "$EVAL_DIR/integration/test_bundle_install.sh" || result=1
   echo ""
   bash "$EVAL_DIR/integration/test_bundle_lifecycle.sh" || result=1
+  echo ""
+  bash "$EVAL_DIR/integration/test_kit_conformance_levels.sh" || result=1
   return $result
 }
 

package/kits/catalog.json

@@ -12,6 +12,12 @@
       "name": "Knowledge Kit",
       "path": "kits/knowledge",
       "description": "Store contract with record types (raw/compiled/concept), mutation operations with required provenance, default markdown+frontmatter+wikilink+graph-index adapter, and a parameterized contract test suite."
+    },
+    {
+      "id": "release-evidence",
+      "name": "Release Evidence Kit",
+      "path": "kits/release-evidence",
+      "description": "Minimal flows-only kit for proving agentless gate evaluation over surface claims in CI. One gate expects a trusted release.evidence claim."
     }
   ]
 }

package/kits/knowledge/adapters/default-store/index.js

@@ -301,7 +301,7 @@ function removeLinksFromGraph(graph, sourceId) {
 // Validation helpers
 // ---------------------------------------------------------------------------
 
-const VALID_TYPES = new Set(["raw", "compiled", "concept", "snapshot"]);
+const VALID_TYPES = new Set(["raw", "compiled", "concept", "snapshot", "person"]);
 const VALID_STATUSES = new Set(["active", "implemented", "retired"]);
 const CATEGORY_SEGMENT_RE = /^[a-z0-9_-]+$/;
 
@@ -367,7 +367,7 @@ export class DefaultKnowledgeStore {
     // Required field enforcement
     if (!input.type) throw missingEvidenceError("create: missing required field: type");
     if (!VALID_TYPES.has(input.type))
-      throw missingEvidenceError(`create: type must be raw, compiled, concept, or snapshot; got: ${input.type}`);
+      throw missingEvidenceError(`create: type must be one of raw, compiled, concept, snapshot, person; got: ${input.type}`);
     if (!input.title || !input.title.trim())
       throw missingEvidenceError("create: missing required field: title");
     if (!input.body && input.body !== "")

package/kits/knowledge/adapters/flow-runner/entity-extractor.js

@@ -0,0 +1,194 @@
+/**
+ * Knowledge Kit — Entity Extractor
+ *
+ * Pluggable interface for extracting person entities from raw/compiled records.
+ * Pattern mirrors SimilarityDetector (see flow-runner/index.js R3 pattern):
+ * an EntityExtractor is a function:
+ *
+ *   async (record: Record) => PersonMention[]
+ *
+ * where PersonMention = { name: string, role?: string, org?: string }
+ *
+ * Default implementation: AttendeeLineExtractor
+ *   - Parses "Attendees:" lines: entries separated by top-level commas (commas
+ *     inside parentheticals are NOT treated as entry separators).
+ *   - Each entry may carry an optional parenthetical role/org:
+ *     "Dana Smith (Acme VP Eng), Lee Wong (Acme, procurement)."
+ *   - Trailing sentence punctuation after the last ')' is stripped so that
+ *     end-of-line entries like 'Lee Wong (Acme procurement).' parse correctly
+ *     (fix for issue #48 — trailing period folded role into name).
+ *   - Also extracts explicit [[wikilinks]] from the body (name = link target)
+ *   - NO freeform NLP — conservative by design (R2)
+ *
+ * @module adapters/flow-runner/entity-extractor
+ */
+
+// ---------------------------------------------------------------------------
+// Attendee line parser
+// ---------------------------------------------------------------------------
+
+const ATTENDEES_LINE_RE = /^Attendees:\s*(.+)$/im;
+const ENTRY_WITH_ROLE_RE = /^([^(]+?)\s*\(([^)]+)\)\s*$/;
+const WIKILINK_RE = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+
+/**
+ * Split an attendee list on top-level commas (commas inside parentheticals
+ * are NOT treated as entry separators).
+ * "Dana Smith (Acme VP Eng), Lee Wong (Acme, procurement)." →
+ *   ["Dana Smith (Acme VP Eng)", "Lee Wong (Acme, procurement)."]
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function splitAttendeeEntries(text) {
+  const entries = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "(") depth++;
+    else if (text[i] === ")") depth--;
+    else if (text[i] === "," && depth === 0) {
+      const entry = text.slice(start, i).trim();
+      if (entry) entries.push(entry);
+      start = i + 1;
+    }
+  }
+  const last = text.slice(start).trim();
+  if (last) entries.push(last);
+  return entries;
+}
+
+/**
+ * Parse one attendee entry: "Dana Smith (Acme VP Eng)" or "Lee Wong"
+ * Returns { name, role?, org? }
+ *
+ * Strips trailing sentence punctuation only when it appears after a closing ')'
+ * to handle end-of-line cases like 'Lee Wong (Acme procurement).' without
+ * accidentally removing trailing periods that are part of abbreviated names
+ * like 'Dana S.'.
+ */
+function parseAttendeeEntry(entry) {
+  const trimmed = entry.trim();
+  // Only strip trailing punctuation when it appears after a closing ')'.
+  // This handles 'Lee Wong (Acme procurement).' (issue #48) while leaving
+  // 'Dana S.' intact so the abbreviated-name form is preserved.
+  const normalized = /\)\s*[.,;:!?]+\s*$/.test(trimmed)
+    ? trimmed.replace(/[.,;:!?]+$/, "")
+    : trimmed;
+  const match = normalized.match(ENTRY_WITH_ROLE_RE);
+  if (!match) return { name: normalized };
+
+  const name = match[1].trim();
+  const roleOrgText = match[2].trim();
+
+  // Try to split "Org Role" or "Org Title Role" — heuristic:
+  // if the parenthetical contains multiple words, first token(s) = org,
+  // last token(s) = role. We just store the whole string as role; callers
+  // can parse further. For AC1 we need role text available.
+  return { name, role: roleOrgText };
+}
+
+/**
+ * Default entity extractor: parses Attendees: lines and explicit [[wikilinks]].
+ *
+ * EntityExtractor interface:
+ *   async (record: Record) => PersonMention[]
+ *
+ * PersonMention: { name: string, role?: string, org?: string }
+ *
+ * @param {object} record
+ * @returns {Promise<Array<{name: string, role?: string, org?: string}>>}
+ */
+export async function defaultEntityExtractor(record) {
+  const body = record.body || "";
+  const mentions = new Map(); // name → mention (deduplicated)
+
+  // 1. Parse "Attendees:" line
+  const attendeesMatch = body.match(ATTENDEES_LINE_RE);
+  if (attendeesMatch) {
+    const entriesText = attendeesMatch[1];
+    const entries = splitAttendeeEntries(entriesText);
+    for (const entry of entries) {
+      const mention = parseAttendeeEntry(entry);
+      if (mention.name && !mentions.has(mention.name)) {
+        mentions.set(mention.name, mention);
+      }
+    }
+  }
+
+  // 2. Extract explicit [[wikilinks]] — target treated as the person name
+  for (const match of body.matchAll(WIKILINK_RE)) {
+    const name = match[1].trim();
+    if (!mentions.has(name)) {
+      mentions.set(name, { name });
+    }
+  }
+
+  return [...mentions.values()];
+}
+
+// ---------------------------------------------------------------------------
+// Name normalisation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalise a person name for comparison:
+ * lowercase, trim, collapse internal whitespace.
+ */
+export function normalizeName(name) {
+  return name.toLowerCase().trim().replace(/\s+/g, " ");
+}
+
+/**
+ * Check if two normalised names are an exact match.
+ */
+export function isExactMatch(a, b) {
+  return normalizeName(a) === normalizeName(b);
+}
+
+/**
+ * Check if `candidate` is a possible duplicate of `existing`:
+ * - Same-surname + same first initial, OR same-firstname + initial surname
+ *   e.g. "Dana S." ~ "Dana Smith"  (first matches, last is initial of last)
+ *        "D. Smith" ~ "Dana Smith" (first is initial of first, last matches)
+ * Does NOT auto-merge — returns true only when ambiguous, not identical.
+ */
+export function isPossibleDuplicate(candidate, existing) {
+  const c = normalizeName(candidate).split(" ");
+  const e = normalizeName(existing).split(" ");
+  if (c.length < 1 || e.length < 1) return false;
+
+  // Exact match is not a "possible duplicate" — it's a real match
+  if (isExactMatch(candidate, existing)) return false;
+
+  if (c.length < 2 || e.length < 2) return false;
+
+  const cFirst = c[0];
+  const cLast  = c[c.length - 1];
+  const eFirst = e[0];
+  const eLast  = e[e.length - 1];
+
+  /**
+   * isInitialOf(abbr, full): true if abbr is a single-letter abbreviation of full.
+   *   "s."  → "smith"  (s matches first char of smith)
+   *   "d."  → "dana"
+   */
+  function isInitialOf(abbr, full) {
+    const a = abbr.replace(/\.$/, "");
+    return a.length === 1 && full.startsWith(a);
+  }
+
+  // Case A: "Dana S." ~ "Dana Smith"
+  //   first names match (or one is initial of other), last of candidate is initial of last of existing
+  const firstsMatch  = cFirst === eFirst || isInitialOf(cFirst, eFirst) || isInitialOf(eFirst, cFirst);
+  const lastInitialA = isInitialOf(cLast, eLast) || isInitialOf(eLast, cLast);
+
+  // Case B: "D. Smith" ~ "Dana Smith"
+  //   first of candidate is initial, last names match exactly
+  const firstInitialB = isInitialOf(cFirst, eFirst) || isInitialOf(eFirst, cFirst);
+  const lastsMatchB   = cLast === eLast;
+
+  return (firstsMatch && lastInitialA) || (firstInitialB && lastsMatchB);
+}
+
+export default defaultEntityExtractor;