@kontourai/flow-agents 2.4.0 → 3.0.0

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;

package/kits/knowledge/providers/work-item/index.js

@@ -0,0 +1,204 @@
+/**
+ * work-item knowledge-store provider (source/sink adapter, not storage).
+ *
+ * Maps a GitHub issue backlog into the typed graph so backlog hygiene becomes a
+ * knowledge-health pass:
+ *   - issues                         -> `issue` nodes (state / labels / title).
+ *   - flow-agents:work-item-metadata `blockers` -> `blocks` edges.
+ *   - prose "blocked by #N"          -> `blocks` edges; other #N refs -> `relates`.
+ *
+ * Reads via an INJECTABLE runner so tests drive it from recorded fixtures and
+ * never touch the real board. Write side is proposals-only: proposeWrite renders
+ * a draft issue comment / label change for an operator to file — it never calls
+ * a mutating gh command.
+ *
+ * @module providers/work-item
+ */
+
+import { execFile } from "node:child_process";
+import { node, edge, proposal, provenance } from "../lib/model.js";
+
+const PROVIDER_ID = "work-item";
+
+/** Default runner: shells out to `gh` (read-only list). */
+function defaultRunner(args) {
+  return new Promise((resolve, reject) => {
+    execFile("gh", args, { maxBuffer: 32 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) return reject(new Error(`gh ${args.join(" ")} failed: ${stderr || err.message}`));
+      resolve(stdout);
+    });
+  });
+}
+
+/** Parse the flow-agents:work-item-metadata JSON block from an issue body. */
+export function parseWorkItemMetadata(body) {
+  if (!body) return null;
+  const start = body.indexOf("flow-agents:work-item-metadata");
+  if (start === -1) return null;
+  const jsonStart = body.indexOf("{", start);
+  const end = body.indexOf("-->", jsonStart);
+  if (jsonStart === -1 || end === -1) return null;
+  try {
+    return JSON.parse(body.slice(jsonStart, end).trim());
+  } catch {
+    return null;
+  }
+}
+
+/** Extract a blocker issue number from a metadata blocker entry. */
+function blockerNumber(entry) {
+  if (typeof entry === "number") return entry;
+  if (typeof entry === "string") {
+    const m = entry.match(/#?(\d+)/);
+    return m ? Number(m[1]) : null;
+  }
+  if (entry && typeof entry === "object") {
+    if (typeof entry.number === "number") return entry.number;
+    if (typeof entry.issue === "number") return entry.issue;
+    if (typeof entry.ref === "string") {
+      const m = entry.ref.match(/#?(\d+)/);
+      return m ? Number(m[1]) : null;
+    }
+  }
+  return null;
+}
+
+export class WorkItemProvider {
+  constructor({ repo, runner, agent } = {}) {
+    this.repo = repo || "";
+    this.runner = runner || defaultRunner;
+    this.agent = agent;
+    this.id = PROVIDER_ID;
+    this._cache = null;
+  }
+
+  capabilities() {
+    return {
+      id: PROVIDER_ID,
+      node_types: ["issue"],
+      edge_types: ["blocks", "relates"],
+      writable: false,
+      write_mode: "proposals-only",
+      proposal_targets: ["comment", "label"],
+      source_of_truth: "GitHub issues (read via gh; write = draft comments/labels)",
+    };
+  }
+
+  async _issues() {
+    if (this._cache) return this._cache;
+    const args = ["issue", "list"];
+    if (this.repo) args.push("--repo", this.repo);
+    args.push("--state", "all", "--json", "number,title,state,labels,body", "--limit", "200");
+    const out = await this.runner(args);
+    const parsed = JSON.parse(out);
+    this._cache = Array.isArray(parsed) ? parsed : [];
+    return this._cache;
+  }
+
+  async readNodes(options = {}) {
+    const issues = await this._issues();
+    const now = new Date().toISOString();
+    const nodes = issues.map((iss) =>
+      node({
+        id: `issue:${iss.number}`,
+        type: "issue",
+        title: iss.title || `issue #${iss.number}`,
+        body: iss.body || "",
+        attributes: {
+          number: iss.number,
+          state: iss.state || "OPEN",
+          labels: (iss.labels || []).map((l) => (typeof l === "string" ? l : l.name)),
+        },
+        provenance: provenance({
+          provider: PROVIDER_ID,
+          source: this.repo ? `${this.repo}#${iss.number}` : `#${iss.number}`,
+          retrievedAt: now,
+          agent: this.agent,
+        }),
+      }),
+    );
+    if (options.type) return nodes.filter((n) => n.type === options.type);
+    return nodes;
+  }
+
+  async readEdges() {
+    const issues = await this._issues();
+    const now = new Date().toISOString();
+    const edges = [];
+    const seen = new Set();
+    const push = (e) => {
+      if (seen.has(e.id)) return;
+      seen.add(e.id);
+      edges.push(e);
+    };
+
+    for (const iss of issues) {
+      const self = `issue:${iss.number}`;
+      const prov = (loc) => provenance({ provider: PROVIDER_ID, source: this.repo ? `${this.repo}#${iss.number}` : `#${iss.number}`, locator: loc, retrievedAt: now, agent: this.agent });
+
+      // metadata blockers -> blocks (blocker blocks this)
+      const md = parseWorkItemMetadata(iss.body);
+      for (const b of (md && Array.isArray(md.blockers) ? md.blockers : [])) {
+        const n = blockerNumber(b);
+        if (n == null) continue;
+        push(edge({ id: `issue:${n}--blocks--${iss.number}`, type: "blocks", from: `issue:${n}`, to: self, attributes: { origin: "metadata" }, provenance: prov("metadata.blockers") }));
+      }
+
+      const body = iss.body || "";
+      // prose "blocked by #N" / "depends on #N" -> blocks
+      for (const m of body.matchAll(/\b(?:blocked by|depends on|blocker:)\s*#(\d+)/gi)) {
+        const n = Number(m[1]);
+        push(edge({ id: `issue:${n}--blocks--${iss.number}`, type: "blocks", from: `issue:${n}`, to: self, attributes: { origin: "prose" }, provenance: prov("body.prose") }));
+      }
+      // other bare #N prose refs -> relates
+      for (const m of body.matchAll(/(?<![\w/])#(\d+)\b/g)) {
+        const n = Number(m[1]);
+        if (n === iss.number) continue;
+        const bid = `issue:${iss.number}--relates--${n}`;
+        if (seen.has(`issue:${n}--blocks--${iss.number}`)) continue; // already a stronger blocks edge
+        push(edge({ id: bid, type: "relates", from: self, to: `issue:${n}`, attributes: { origin: "prose" }, provenance: prov("body.prose") }));
+      }
+    }
+    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 an issue comment or label change. Renders the draft an operator
+   * would file with gh — the provider never runs a mutating gh command.
+   */
+  async proposeWrite(intent = {}) {
+    const { issue, kind = "comment", commentBody, labels = [] } = intent;
+    if (issue == null) throw new Error("work-item proposeWrite requires intent.issue (number)");
+    if (kind === "label") {
+      return proposal({
+        provider: PROVIDER_ID,
+        kind: "label",
+        target: { repo: this.repo, issue },
+        payload: { labels },
+        rendered: `gh issue edit ${issue}${this.repo ? ` --repo ${this.repo}` : ""} ${labels.map((l) => `--add-label ${JSON.stringify(l)}`).join(" ")}`,
+        rationale: intent.rationale || "Proposed label change (draft — operator files it).",
+        provenance: provenance({ provider: PROVIDER_ID, source: this.repo ? `${this.repo}#${issue}` : `#${issue}`, agent: this.agent }),
+      });
+    }
+    return proposal({
+      provider: PROVIDER_ID,
+      kind: "comment",
+      target: { repo: this.repo, issue },
+      payload: { body: commentBody || "" },
+      rendered: `gh issue comment ${issue}${this.repo ? ` --repo ${this.repo}` : ""} --body ${JSON.stringify(commentBody || "")}`,
+      rationale: intent.rationale || "Proposed issue comment (draft — operator files it).",
+      provenance: provenance({ provider: PROVIDER_ID, source: this.repo ? `${this.repo}#${issue}` : `#${issue}`, agent: this.agent }),
+    });
+  }
+}
+
+export default WorkItemProvider;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "2.4.0",
+  "version": "3.0.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
@@ -110,6 +110,8 @@
     "workflow:sidecar": "npm run build --silent && node build/src/cli/workflow-sidecar.js",
     "workflow:validate-artifacts": "npm run build --silent && node build/src/cli/validate-workflow-artifacts.js",
     "effective-backlog-settings": "npm run build --silent && node build/src/cli.js effective-backlog-settings",
+    "assignment-provider": "npm run build --silent && node build/src/cli.js assignment-provider",
+    "effective-assignment-provider-settings": "npm run build --silent && node build/src/cli.js effective-assignment-provider-settings",
     "pull-work-provider": "npm run build --silent && node build/src/cli.js pull-work-provider",
     "publish-change": "npm run build --silent && node build/src/cli.js publish-change",
     "promote-workflow-artifact": "npm run build --silent && node build/src/cli.js promote-workflow-artifact",
@@ -141,7 +143,7 @@
     "kit": "npm run build --silent && node build/src/cli.js kit"
   },
   "devDependencies": {
-    "@types/node": "^26.0.1",
+    "@types/node": "^26.1.0",
     "promptfoo": "^0.121.17",
     "typescript": "^6.0.3"
   },

package/schemas/assignment-provider-settings.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flow-agents.dev/schemas/assignment-provider-settings.schema.json",
+  "title": "Flow Agents Assignment Provider Settings",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schema_version": { "const": "1.0" },
+    "defaults": { "$ref": "#/$defs/assignment_settings" },
+    "projects": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/project_assignment_settings" }
+    }
+  },
+  "anyOf": [{ "required": ["defaults"] }, { "required": ["projects"] }],
+  "$defs": {
+    "project_assignment_settings": {
+      "allOf": [
+        { "$ref": "#/$defs/assignment_settings" },
+        { "type": "object", "required": ["project"] }
+      ]
+    },
+    "assignment_settings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "policy"],
+      "properties": {
+        "project": { "$ref": "#/$defs/project_match" },
+        "provider": { "$ref": "#/$defs/provider" },
+        "policy": { "$ref": "#/$defs/policy" }
+      }
+    },
+    "project_match": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repo"],
+      "properties": {
+        "repo": { "$ref": "#/$defs/repo" },
+        "paths": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "provider": {
+      "oneOf": [
+        { "$ref": "#/$defs/github_provider" },
+        { "$ref": "#/$defs/local_file_provider" }
+      ]
+    },
+    "github_provider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "repo", "capabilities"],
+      "properties": {
+        "kind": { "const": "github" },
+        "repo": { "$ref": "#/$defs/repo" },
+        "capabilities": { "$ref": "#/$defs/capabilities" }
+      }
+    },
+    "local_file_provider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "capabilities"],
+      "properties": {
+        "kind": { "const": "local-file" },
+        "capabilities": { "$ref": "#/$defs/capabilities" }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label_name", "claim_comment_marker", "human_assignee_policy"],
+      "properties": {
+        "label_name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Label attached to a claimed subject on providers that support labels. Default: \"agent:claimed\"."
+        },
+        "claim_comment_marker": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Fixed marker used to locate the machine-readable claim comment among human comments. Default: \"<!-- flow-agents:assignment-claim -->\"."
+        },
+        "human_assignee_policy": { "$ref": "#/$defs/human_assignee_policy" },
+        "comment_refresh_on_phase_transition": {
+          "type": "boolean",
+          "description": "Whether an explicit render-claim/render-supersede call at a phase transition also refreshes the claim comment body. Default: false. No new mechanism; this reuses the same render path already built for claim."
+        }
+      }
+    },
+    "human_assignee_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["behavior", "idle_threshold_days"],
+      "properties": {
+        "behavior": {
+          "enum": ["ask_first", "never_reclaim"],
+          "description": "Default: \"ask_first\". A human assignee is never auto-superseded regardless of this value; this knob only governs whether idle human assignments are ever surfaced for possible reclaim confirmation (ask_first) or left untouched (never_reclaim)."
+        },
+        "idle_threshold_days": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Days of no linked activity before an idle human assignment is surfaced for confirmation. Default: 3."
+        }
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "enum": ["assignees", "labels", "comments"]
+      },
+      "uniqueItems": true
+    },
+    "repo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["owner", "name"],
+      "properties": {
+        "owner": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "url": { "type": "string" }
+      }
+    }
+  }
+}