kcp-harness 0.1.0

package/dist/classifier.js

@@ -0,0 +1,177 @@
+// Tool call classifier — detect knowledge-navigation tool calls.
+//
+// The classifier is a pure function: given a tool name, its arguments, and
+// the configured governed domains, it returns whether the call targets a
+// governed knowledge domain, which domain matched, and why.
+//
+// Classification happens BEFORE governance. Every tool call is classified
+// exactly once; the governance layer only runs for governed calls.
+//
+// The classifier extracts the target path or URL from known tool argument
+// shapes (Read, Glob, Grep, WebFetch, etc.) and matches against the
+// governed domain's path/URL prefixes. Tool names in the domain's `tools`
+// list are matched directly regardless of arguments.
+// -- Path extraction from tool arguments -----------------------------------
+/** Known tool argument shapes for extracting file paths. */
+const PATH_EXTRACTORS = {
+    // Claude Code built-in tools
+    Read: (a) => str(a["file_path"]),
+    Edit: (a) => str(a["file_path"]),
+    Write: (a) => str(a["file_path"]),
+    Glob: (a) => str(a["path"]) ?? extractPathPrefix(str(a["pattern"])),
+    Grep: (a) => str(a["path"]),
+    // MCP filesystem tools (common patterns)
+    read_file: (a) => str(a["path"]),
+    write_file: (a) => str(a["path"]),
+    list_directory: (a) => str(a["path"]),
+    search_files: (a) => str(a["path"]),
+    get_file_info: (a) => str(a["path"]),
+    // Bash — best-effort: check for file access patterns
+    Bash: (a) => extractBashTarget(str(a["command"])),
+};
+/** Known tool argument shapes for extracting URLs. */
+const URL_EXTRACTORS = {
+    WebFetch: (a) => str(a["url"]),
+    WebSearch: (a) => undefined, // search queries aren't URL targets
+    fetch: (a) => str(a["url"]),
+};
+/** KCP tools are always classified as knowledge-nav. */
+const KCP_TOOLS = new Set(["kcp_plan", "kcp_load", "kcp_trace", "kcp_validate", "kcp_replay"]);
+// -- Classification ---------------------------------------------------------
+/**
+ * Classify a tool call: is it knowledge-navigation targeting a governed domain?
+ *
+ * Classification rules (in order):
+ * 1. KCP tools → always governed (route to kcp-agent directly)
+ * 2. Tool name in domain's `tools` list → governed by that domain
+ * 3. File path extracted from arguments → match against domain paths
+ * 4. URL extracted from arguments → match against domain URLs
+ * 5. Otherwise → pass-through (ungoverned)
+ */
+export function classify(toolName, args, domains) {
+    // Rule 1: KCP tools are always knowledge-nav
+    if (KCP_TOOLS.has(toolName)) {
+        return { governed: true, reason: `KCP tool: ${toolName}` };
+    }
+    // Rule 2: tool name explicitly listed in a domain
+    for (const domain of domains) {
+        if (domain.tools?.includes(toolName)) {
+            return { governed: true, domain, reason: `tool ${toolName} is governed by ${domain.manifest}` };
+        }
+    }
+    // Rule 3: extract path and match against governed path prefixes
+    const pathExtractor = PATH_EXTRACTORS[toolName];
+    if (pathExtractor) {
+        const target = pathExtractor(args);
+        if (target) {
+            const normalized = normalizePath(target);
+            for (const domain of domains) {
+                if (domain.paths) {
+                    for (const prefix of domain.paths) {
+                        if (matchesPrefix(normalized, normalizePath(prefix))) {
+                            return {
+                                governed: true,
+                                domain,
+                                target: normalized,
+                                reason: `path ${normalized} is governed by ${domain.manifest} (prefix: ${prefix})`,
+                            };
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Rule 4: extract URL and match against governed URL prefixes
+    const urlExtractor = URL_EXTRACTORS[toolName];
+    if (urlExtractor) {
+        const target = urlExtractor(args);
+        if (target) {
+            for (const domain of domains) {
+                if (domain.urls) {
+                    for (const prefix of domain.urls) {
+                        if (target.startsWith(prefix)) {
+                            return {
+                                governed: true,
+                                domain,
+                                target,
+                                reason: `URL ${target} is governed by ${domain.manifest} (prefix: ${prefix})`,
+                            };
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Rule 5: pass-through
+    return { governed: false, reason: `tool ${toolName} does not target a governed domain` };
+}
+/**
+ * Extract known targets from any tool call arguments.
+ * Useful for audit logging even when not governed.
+ */
+export function extractTargets(toolName, args) {
+    const paths = [];
+    const urls = [];
+    const pathFn = PATH_EXTRACTORS[toolName];
+    if (pathFn) {
+        const p = pathFn(args);
+        if (p)
+            paths.push(p);
+    }
+    const urlFn = URL_EXTRACTORS[toolName];
+    if (urlFn) {
+        const u = urlFn(args);
+        if (u)
+            urls.push(u);
+    }
+    return { paths, urls };
+}
+// -- Helpers ----------------------------------------------------------------
+function str(v) {
+    return typeof v === "string" ? v : undefined;
+}
+/** Normalize a file path: strip leading ./ and trailing /, collapse //. */
+export function normalizePath(p) {
+    let n = p.replace(/\/+/g, "/");
+    if (n.startsWith("./"))
+        n = n.slice(2);
+    // Don't strip leading / — absolute paths stay absolute
+    return n;
+}
+/** Check if a path starts with a prefix (directory-boundary-aware). */
+export function matchesPrefix(path, prefix) {
+    // Normalize both: strip trailing slashes for comparison
+    const a = path.replace(/\/+$/, "");
+    const b = prefix.replace(/\/+$/, "");
+    if (a === b)
+        return true;
+    // Ensure prefix matches at a directory boundary
+    return a.startsWith(b + "/");
+}
+/** Extract the directory prefix from a glob pattern (best-effort). */
+function extractPathPrefix(pattern) {
+    if (!pattern)
+        return undefined;
+    // Take everything before the first glob character
+    const idx = pattern.search(/[*?\[{]/);
+    if (idx <= 0)
+        return undefined;
+    const prefix = pattern.slice(0, idx);
+    // Find the last / before the glob
+    const lastSlash = prefix.lastIndexOf("/");
+    if (lastSlash > 0)
+        return prefix.slice(0, lastSlash);
+    // If the prefix itself is a directory name (e.g. "src" from "src/**"), return it
+    if (prefix.length > 0 && !prefix.includes("."))
+        return prefix.replace(/\/$/, "");
+    return undefined;
+}
+/** Best-effort extraction of file paths from Bash commands. */
+function extractBashTarget(command) {
+    if (!command)
+        return undefined;
+    // Match common file-access commands: cat, head, tail, less, more, vi, nano
+    const fileCommands = /\b(?:cat|head|tail|less|more|vi|vim|nano|code)\s+["']?([^\s"'|;&]+)/;
+    const m = command.match(fileCommands);
+    return m?.[1] ?? undefined;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// kcp-harness CLI — launch the compliance proxy.
+//
+// Usage:
+//   kcp-harness serve [--config harness.yaml]   — start the MCP proxy
+//   kcp-harness init                             — create a harness.yaml template
+//   kcp-harness check [--config harness.yaml]    — validate the config
+//
+// The harness reads its configuration from harness.yaml (or the path given
+// by --config). The config declares governed domains, policies, downstream
+// MCP servers, and audit log settings.
+import { writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { loadConfig } from "./config.js";
+import { serveProxy } from "./proxy.js";
+import { generate, listAgents } from "./integrations/generate.js";
+const USAGE = `kcp-harness — KCP Compliance Harness
+
+Usage:
+  kcp-harness serve  [--config harness.yaml]   Start the MCP proxy
+  kcp-harness init                             Create a harness.yaml template
+  kcp-harness check  [--config harness.yaml]   Validate configuration
+  kcp-harness integrate <agent> [options]       Generate agent integration files
+  kcp-harness integrate --list                  List supported agents
+  kcp-harness --version                        Show version
+  kcp-harness --help                           Show this help
+
+Agents: claude-code, cursor, windsurf, cline, continue, copilot, copilot-cli, crush, openclaw
+
+The harness is an MCP proxy that enforces deterministic knowledge
+governance for any agent. It intercepts tool calls, classifies them
+as knowledge-navigation or pass-through, and routes governed calls
+through the kcp-agent planner before execution.
+`;
+const VERSION = "0.1.0";
+const TEMPLATE = `# kcp-harness configuration
+version: "1.0"
+
+governance:
+  domains:
+    - manifest: "./knowledge.yaml"
+      paths:
+        - "docs/"
+        - "src/"
+      # urls:
+      #   - "https://docs.example.com/"
+      # tools:
+      #   - "custom_knowledge_tool"
+
+  policy:
+    fail_closed: true
+    audit_all: true
+    max_units: 5
+    strict: false
+    # budget:
+    #   amount: 1.00
+    #   currency: USDC
+    # context_budget: 50000
+    # env: prod
+
+downstream:
+  # - name: "filesystem"
+  #   command: "npx"
+  #   args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
+
+audit:
+  path: ".kcp-harness/audit.jsonl"
+`;
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command || command === "--help" || command === "-h") {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (command === "--version" || command === "-v") {
+        process.stdout.write(`kcp-harness ${VERSION}\n`);
+        return;
+    }
+    const configPath = getFlag(args, "--config") ?? "harness.yaml";
+    switch (command) {
+        case "serve": {
+            if (!existsSync(configPath)) {
+                process.stderr.write(`[kcp-harness] config not found: ${configPath}\n`);
+                process.stderr.write(`[kcp-harness] run 'kcp-harness init' to create one\n`);
+                process.exit(1);
+            }
+            const config = loadConfig(configPath);
+            process.stderr.write(`[kcp-harness] starting proxy (${config.governance.domains.length} governed domains)\n`);
+            await serveProxy(config);
+            break;
+        }
+        case "init": {
+            const target = configPath === "harness.yaml" ? "harness.yaml" : configPath;
+            if (existsSync(target)) {
+                process.stderr.write(`[kcp-harness] ${target} already exists — not overwriting\n`);
+                process.exit(1);
+            }
+            writeFileSync(target, TEMPLATE, "utf-8");
+            process.stderr.write(`[kcp-harness] created ${target}\n`);
+            break;
+        }
+        case "check": {
+            if (!existsSync(configPath)) {
+                process.stderr.write(`[kcp-harness] config not found: ${configPath}\n`);
+                process.exit(1);
+            }
+            try {
+                const config = loadConfig(configPath);
+                process.stdout.write(JSON.stringify(config, null, 2) + "\n");
+                process.stderr.write(`[kcp-harness] config valid: ${config.governance.domains.length} domain(s), ${config.downstream.length} downstream(s)\n`);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                process.stderr.write(`[kcp-harness] config error: ${msg}\n`);
+                process.exit(1);
+            }
+            break;
+        }
+        case "integrate": {
+            const agent = args[1];
+            if (!agent || agent === "--list") {
+                const agents = listAgents();
+                process.stdout.write("Supported agents:\n");
+                for (const a of agents) {
+                    process.stdout.write(`  ${a}\n`);
+                }
+                break;
+            }
+            const opts = {
+                manifest: getFlag(args, "--manifest"),
+                harnessConfig: getFlag(args, "--config"),
+                harnessCommand: getFlag(args, "--command"),
+                paths: getFlag(args, "--paths")?.split(","),
+            };
+            try {
+                const output = generate(agent, opts);
+                const outDir = getFlag(args, "--out") ?? ".";
+                const dryRun = args.includes("--dry-run");
+                process.stderr.write(`[kcp-harness] generating ${output.name} integration (${output.files.length} files)\n`);
+                for (const file of output.files) {
+                    const filePath = join(outDir, file.path);
+                    if (dryRun) {
+                        process.stdout.write(`--- ${filePath} ---\n`);
+                        process.stdout.write(file.content);
+                        process.stdout.write("\n");
+                    }
+                    else {
+                        const dir = dirname(filePath);
+                        mkdirSync(dir, { recursive: true });
+                        writeFileSync(filePath, file.content, "utf-8");
+                        process.stderr.write(`[kcp-harness]   wrote ${filePath}\n`);
+                    }
+                }
+                process.stdout.write("\n" + output.instructions + "\n");
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                process.stderr.write(`[kcp-harness] error: ${msg}\n`);
+                process.exit(1);
+            }
+            break;
+        }
+        default:
+            process.stderr.write(`[kcp-harness] unknown command: ${command}\n\n`);
+            process.stdout.write(USAGE);
+            process.exit(1);
+    }
+}
+function getFlag(args, flag) {
+    const idx = args.indexOf(flag);
+    return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : undefined;
+}
+main().catch((e) => {
+    process.stderr.write(`[kcp-harness] fatal: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(1);
+});

package/dist/config.d.ts

@@ -0,0 +1,65 @@
+/** A knowledge domain governed by a KCP manifest. */
+export interface GovernedDomain {
+    /** Path or URL to the knowledge.yaml that governs this domain. */
+    manifest: string;
+    /** File path prefixes under governance (relative to the project root). */
+    paths?: string[];
+    /** URL prefixes under governance. */
+    urls?: string[];
+    /** Specific tool names that are always governed in this domain. */
+    tools?: string[];
+}
+/** Governance policy — what happens when a governed domain is accessed. */
+export interface GovernancePolicy {
+    /** Block access to governed paths without plan approval (default: true). */
+    fail_closed: boolean;
+    /** Log all tool calls, not just governed ones (default: true). */
+    audit_all: boolean;
+    /** Money budget ceiling for the session. */
+    budget?: {
+        amount: number;
+        currency?: string;
+    };
+    /** Token ceiling for context window. */
+    context_budget?: number;
+    /** Cap on selected units per plan (default: 5). */
+    max_units?: number;
+    /** Fail-closed: drop non-eligible units from plan instead of listing them. */
+    strict?: boolean;
+    /** Environment for federation context selection (dev/test/staging/prod). */
+    env?: string;
+}
+/** A downstream MCP server to proxy tool calls to. */
+export interface DownstreamConfig {
+    /** Human-readable name for this downstream server. */
+    name: string;
+    /** Command to spawn the server. */
+    command: string;
+    /** Arguments to the command. */
+    args?: string[];
+    /** Extra environment variables. */
+    env?: Record<string, string>;
+}
+/** Audit log configuration. */
+export interface AuditConfig {
+    /** Path to the append-only JSONL audit log. */
+    path: string;
+}
+/** Top-level harness configuration. */
+export interface HarnessConfig {
+    version: string;
+    governance: {
+        domains: GovernedDomain[];
+        policy: GovernancePolicy;
+    };
+    downstream: DownstreamConfig[];
+    audit: AuditConfig;
+}
+/** Default governance policy. */
+export declare const DEFAULT_POLICY: GovernancePolicy;
+/** Default audit configuration. */
+export declare const DEFAULT_AUDIT: AuditConfig;
+/** Load and validate a harness configuration from a YAML file. */
+export declare function loadConfig(path: string): HarnessConfig;
+/** Parse a harness configuration from YAML text. */
+export declare function parseConfig(text: string): HarnessConfig;

package/dist/config.js

@@ -0,0 +1,91 @@
+// Harness configuration — governed domains, policies, downstream servers.
+//
+// The harness reads a YAML config that declares which knowledge domains are
+// governed (by manifest + path/URL prefixes), what policy to enforce, and
+// which downstream MCP servers to proxy. Everything else passes through.
+import { readFileSync } from "node:fs";
+import yaml from "js-yaml";
+/** Default governance policy. */
+export const DEFAULT_POLICY = {
+    fail_closed: true,
+    audit_all: true,
+    max_units: 5,
+    strict: false,
+};
+/** Default audit configuration. */
+export const DEFAULT_AUDIT = {
+    path: ".kcp-harness/audit.jsonl",
+};
+/** Load and validate a harness configuration from a YAML file. */
+export function loadConfig(path) {
+    const text = readFileSync(path, "utf-8");
+    return parseConfig(text);
+}
+/** Parse a harness configuration from YAML text. */
+export function parseConfig(text) {
+    const raw = yaml.load(text);
+    if (!raw || typeof raw !== "object")
+        throw new Error("harness config must be a YAML object");
+    const governance = raw["governance"];
+    const domains = parseDomains(governance?.["domains"]);
+    const policy = parsePolicy(governance?.["policy"]);
+    const downstream = parseDownstream(raw["downstream"]);
+    const audit = parseAudit(raw["audit"]);
+    return {
+        version: String(raw["version"] ?? "1.0"),
+        governance: { domains, policy },
+        downstream,
+        audit,
+    };
+}
+function parseDomains(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((d) => ({
+        manifest: String(d["manifest"] ?? ""),
+        paths: Array.isArray(d["paths"]) ? d["paths"].map(String) : undefined,
+        urls: Array.isArray(d["urls"]) ? d["urls"].map(String) : undefined,
+        tools: Array.isArray(d["tools"]) ? d["tools"].map(String) : undefined,
+    }));
+}
+function parsePolicy(raw) {
+    if (!raw || typeof raw !== "object")
+        return { ...DEFAULT_POLICY };
+    const p = raw;
+    return {
+        fail_closed: p["fail_closed"] !== false,
+        audit_all: p["audit_all"] !== false,
+        budget: parseBudget(p["budget"]),
+        context_budget: p["context_budget"] === undefined ? undefined : Number(p["context_budget"]),
+        max_units: p["max_units"] === undefined ? DEFAULT_POLICY.max_units : Number(p["max_units"]),
+        strict: p["strict"] === true,
+        env: p["env"] === undefined ? undefined : String(p["env"]),
+    };
+}
+function parseBudget(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const b = raw;
+    return {
+        amount: Number(b["amount"] ?? 0),
+        currency: b["currency"] === undefined ? undefined : String(b["currency"]),
+    };
+}
+function parseDownstream(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((d) => ({
+        name: String(d["name"] ?? ""),
+        command: String(d["command"] ?? ""),
+        args: Array.isArray(d["args"]) ? d["args"].map(String) : undefined,
+        env: d["env"] && typeof d["env"] === "object" ? Object.fromEntries(Object.entries(d["env"]).map(([k, v]) => [k, String(v)])) : undefined,
+    }));
+}
+function parseAudit(raw) {
+    if (!raw || typeof raw !== "object")
+        return { ...DEFAULT_AUDIT };
+    const a = raw;
+    return {
+        path: String(a["path"] ?? DEFAULT_AUDIT.path),
+    };
+}

package/dist/downstream.d.ts

@@ -0,0 +1,50 @@
+import { type ChildProcess } from "node:child_process";
+import { type Interface } from "node:readline";
+import type { DownstreamConfig } from "./config.js";
+/** An MCP tool descriptor (matches MCP spec). */
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+/** A live connection to a downstream MCP server. */
+export interface DownstreamConnection {
+    name: string;
+    config: DownstreamConfig;
+    process: ChildProcess;
+    readline: Interface;
+    tools: McpTool[];
+    nextId: number;
+    pending: Map<number, {
+        resolve: (v: unknown) => void;
+        reject: (e: Error) => void;
+        timer: ReturnType<typeof setTimeout>;
+    }>;
+    alive: boolean;
+}
+/** Manages the lifecycle of downstream MCP servers. */
+export declare class DownstreamManager {
+    private connections;
+    /** Map from tool name → downstream connection that owns it. */
+    private toolOwners;
+    /** Spawn and initialize a downstream MCP server. */
+    add(config: DownstreamConfig): Promise<DownstreamConnection>;
+    /** Get all tools from all downstream servers. */
+    allTools(): McpTool[];
+    /** Find which downstream owns a tool. */
+    ownerOf(toolName: string): DownstreamConnection | undefined;
+    /** Call a tool on the downstream that owns it. */
+    callTool(toolName: string, args: Record<string, unknown>): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError: boolean;
+    }>;
+    /** Shut down all downstream connections. */
+    shutdown(): Promise<void>;
+    private spawn;
+    private initialize;
+    private rpc;
+    private notify;
+}