@kontourai/flow-agents 0.1.1 → 0.1.2

package/src/cli/utterance-check.ts

@@ -0,0 +1,254 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { flagBool, flagString, parseArgs } from "../lib/args.js";
+
+// ---------------------------------------------------------------------------
+// Output types
+// ---------------------------------------------------------------------------
+
+interface StatementResult {
+  excerpt: string;
+  badge: string;
+  target: { subjectType: string; subjectId: string; fieldOrBehavior: string };
+  span?: { start: number; end: number };
+}
+
+interface UtteranceReport {
+  status: "ok" | "not_configured" | "error";
+  agent_id: string;
+  utterance_excerpt: string;
+  statements: StatementResult[];
+  summary: string;
+}
+
+// ---------------------------------------------------------------------------
+// Survey module interface (mirrors @kontourai/survey exported shapes)
+// ---------------------------------------------------------------------------
+
+interface SurveyExtractedItem {
+  target: { subjectType: string; subjectId: string; fieldOrBehavior: string };
+  value?: unknown;
+  excerpt: string;
+  span?: { start: number; end: number };
+  confidence: number;
+}
+
+interface SurveyExtractor {
+  name: string;
+  extract(utterance: string): SurveyExtractedItem[] | Promise<SurveyExtractedItem[]>;
+}
+
+interface SurveyStatementItem {
+  excerpt: string;
+  badge: string;
+  target: { subjectType: string; subjectId: string; fieldOrBehavior: string };
+  span?: { start: number; end: number };
+  inquiryRecord: Record<string, unknown>;
+}
+
+interface SurveyTrustReport {
+  source: Record<string, unknown>;
+  statements: SurveyStatementItem[];
+}
+
+interface SurveyMod {
+  surveyAgentUtterance: (
+    utterance: string,
+    extractor: SurveyExtractor,
+    context: { bundle: Record<string, unknown>; agentId: string; now?: Date }
+  ) => Promise<SurveyTrustReport>;
+  referenceUtteranceExtractor: SurveyExtractor;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function usage(): void {
+  console.error(
+    [
+      "usage: flow-agents utterance-check check [options]",
+      "",
+      "Check an agent utterance for evidence coverage using @kontourai/survey.",
+      "Requires @kontourai/survey to be installed in the target workspace.",
+      "",
+      "Options:",
+      "  --utterance TEXT      Utterance text to check (required unless --not-configured).",
+      "  --bundle-path FILE    Trust bundle JSON file. Omit for an empty bundle (all unsupported).",
+      "  --agent-id ID         Agent identifier for provenance (default: flow-agents-utterance-check).",
+      "  --not-configured      Skip survey call; output not_configured without error.",
+      "  --strict              Exit non-zero when any badge is disputed, rejected, or unsupported.",
+      "  --help                Show this help.",
+    ].join("\n")
+  );
+}
+
+function excerptText(text: string, maxLen = 200): string {
+  const trimmed = text.trim().replace(/\s+/g, " ");
+  return trimmed.length > maxLen ? `${trimmed.slice(0, maxLen - 3)}...` : trimmed;
+}
+
+function badgeSummary(statements: StatementResult[]): string {
+  if (statements.length === 0) return "no factual statements extracted";
+  const counts: Record<string, number> = {};
+  for (const s of statements) {
+    counts[s.badge] = (counts[s.badge] ?? 0) + 1;
+  }
+  return Object.entries(counts)
+    .sort((a, b) => b[1] - a[1])
+    .map(([badge, n]) => `${badge}:${n}`)
+    .join(", ");
+}
+
+function hasConcerningBadge(badge: string): boolean {
+  return badge === "disputed" || badge === "rejected" || badge === "unsupported";
+}
+
+async function loadSurvey(): Promise<SurveyMod | undefined> {
+  try {
+    const pkg = "@kontourai/survey";
+    // Dynamic import avoids a static dependency on @kontourai/survey —
+    // the same pattern survey/src/anthropic.ts uses for @anthropic-ai/sdk.
+    const mod = await (Function("m", "return import(m)")(pkg) as Promise<unknown>);
+    return mod as SurveyMod;
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core check logic
+// ---------------------------------------------------------------------------
+
+async function runCheck(argv: string[]): Promise<number> {
+  const { flags } = parseArgs(argv);
+
+  if (flagBool(flags, "help")) {
+    usage();
+    return 0;
+  }
+
+  const agentId = flagString(flags, "agent-id") ?? "flow-agents-utterance-check";
+  const notConfigured = flagBool(flags, "not-configured");
+  const strict = flagBool(flags, "strict");
+
+  if (notConfigured) {
+    const report: UtteranceReport = {
+      status: "not_configured",
+      agent_id: agentId,
+      utterance_excerpt: "",
+      statements: [],
+      summary: "@kontourai/survey is not configured for this workspace.",
+    };
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return 0;
+  }
+
+  const utterance = flagString(flags, "utterance");
+  if (!utterance) {
+    usage();
+    return 3;
+  }
+
+  const bundlePath = flagString(flags, "bundle-path");
+  let bundle: Record<string, unknown> = { claims: [] };
+  if (bundlePath) {
+    const resolved = path.resolve(bundlePath);
+    try {
+      const raw = fs.readFileSync(resolved, "utf8");
+      bundle = JSON.parse(raw) as Record<string, unknown>;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[UtteranceCheck] could not read bundle from ${resolved}: ${msg}\n`);
+    }
+  }
+
+  const survey = await loadSurvey();
+  if (!survey) {
+    const report: UtteranceReport = {
+      status: "not_configured",
+      agent_id: agentId,
+      utterance_excerpt: excerptText(utterance),
+      statements: [],
+      summary: "@kontourai/survey is not installed. Install it or run with --not-configured.",
+    };
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.stderr.write(
+      "[UtteranceCheck] not_configured: @kontourai/survey is not installed in this workspace.\n"
+    );
+    return 1;
+  }
+
+  const { surveyAgentUtterance, referenceUtteranceExtractor } = survey;
+
+  let trustReport: SurveyTrustReport;
+  try {
+    trustReport = await surveyAgentUtterance(utterance, referenceUtteranceExtractor, {
+      bundle,
+      agentId,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const report: UtteranceReport = {
+      status: "error",
+      agent_id: agentId,
+      utterance_excerpt: excerptText(utterance),
+      statements: [],
+      summary: `Survey call failed: ${msg}`,
+    };
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.stderr.write(`[UtteranceCheck] survey call failed: ${msg}\n`);
+    return 1;
+  }
+
+  const statements: StatementResult[] = trustReport.statements.map((s) => ({
+    excerpt: s.excerpt,
+    badge: s.badge,
+    target: s.target,
+    span: s.span,
+  }));
+
+  const summary = badgeSummary(statements);
+  const report: UtteranceReport = {
+    status: "ok",
+    agent_id: agentId,
+    utterance_excerpt: excerptText(utterance),
+    statements,
+    summary,
+  };
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+
+  const concerning = statements.filter((s) => hasConcerningBadge(s.badge));
+  if (concerning.length > 0) {
+    process.stderr.write(
+      `[UtteranceCheck] ${concerning.length} statement(s) lack evidence coverage: ${summary}\n`
+    );
+    for (const s of concerning.slice(0, 4)) {
+      process.stderr.write(`  - [${s.badge}] "${excerptText(s.excerpt, 100)}"\n`);
+    }
+  }
+
+  if (strict && concerning.length > 0) return 2;
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+export async function main(argv = process.argv.slice(2)): Promise<number> {
+  const [subcommand, ...rest] = argv;
+  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+    usage();
+    return 0;
+  }
+  if (subcommand !== "check") {
+    console.error(`Unknown utterance-check subcommand: ${subcommand}`);
+    usage();
+    return 3;
+  }
+  return runCheck(rest);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exit(await main());

package/src/cli.ts

@@ -19,6 +19,7 @@ import { main as validateSource } from "./tools/validate-source-tree.js";
 import { main as validatePackage } from "./tools/validate-package.js";
 import { main as validateHookInfluence } from "./cli/validate-hook-influence.js";
 import { main as runtimeAdapter } from "./cli/runtime-adapter.js";
+import { main as utteranceCheck } from "./cli/utterance-check.js";
 
 const availableCommands = new Map<string, (argv: string[]) => number | Promise<number>>([
   ["build-bundles", () => buildBundles()],
@@ -33,6 +34,7 @@ const availableCommands = new Map<string, (argv: string[]) => number | Promise<n
   ["publish-change", publishChange],
   ["pull-work-provider", pullWorkProvider],
   ["runtime-adapter", runtimeAdapter],
+  ["utterance-check", utteranceCheck],
   ["telemetry-doctor", telemetryDoctor],
   ["usage-feedback", usageFeedback],
   ["veritas-governance", veritasGovernance],
@@ -58,6 +60,7 @@ const aliases = new Map<string, string>([
   ["flow-agents-usage-feedback", "usage-feedback"],
   ["flow-agents-veritas-governance", "veritas-governance"],
   ["flow-agents-validate-hook-influence", "validate-hook-influence"],
+  ["flow-agents-utterance-check", "utterance-check"],
   ["flow-agents-validate-source", "validate-source"],
   ["flow-agents-workflow-artifact-cleanup-audit", "workflow-artifact-cleanup-audit"],
 ]);

package/src/tools/validate-source-tree.ts

@@ -68,6 +68,7 @@ const hookFilePolicies = new Map<string, { category: string; requiredNeedles: st
   ["scripts/hooks/report-only-guard.js", { category: "policy hook", requiredNeedles: ["Report-Only Guard Hook"] }],
   ["scripts/hooks/stop-format-typecheck.js", { category: "policy hook", requiredNeedles: ["Stop Hook", "typecheck"] }],
   ["scripts/hooks/stop-goal-fit.js", { category: "policy hook", requiredNeedles: ["Stop Hook", "Goal Fit"] }],
+  ["scripts/hooks/utterance-check.js", { category: "policy hook", requiredNeedles: ["Utterance Check Hook", "FLOW_AGENTS_UTTERANCE_CHECK_ENABLED"] }],
   ["scripts/hooks/workflow-steering.js", { category: "policy hook", requiredNeedles: ["Workflow Steering Hook"] }],
   ["scripts/hooks/desktop-notify.sh", { category: "local notification helper", requiredNeedles: ["desktop-notify.sh", "osascript"] }],
   ["scripts/hooks/lib/audit-transport.sh", { category: "shared hook library", requiredNeedles: ["audit_emit"] }],

package/build/src/cli/docs-preview.js

@@ -1,39 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-function esc(value) {
-    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
-function titleFor(file, text) {
-    return text.match(/^title:\s*(.+)$/m)?.[1].trim() ?? text.split(/\r?\n/).find((line) => line.startsWith("# "))?.slice(2).trim() ?? path.basename(file, ".md").replace(/-/g, " ");
-}
-function render(text) {
-    return text.replace(/^---\n.*?\n---\n/s, "").split(/\r?\n/).map((line) => {
-        if (line.startsWith("# "))
-            return `<h1>${esc(line.slice(2).trim())}</h1>`;
-        if (line.startsWith("## "))
-            return `<h2>${esc(line.slice(3).trim())}</h2>`;
-        if (line.startsWith("- "))
-            return `<li>${esc(line.slice(2).trim())}</li>`;
-        return line.trim() ? `<p>${esc(line.trim())}</p>` : "";
-    }).join("\n");
-}
-export function main() {
-    const root = path.resolve(path.dirname(process.argv[1]), "..");
-    const docs = path.join(root, "docs");
-    const out = path.join(root, "_site");
-    fs.rmSync(out, { recursive: true, force: true });
-    fs.mkdirSync(out, { recursive: true });
-    const assets = path.join(docs, "assets");
-    if (fs.existsSync(assets))
-        fs.cpSync(assets, path.join(out, "assets"), { recursive: true });
-    for (const file of fs.readdirSync(docs).filter((name) => name.endsWith(".md")).sort()) {
-        const source = path.join(docs, file);
-        const text = fs.readFileSync(source, "utf8");
-        const title = titleFor(file, text);
-        fs.writeFileSync(path.join(out, `${path.basename(file, ".md")}.html`), `<!doctype html><html><head><meta charset="utf-8"><title>${esc(title)}</title><link rel="stylesheet" href="assets/site.css"></head><body>${render(text)}<script src="assets/site.js" defer></script></body></html>`, "utf8");
-    }
-    console.log(`Built local docs preview: ${out}`);
-    return 0;
-}
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());

package/build/src/cli/export-bookmarks.js

@@ -1,38 +0,0 @@
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-function esc(value) {
-    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-}
-export function main(argv = process.argv.slice(2)) {
-    if (argv.length < 1) {
-        console.log("Usage: export-bookmarks <bookmarks.md> [output.html]");
-        return 1;
-    }
-    const input = argv[0];
-    const output = argv[1] ?? path.join(os.homedir(), "Downloads", "bookmarks_organized.html");
-    if (!fs.existsSync(input)) {
-        console.log(`Error: ${input} not found`);
-        return 1;
-    }
-    const links = Array.from(fs.readFileSync(input, "utf8").matchAll(/^- \*\*[\d-]+\*\* \[(\w+)\]: (.+?) — (https?:\/\/\S+)(?: — (.+))?$/gm), (m) => ({ tag: m[1], title: m[2], url: m[3] }));
-    const timestamp = Math.floor(Date.now() / 1000);
-    const byTag = new Map();
-    for (const link of links)
-        byTag.set(link.tag, [...(byTag.get(link.tag) ?? []), link]);
-    const lines = ["<!DOCTYPE NETSCAPE-Bookmark-file-1>", '<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">', "<TITLE>Bookmarks</TITLE>", "<H1>Bookmarks</H1>", "<DL><p>"];
-    for (const tag of Array.from(byTag.keys()).sort()) {
-        lines.push(`    <DT><H3 ADD_DATE="${timestamp}" LAST_MODIFIED="${timestamp}">${esc(tag)}</H3>`, "    <DL><p>");
-        for (const link of (byTag.get(tag) ?? []).sort((a, b) => a.title.localeCompare(b.title)))
-            lines.push(`        <DT><A HREF="${esc(link.url)}" ADD_DATE="${timestamp}">${esc(link.title)}</A>`);
-        lines.push("    </DL><p>");
-    }
-    lines.push("</DL><p>");
-    fs.writeFileSync(output, lines.join("\n"), "utf8");
-    console.log("Bookmarks exported");
-    console.log(`Source: ${input} (${links.length} links)`);
-    console.log(`Output: ${output}`);
-    return 0;
-}
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());

package/build/src/cli/import-bookmarks.js

@@ -1,50 +0,0 @@
-import * as fs from "node:fs";
-const SKIP = [/mail\.google\.com/i, /outlook\.(office|live)\.com/i, /calendar\.google\.com/i, /linkedin\.com\/in\//i, /slack\.com\/archives/i, /zoom\.us\/j\//i, /teams\.microsoft\.com/i];
-const TAGS = [[/github\.com|gitlab\.com|codecommit|code\.amazon/i, "repo"], [/docs\.|documentation|\/docs\/|readme|userguide|developer-guide/i, "docs"], [/wiki\.|\/wiki\/|confluence|runbook/i, "wiki"], [/dashboard|console\.|portal|admin\.|grafana|cloudwatch/i, "tool"], [/learn\.|training\.|course|certification|workshop|tutorial/i, "training"], [/template|boilerplate|starter|scaffold/i, "template"], [/spec\.|standard|architecture|rfc|design-doc/i, "reference"]];
-function inferTag(url) {
-    return TAGS.find(([pattern]) => pattern.test(url))?.[1] ?? "external";
-}
-function existingUrls(file) {
-    if (!fs.existsSync(file))
-        return new Set();
-    return new Set(Array.from(fs.readFileSync(file, "utf8").matchAll(/-->\s*(https?:\/\/\S+)|—\s+(https?:\/\/\S+)/g), (match) => match[1] ?? match[2]));
-}
-export function main(argv = process.argv.slice(2)) {
-    if (argv.length < 2) {
-        console.log("Usage: import-bookmarks <bookmarks.html> <bookmarks.md>");
-        return 1;
-    }
-    const [htmlPath, mdPath] = argv;
-    if (!fs.existsSync(htmlPath)) {
-        console.log(`Error: ${htmlPath} not found`);
-        return 1;
-    }
-    const html = fs.readFileSync(htmlPath, "utf8");
-    const bookmarks = Array.from(html.matchAll(/<A\b[^>]*HREF=["']([^"']+)["'][^>]*>(.*?)<\/A>/gi), (match) => ({ url: match[1], title: match[2].replace(/<[^>]+>/g, "").trim() }));
-    console.log(`Found ${bookmarks.length} bookmarks in HTML`);
-    const seen = existingUrls(mdPath);
-    console.log(`Found ${seen.size} existing entries in bookmarks.md`);
-    const today = new Date().toISOString().slice(0, 10);
-    const entries = [];
-    let skipped = 0;
-    let preserved = 0;
-    for (const bookmark of bookmarks) {
-        if (!/^https?:\/\//.test(bookmark.url) || SKIP.some((pattern) => pattern.test(bookmark.url))) {
-            skipped += 1;
-            continue;
-        }
-        if (seen.has(bookmark.url)) {
-            preserved += 1;
-            continue;
-        }
-        entries.push(`- **${today}** [${inferTag(bookmark.url)}]: ${bookmark.title} — ${bookmark.url} — (imported from browser)`);
-    }
-    if (entries.length)
-        fs.appendFileSync(mdPath, `${fs.existsSync(mdPath) ? "\n" : ""}${entries.join("\n")}\n`, "utf8");
-    console.log(`Added ${entries.length} new bookmarks`);
-    console.log(`Preserved ${preserved} existing bookmarks`);
-    console.log(`Skipped ${skipped} routine/non-http bookmarks`);
-    return 0;
-}
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());

package/build/src/cli/instinct-cli.js

@@ -1,93 +0,0 @@
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-const SOUL_PATH = process.env.SOUL_PATH ?? path.join(os.homedir(), ".soul");
-const INSTINCTS_DIR = path.join(SOUL_PATH, "knowledge", "instincts");
-function parse(file) {
-    const text = fs.readFileSync(file, "utf8");
-    if (!text.startsWith("---"))
-        return null;
-    const [, fm, body] = text.split("---", 3);
-    const meta = {};
-    for (const line of fm.trim().split(/\r?\n/)) {
-        const idx = line.indexOf(":");
-        if (idx === -1)
-            continue;
-        const key = line.slice(0, idx).trim();
-        const raw = line.slice(idx + 1).trim().replace(/^["']|["']$/g, "");
-        meta[key] = key === "confidence" ? Number(raw) : key === "observation_count" ? Number.parseInt(raw, 10) : raw;
-    }
-    meta._body = body.trim();
-    meta._path = file;
-    return meta;
-}
-function files() {
-    const roots = [path.join(INSTINCTS_DIR, "global"), path.join(INSTINCTS_DIR, "projects")];
-    const out = [];
-    for (const root of roots) {
-        if (!fs.existsSync(root))
-            continue;
-        const stack = [root];
-        while (stack.length) {
-            const dir = stack.pop();
-            for (const name of fs.readdirSync(dir)) {
-                const file = path.join(dir, name);
-                if (fs.statSync(file).isDirectory())
-                    stack.push(file);
-                else if (file.endsWith(".md"))
-                    out.push(file);
-            }
-        }
-    }
-    return out;
-}
-function write(inst, file) {
-    const body = String(inst._body ?? "");
-    const lines = ["---"];
-    for (const [key, value] of Object.entries(inst))
-        if (!key.startsWith("_"))
-            lines.push(`${key}: ${typeof value === "number" ? value : String(value)}`);
-    lines.push("---", "", body);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, `${lines.join("\n").trimEnd()}\n`, "utf8");
-}
-export function main(argv = process.argv.slice(2)) {
-    const [command, ...rest] = argv;
-    const instincts = files().map(parse).filter((item) => Boolean(item));
-    if (command === "status") {
-        const global = instincts.filter((item) => item.scope === "global").length;
-        console.log(`Total instincts: ${instincts.length}`);
-        console.log(`  Global: ${global}, Project: ${instincts.length - global}`);
-        return 0;
-    }
-    if (command === "list") {
-        for (const inst of instincts)
-            console.log(`  [${Number(inst.confidence ?? 0).toFixed(2)}] ${inst.id ?? "?"} - ${inst.trigger ?? "?"} (${inst.scope ?? "?"})`);
-        return 0;
-    }
-    if (command === "show") {
-        const found = instincts.find((item) => item.id === rest[0]);
-        if (!found) {
-            console.error(`Instinct '${rest[0]}' not found.`);
-            return 1;
-        }
-        console.log(fs.readFileSync(String(found._path), "utf8"));
-        return 0;
-    }
-    if (command === "create") {
-        const id = rest[rest.indexOf("--id") + 1];
-        const trigger = rest[rest.indexOf("--trigger") + 1];
-        const domain = rest[rest.indexOf("--domain") + 1];
-        const scope = rest.includes("--scope") ? rest[rest.indexOf("--scope") + 1] : "project";
-        if (!id || !trigger || !domain)
-            return 2;
-        const file = scope === "global" ? path.join(INSTINCTS_DIR, "global", `${id}.md`) : path.join(INSTINCTS_DIR, "projects", rest[rest.indexOf("--project-id") + 1] ?? "default", "instincts", `${id}.md`);
-        write({ id, trigger, confidence: 0.3, domain, source: "session-observation", scope, created: new Date().toISOString().slice(0, 10), last_observed: new Date().toISOString().slice(0, 10), observation_count: 1, _body: `# ${id}\n\n## Action\nTBD` }, file);
-        console.log(`Created ${file}`);
-        return 0;
-    }
-    console.error("usage: instinct-cli <status|list|show|create>");
-    return 2;
-}
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());