@kontourai/flow-agents 2.3.0 → 3.0.0

package/kits/knowledge/providers/health/index.js

@@ -0,0 +1,153 @@
+/**
+ * Provider-agnostic knowledge-health verbs.
+ *
+ * Each verb takes a graph ({ nodes, edges }) produced by ANY provider that
+ * implements the read side of the knowledge-store contract and returns a
+ * schema-valid Knowledge Health Report (schemas/knowledge/health-report.schema.json).
+ * The verbs never inspect provider internals — that is what lets the SAME health
+ * command run identically over the vault, git-repo, and work-item providers
+ * (AC1, AC2, R4).
+ *
+ * @module providers/health
+ */
+
+import { loadSchemas } from "../lib/model.js";
+import { assertValid } from "../lib/schema-validate.js";
+
+const { healthReport: HEALTH_SCHEMA } = loadSchemas();
+
+/** Normalise a title into a comparable token set. */
+function tokenize(title) {
+  return new Set(
+    String(title || "")
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, " ")
+      .split(/\s+/)
+      .filter(Boolean),
+  );
+}
+
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+  let inter = 0;
+  for (const t of a) if (b.has(t)) inter++;
+  const union = a.size + b.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+
+function finalize(report) {
+  report.summary.finding_count = report.findings.length;
+  assertValid(report, HEALTH_SCHEMA, `health report (${report.check})`);
+  return report;
+}
+
+/**
+ * Duplicate detection: flag node PAIRS whose titles are the same or highly
+ * similar (token Jaccard >= threshold). Scoped to same-type pairs by default so
+ * a decision and an issue with a shared word are not conflated.
+ *
+ * @param {{nodes: object[], edges: object[]}} graph
+ * @param {object} [options]
+ * @param {string} [options.provider="unknown"]
+ * @param {number} [options.threshold=0.7]
+ * @param {boolean} [options.crossType=false] compare across node types when true
+ * @param {string} [options.generatedAt]
+ */
+export function detectDuplicates(graph, options = {}) {
+  const nodes = graph.nodes || [];
+  const edges = graph.edges || [];
+  const threshold = typeof options.threshold === "number" ? options.threshold : 0.7;
+  const crossType = options.crossType === true;
+
+  const report = {
+    schema_version: "1.0",
+    check: "duplicate-detection",
+    provider: options.provider || "unknown",
+    generated_at: options.generatedAt || new Date().toISOString(),
+    summary: { nodes_examined: nodes.length, edges_examined: edges.length, finding_count: 0 },
+    findings: [],
+  };
+
+  const tokenized = nodes.map((n) => ({ node: n, tokens: tokenize(n.title) }));
+  for (let i = 0; i < tokenized.length; i++) {
+    for (let j = i + 1; j < tokenized.length; j++) {
+      const a = tokenized[i];
+      const b = tokenized[j];
+      if (!crossType && a.node.type !== b.node.type) continue;
+      const score = jaccard(a.tokens, b.tokens);
+      if (score >= threshold) {
+        report.findings.push({
+          kind: "duplicate-nodes",
+          severity: "warning",
+          node_ids: [a.node.id, b.node.id],
+          message: `Possible duplicate ${a.node.type} nodes: "${a.node.title}" ~ "${b.node.title}" (similarity ${score.toFixed(2)})`,
+          evidence: {
+            similarity: Number(score.toFixed(4)),
+            threshold,
+            title_a: a.node.title,
+            title_b: b.node.title,
+            type: a.node.type,
+          },
+        });
+      }
+    }
+  }
+  return finalize(report);
+}
+
+/**
+ * Dependency-link integrity: flag dependency edges whose endpoints do not
+ * resolve to a node present in the graph. An edge marked resolved:false is a
+ * deliberate external reference and is skipped.
+ *
+ * @param {{nodes: object[], edges: object[]}} graph
+ * @param {object} [options]
+ * @param {string} [options.provider="unknown"]
+ * @param {string[]} [options.dependencyTypes=["blocks"]] edge types treated as dependency links
+ * @param {string} [options.generatedAt]
+ */
+export function checkDependencyLinkIntegrity(graph, options = {}) {
+  const nodes = graph.nodes || [];
+  const edges = graph.edges || [];
+  const depTypes = new Set(options.dependencyTypes || ["blocks"]);
+  const ids = new Set(nodes.map((n) => n.id));
+
+  const report = {
+    schema_version: "1.0",
+    check: "dependency-link-integrity",
+    provider: options.provider || "unknown",
+    generated_at: options.generatedAt || new Date().toISOString(),
+    summary: { nodes_examined: nodes.length, edges_examined: edges.length, finding_count: 0 },
+    findings: [],
+  };
+
+  for (const e of edges) {
+    if (!depTypes.has(e.type)) continue;
+    if (e.resolved === false) continue; // deliberate external ref
+    const sourceMissing = !ids.has(e.from);
+    const targetMissing = !ids.has(e.to);
+    if (!sourceMissing && !targetMissing) continue;
+    report.findings.push({
+      kind: "broken-dependency-link",
+      severity: "error",
+      edge_ids: [e.id],
+      node_ids: [e.from, e.to],
+      message: `Broken ${e.type} link ${e.from} -> ${e.to}: ${
+        targetMissing ? `target '${e.to}' not found` : ""
+      }${targetMissing && sourceMissing ? "; " : ""}${sourceMissing ? `source '${e.from}' not found` : ""}`.trim(),
+      evidence: {
+        edge_type: e.type,
+        from: e.from,
+        to: e.to,
+        source_missing: sourceMissing,
+        target_missing: targetMissing,
+      },
+    });
+  }
+  return finalize(report);
+}
+
+export const HEALTH_VERBS = Object.freeze({
+  "duplicate-detection": detectDuplicates,
+  "dependency-link-integrity": checkDependencyLinkIntegrity,
+});

package/kits/knowledge/providers/index.js

@@ -0,0 +1,24 @@
+/**
+ * Knowledge Kit store providers — public entry point.
+ *
+ * Typed graph model (nodes / edges / provenance) with pluggable providers behind
+ * one read + proposals-only write interface, plus provider-agnostic health verbs.
+ * See context/contracts/knowledge-store-contract.md.
+ *
+ * @module providers
+ */
+
+export { MarkdownVaultProvider } from "./markdown-vault/index.js";
+export { GitRepoProvider } from "./git-repo/index.js";
+export { WorkItemProvider, parseWorkItemMetadata } from "./work-item/index.js";
+export { detectDuplicates, checkDependencyLinkIntegrity, HEALTH_VERBS } from "./health/index.js";
+export {
+  EDGE_TYPES,
+  CORE_NODE_TYPES,
+  loadSchemas,
+  node,
+  edge,
+  proposal,
+  provenance,
+} from "./lib/model.js";
+export { validate, assertValid } from "./lib/schema-validate.js";

package/kits/knowledge/providers/lib/model.js

@@ -0,0 +1,91 @@
+/**
+ * Knowledge graph model helpers: node / edge / proposal / provenance
+ * constructors, the closed edge-type vocabulary, the recommended node-type
+ * vocabulary, and loaders for the JSON schemas that define them.
+ *
+ * @module providers/lib/model
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_DIR = path.resolve(__dirname, "../../../../schemas/knowledge");
+
+/** Closed vocabulary of edge types (schema-enforced). */
+export const EDGE_TYPES = Object.freeze([
+  "supersedes",
+  "merged-into",
+  "blocks",
+  "evidence-of",
+  "mentions",
+  "relates",
+]);
+
+/** Recommended core node types. EXTENSIBLE — providers may emit others. */
+export const CORE_NODE_TYPES = Object.freeze([
+  "note",
+  "decision",
+  "issue",
+  "session",
+  "person",
+]);
+
+let _schemaCache = null;
+/** Load and cache the four graph schemas. */
+export function loadSchemas() {
+  if (_schemaCache) return _schemaCache;
+  const read = (name) => JSON.parse(fs.readFileSync(path.join(SCHEMA_DIR, name), "utf8"));
+  _schemaCache = {
+    node: read("node.schema.json"),
+    edge: read("edge.schema.json"),
+    proposal: read("proposal.schema.json"),
+    healthReport: read("health-report.schema.json"),
+  };
+  return _schemaCache;
+}
+
+/** Build a provenance object. */
+export function provenance({ provider, source, locator, retrievedAt, agent }) {
+  const p = {
+    provider,
+    source,
+    retrieved_at: retrievedAt || new Date().toISOString(),
+  };
+  if (locator) p.locator = locator;
+  if (agent) p.agent = agent;
+  return p;
+}
+
+/** Build a node. Omits empty optional fields so schema additionalProperties holds. */
+export function node({ id, type, title, body, attributes, provenance: prov }) {
+  const n = { id, type, title, provenance: prov };
+  if (body !== undefined) n.body = body;
+  if (attributes && Object.keys(attributes).length) n.attributes = attributes;
+  return n;
+}
+
+/** Build an edge. `resolved` defaults to true (an internal dependency link). */
+export function edge({ id, type, from, to, resolved, attributes, provenance: prov }) {
+  const e = { id, type, from, to, provenance: prov };
+  if (resolved === false) e.resolved = false;
+  if (attributes && Object.keys(attributes).length) e.attributes = attributes;
+  return e;
+}
+
+/** Build a proposal. status is always "proposed" — proposals-only by construction. */
+export function proposal({ provider, kind, target, payload, rendered, rationale, provenance: prov }) {
+  const p = {
+    schema_version: "1.0",
+    provider,
+    kind,
+    target: target || {},
+    status: "proposed",
+    provenance: prov,
+  };
+  if (payload) p.payload = payload;
+  if (rendered !== undefined) p.rendered = rendered;
+  if (rationale) p.rationale = rationale;
+  return p;
+}

package/kits/knowledge/providers/lib/schema-validate.js

@@ -0,0 +1,119 @@
+/**
+ * Minimal, dependency-free JSON-Schema validator.
+ *
+ * Supports exactly the draft-07 subset used by the Knowledge Kit graph schemas
+ * (schemas/knowledge/*.schema.json): type, required, properties,
+ * additionalProperties:false, enum, const, items, minLength, minItems, integer,
+ * and local `$ref` into `#/$defs/*`. It is intentionally NOT a general validator
+ * — it exists so health reports and conformance tests can assert schema validity
+ * without pulling an external dependency (the same zero-dep discipline the
+ * decision-registry validator follows).
+ *
+ * @module providers/lib/schema-validate
+ */
+
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+function matchesType(value, type) {
+  if (type === "integer") return typeof value === "number" && Number.isInteger(value);
+  if (type === "number") return typeof value === "number";
+  if (type === "object") return typeOf(value) === "object";
+  if (type === "array") return Array.isArray(value);
+  return typeOf(value) === type;
+}
+
+function resolveRef(ref, root) {
+  if (!ref.startsWith("#/")) throw new Error(`Unsupported $ref (only local #/ refs): ${ref}`);
+  const parts = ref.slice(2).split("/");
+  let node = root;
+  for (const part of parts) {
+    node = node && node[part];
+  }
+  if (!node) throw new Error(`Unresolved $ref: ${ref}`);
+  return node;
+}
+
+function validateNode(value, schema, root, pathStr, errors) {
+  if (schema.$ref) {
+    return validateNode(value, resolveRef(schema.$ref, root), root, pathStr, errors);
+  }
+
+  if ("const" in schema) {
+    if (value !== schema.const) {
+      errors.push(`${pathStr}: expected const ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`);
+    }
+  }
+
+  if (schema.enum) {
+    if (!schema.enum.includes(value)) {
+      errors.push(`${pathStr}: value ${JSON.stringify(value)} not in enum ${JSON.stringify(schema.enum)}`);
+    }
+  }
+
+  if (schema.type) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((t) => matchesType(value, t))) {
+      errors.push(`${pathStr}: expected type ${types.join("|")}, got ${typeOf(value)}`);
+      return; // further checks assume the type held
+    }
+  }
+
+  if (typeof value === "string") {
+    if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+      errors.push(`${pathStr}: string shorter than minLength ${schema.minLength}`);
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+      errors.push(`${pathStr}: array shorter than minItems ${schema.minItems}`);
+    }
+    if (schema.items) {
+      value.forEach((item, i) => validateNode(item, schema.items, root, `${pathStr}[${i}]`, errors));
+    }
+  }
+
+  if (typeOf(value) === "object") {
+    const props = schema.properties || {};
+    for (const req of schema.required || []) {
+      if (!(req in value)) errors.push(`${pathStr}: missing required property '${req}'`);
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(value)) {
+        if (!(key in props)) errors.push(`${pathStr}: unexpected property '${key}'`);
+      }
+    }
+    for (const [key, propSchema] of Object.entries(props)) {
+      if (key in value) {
+        validateNode(value[key], propSchema, root, `${pathStr}/${key}`, errors);
+      }
+    }
+  }
+}
+
+/**
+ * Validate `value` against `schema`.
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validate(value, schema) {
+  const errors = [];
+  validateNode(value, schema, schema, "$", errors);
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Assert validity, throwing a descriptive error when invalid. Handy in tests.
+ */
+export function assertValid(value, schema, label = "value") {
+  const { valid, errors } = validate(value, schema);
+  if (!valid) {
+    const err = new Error(`${label} failed schema validation:\n  ${errors.join("\n  ")}`);
+    err.code = "SCHEMA_INVALID";
+    err.errors = errors;
+    throw err;
+  }
+}

package/kits/knowledge/providers/markdown-vault/index.js

@@ -0,0 +1,169 @@
+/**
+ * markdown-vault knowledge-store provider.
+ *
+ * Adapts the existing Knowledge Kit store (the markdown-vault behaviour:
+ * markdown files + YAML frontmatter + [[wikilinks]] + a JSON graph index) to
+ * the knowledge-store PROVIDER contract (typed nodes/edges/provenance). It is a
+ * thin READ + PROPOSE wrapper over an existing store adapter instance — it does
+ * NOT reimplement or modify the adapter, so existing Knowledge Kit skills are
+ * unaffected. Wikilinks/frontmatter remain the native form; proposeWrite renders
+ * a new note in exactly that form for a human to file.
+ *
+ * @module providers/markdown-vault
+ */
+
+import { node, edge, proposal, provenance } from "../lib/model.js";
+import DefaultKnowledgeStore from "../../adapters/default-store/index.js";
+
+const PROVIDER_ID = "markdown-vault";
+
+/** Vault record type -> graph node type. Extensible: unknowns fall back to note. */
+function nodeTypeFor(recordType) {
+  return recordType === "person" ? "person" : "note";
+}
+
+/** Vault link kind -> closed graph edge type. */
+function edgeTypeFor(linkKind) {
+  switch (linkKind) {
+    case "supersedes":
+    case "refines":
+      return "supersedes";
+    case "source":
+    case "example":
+      return "evidence-of";
+    case "appears-in":
+    case "person":
+      return "mentions";
+    case "proposes":
+    case "related":
+    default:
+      return "relates";
+  }
+}
+
+const ALL_RECORD_TYPES = ["raw", "compiled", "concept", "snapshot", "person"];
+
+export class MarkdownVaultProvider {
+  constructor({ store, storeRoot, agent } = {}) {
+    if (!store && !storeRoot) {
+      throw new Error("MarkdownVaultProvider requires { store } or { storeRoot }");
+    }
+    this.store = store || new DefaultKnowledgeStore({ storeRoot });
+    this.storeRoot = storeRoot || "(injected store)";
+    this.agent = agent;
+    this.id = PROVIDER_ID;
+  }
+
+  capabilities() {
+    return {
+      id: PROVIDER_ID,
+      node_types: ["note", "person"],
+      edge_types: ["supersedes", "evidence-of", "mentions", "relates"],
+      writable: false,
+      write_mode: "proposals-only",
+      proposal_targets: ["create-node"],
+      source_of_truth: "human-curated markdown vault",
+    };
+  }
+
+  async _allRecords() {
+    const out = [];
+    for (const t of ALL_RECORD_TYPES) {
+      const recs = await this.store.listByType(t, { includeRetired: true });
+      for (const r of recs) out.push(r);
+    }
+    return out;
+  }
+
+  async readNodes(options = {}) {
+    const records = await this._allRecords();
+    const nodes = records.map((r) => {
+      const attributes = { record_type: r.type };
+      if (r.category) attributes.category = r.category;
+      if (r.status) attributes.status = r.status;
+      if (Array.isArray(r.tags) && r.tags.length) attributes.tags = r.tags;
+      return node({
+        id: r.id,
+        type: nodeTypeFor(r.type),
+        title: r.title,
+        body: typeof r.body === "string" ? r.body : "",
+        attributes,
+        provenance: provenance({
+          provider: PROVIDER_ID,
+          source: `${this.storeRoot}#${r.id}`,
+          locator: r.type,
+          agent: this.agent,
+        }),
+      });
+    });
+    if (options.type) return nodes.filter((n) => n.type === options.type);
+    return nodes;
+  }
+
+  async readEdges() {
+    const records = await this._allRecords();
+    const edges = [];
+    for (const r of records) {
+      const links = await this.store.getLinks(r.id);
+      for (const l of links.forward || []) {
+        edges.push(
+          edge({
+            id: `${r.id}--${l.kind}--${l.target_id}`,
+            type: edgeTypeFor(l.kind),
+            from: r.id,
+            to: l.target_id,
+            attributes: { vault_link_kind: l.kind },
+            provenance: provenance({
+              provider: PROVIDER_ID,
+              source: `${this.storeRoot}#${r.id}`,
+              locator: `links.${l.kind}`,
+              agent: this.agent,
+            }),
+          }),
+        );
+      }
+    }
+    return edges;
+  }
+
+  async queryByType(type) {
+    return this.readNodes({ type });
+  }
+
+  async readGraph() {
+    const [nodes, edges] = await Promise.all([this.readNodes(), this.readEdges()]);
+    return { nodes, edges };
+  }
+
+  /**
+   * Propose a new vault note. Renders the native markdown-vault form
+   * (frontmatter + [[wikilinks]]) WITHOUT touching the store — proposals only.
+   */
+  async proposeWrite(intent = {}) {
+    const { title, body = "", category = "inbox", tags = [], links = [] } = intent;
+    if (!title) throw new Error("markdown-vault proposeWrite requires intent.title");
+    const wikilinks = links.map((l) => `[[${l.target_id}${l.label ? `|${l.label}` : ""}]]`).join(" ");
+    const fm = [
+      "---",
+      "type: compiled",
+      `title: ${title}`,
+      `category: ${category}`,
+      tags.length ? `tags: [${tags.join(", ")}]` : "tags: []",
+      "---",
+      "",
+      body,
+      wikilinks ? `\n${wikilinks}` : "",
+    ].join("\n");
+    return proposal({
+      provider: PROVIDER_ID,
+      kind: "create-node",
+      target: { store_root: this.storeRoot, category },
+      payload: { type: "note", title, body, category, tags, links },
+      rendered: fm,
+      rationale: intent.rationale || "Proposed vault note (file it via the Knowledge Kit ingest/compile flow).",
+      provenance: provenance({ provider: PROVIDER_ID, source: this.storeRoot, agent: this.agent }),
+    });
+  }
+}
+
+export default MarkdownVaultProvider;