kcp-harness 0.1.0 → 0.4.0

package/README.md

@@ -0,0 +1,267 @@
+# kcp-harness
+
+**Deterministic knowledge governance for any AI agent.**
+
+> *Your agent can read every file in your project. Can it prove why it read what it read?*
+
+KCP Harness is an MCP compliance proxy that sits between an AI coding agent and its tools. It
+intercepts knowledge-related calls, routes them through the
+[kcp-agent](https://github.com/Cantara/kcp-agent) deterministic planner (13-gate cascade, no LLM),
+and produces compliance artifacts — decision traces, audit logs, budget ledgers — as a side effect
+of normal agent operation.
+
+The agent can't bypass governance because it only talks to the proxy's MCP interface. The proxy
+decides what knowledge is accessible, tracks spend, and logs every decision. **Fail-closed: if the
+harness can't verify a request, the agent gets nothing.**
+
+```
+Agent (Claude Code / Cursor / Copilot / Windsurf / Cline / Crush / OpenClaw / ...)
+  │
+  │  MCP tool call
+  v
+┌─────────────────────────────────────────────────────────┐
+│  kcp-harness                                            │
+│                                                         │
+│  classify → govern (13 gates) → execute → audit         │
+│                                                         │
+│  Side outputs:                                          │
+│  · Decision traces     (per-request, deterministic)     │
+│  · Audit log           (append-only JSONL)              │
+│  · Budget ledger       (itemized, ceiling-enforced)     │
+│  · Temporal drift      (plan validity over time)        │
+└─────────────────────────────────────────────────────────┘
+  │
+  v
+Knowledge manifests (knowledge.yaml)
+```
+
+**[Documentation →](https://cantara.github.io/kcp-harness/)**
+
+## Why
+
+Enterprises need agents that are *defensible* — auditable, reproducible, budget-controlled,
+temporally pinned. Today's agents can't prove why they read what they read. The harness adds a
+compliance layer without replacing the agent.
+
+| What you keep | What the harness adds |
+|---|---|
+| Your agent (Claude Code, Cursor, Copilot, ...) | Deterministic knowledge selection |
+| Your workflow (coding, reviewing, shipping) | Decision traces (13 gates per unit) |
+| Your tools (MCP servers, shell, browser) | Budget enforcement (ceiling, per-currency) |
+| | Temporal governance (drift detection) |
+| | Append-only audit log |
+| | Replay / cross-examination |
+
+**You sell the compliance layer. The agents are pluggable.**
+
+## Install
+
+```bash
+npm install -g kcp-harness
+```
+
+Or use without installing:
+
+```bash
+npx kcp-harness --help
+```
+
+### Native executables
+
+Pre-built binaries (no Node/Deno required) for Linux x64/arm64, macOS x64/arm64, and Windows x64
+— grab them from a [release](https://github.com/Cantara/kcp-harness/releases). To build one yourself:
+
+```bash
+npm ci && npm run build
+deno compile --allow-read --allow-env --allow-net --allow-run \
+  --node-modules-dir=auto --output kcp-harness dist/cli.js
+```
+
+## Quick start
+
+### 1. Initialize
+
+```bash
+kcp-harness init          # creates harness.yaml
+```
+
+### 2. Generate agent integration
+
+```bash
+kcp-harness integrate claude-code    # or: cursor, copilot, windsurf, cline, continue, crush, openclaw
+```
+
+### 3. Start coding
+
+Your agent now routes knowledge access through the harness. Every decision is logged.
+
+## Supported agents
+
+| Agent | Config | Integration |
+|---|---|---|
+| **Claude Code** | `.mcp.json` + PreToolUse hooks | `kcp-harness integrate claude-code` |
+| **Cursor** | `.cursor/mcp.json` + `.mdc` rules | `kcp-harness integrate cursor` |
+| **GitHub Copilot** | `.vscode/mcp.json` (uses `"servers"` key) | `kcp-harness integrate copilot` |
+| **Windsurf** | global config + `.windsurfrules` | `kcp-harness integrate windsurf` |
+| **Cline** | MCP settings + `.clinerules` | `kcp-harness integrate cline` |
+| **Continue** | `.continue/mcpServers/*.yaml` | `kcp-harness integrate continue` |
+| **Crush** | `crush.json` + PrepareStep | `kcp-harness integrate crush` |
+| **OpenClaw** | `openclaw.json` + plugin hooks | `kcp-harness integrate openclaw` |
+
+Each agent has its own MCP config format, rules file, and quirks. The `integrate` command handles
+them all — one governance layer, any agent.
+
+## How it works
+
+Every tool call flows through a five-stage pipeline:
+
+```
+1. RECEIVE      MCP JSON-RPC request from agent
+2. CLASSIFY     Knowledge-navigation or pass-through?
+3. GOVERN       13-gate cascade (audience → temporal → budget → ...)
+4. EXECUTE      Call downstream tool / return content
+5. AUDIT        Log decision to append-only audit log
+```
+
+### Classifier
+
+The classifier examines each tool call and determines whether it targets governed knowledge.
+`Read("docs/api.md")` where `docs/` is governed? Route through the planner. `Read("package.json")`
+where `package.json` isn't governed? Pass through. KCP tools (`kcp_plan`, `kcp_load`) are always
+governed.
+
+### Governor
+
+Two modes:
+
+- **Plan-first (fast path)** — the agent calls `kcp_plan` first. The harness caches the approved
+  plan. Subsequent reads are checked against the cached plan — no re-planning.
+- **Auto-plan (fallback)** — the agent reads a governed path without planning. The harness runs
+  the planner automatically. Slower, but governance is enforced even for agents that don't know
+  about `kcp_plan`.
+
+### The 13-gate cascade
+
+Every knowledge unit is evaluated through 13 deterministic gates, in order:
+
+```
+audience → not_for → temporal → deprecated → supersession → relevance →
+attestation → payment → access → strict → max_units → money_budget → context_budget
+```
+
+A unit must pass **all** gates. The gate that blocks it is recorded in the decision trace. Same
+inputs → same plan. No model involved.
+
+## MCP tools
+
+Once connected, agents can use these governance tools:
+
+| Tool | Description |
+|---|---|
+| `kcp_plan` | Deterministic load plan — which units, in what order, which skipped and why |
+| `kcp_load` | Plan + load eligible unit content |
+| `kcp_trace` | Full 13-gate decision trace |
+| `kcp_validate` | Lint a `knowledge.yaml` |
+| `harness_status` | Current governance state |
+| `harness_budget` | Itemized spend tracking |
+| `harness_temporal_check` | Plan drift detection |
+
+## Compliance artifacts
+
+### Audit log
+
+Append-only JSONL. Every decision — governed or pass-through — is logged with sequence number,
+timestamp, tool, targets, and governance decision:
+
+```bash
+cat .kcp-harness/audit.jsonl | jq 'select(.governed == true)'
+```
+
+### Budget ledger
+
+Append-only itemized spend tracking. Per-currency running totals. Ceiling enforcement — a load
+that would exceed the budget is rejected atomically (no partial loads).
+
+### Temporal governance
+
+Plans are registered with a temporal watcher. On subsequent calls, the watcher re-evaluates
+against the current time. If units have drifted (expired, newly valid), the harness emits a drift
+event. Long-running sessions stay honest.
+
+## Configuration
+
+```yaml
+# harness.yaml
+version: "1.0"
+
+governance:
+  domains:
+    - manifest: "./knowledge.yaml"
+      paths: ["docs/", "src/"]
+
+  policy:
+    fail_closed: true
+    audit_all: true
+    max_units: 5
+    budget:
+      amount: 1.00
+      currency: USDC
+
+audit:
+  path: ".kcp-harness/audit.jsonl"
+```
+
+## CLI
+
+```
+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
+```
+
+## Library
+
+```ts
+import { classify, govern, BudgetLedger, TemporalWatch } from "kcp-harness";
+import { generate, listAgents } from "kcp-harness";
+
+// Classify a tool call
+const result = classify("Read", { file_path: "docs/api.md" }, governedDomains);
+
+// Generate integration files
+const output = generate("claude-code", { manifest: "./knowledge.yaml", paths: ["docs/"] });
+```
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│  Layer 3: Integration Packages               │
+│  Agent-specific configs + rules files        │
+│  (claude-code, cursor, copilot, ...)         │
+├──────────────────────────────────────────────┤
+│  Layer 2: KCP Compliance Harness             │  ← THIS
+│  MCP proxy — deterministic governance        │
+├──────────────────────────────────────────────┤
+│  Layer 1: kcp-agent (planner core)           │
+│  13-gate cascade, decision traces            │
+└──────────────────────────────────────────────┘
+```
+
+**Forking agents puts you in competition. A harness puts you in composition.**
+
+## Tests
+
+```bash
+npm test     # 123 tests across 9 test files
+```
+
+Covers: classifier (28), audit (14), session (9), governor (5), proxy (10), integration (9),
+budget-ledger (14), temporal-watch (6), integrations (28).
+
+## License
+
+Apache-2.0 · By [eXOReaction AS](https://www.exoreaction.com), hosted under
+[Cantara](https://github.com/Cantara).

package/dist/audit-reader.d.ts

@@ -0,0 +1,68 @@
+import type { AuditEvent, AuditEventType } from "./audit.js";
+/** Filter criteria for querying audit events. */
+export interface AuditFilter {
+    /** Filter by session ID. */
+    sessionId?: string;
+    /** Filter by event type(s). */
+    type?: AuditEventType | AuditEventType[];
+    /** Include events from this ISO date (inclusive). */
+    from?: string;
+    /** Include events until this ISO date (inclusive). */
+    to?: string;
+    /** Filter by outcome. */
+    outcome?: AuditEvent["outcome"];
+}
+/** Aggregate statistics from the audit log. */
+export interface AuditSummary {
+    /** Total sessions observed. */
+    sessions: number;
+    /** Total events. */
+    events: number;
+    /** Events targeting governed domains. */
+    governed: number;
+    /** Events that were blocked. */
+    blocked: number;
+    /** Budget exceeded events. */
+    budgetExceeded: number;
+    /** Temporal drift events. */
+    drifts: number;
+    /** Signature-blocked events. */
+    signatureBlocked: number;
+    /** Date range of the log. */
+    dateRange: {
+        first: string;
+        last: string;
+    };
+}
+/** Session summary in the index. */
+export interface SessionEntry {
+    id: string;
+    startedAt: string;
+    endedAt?: string;
+    events: number;
+    governed: number;
+    blocked: number;
+}
+/** Index of all sessions in the audit log. */
+export interface SessionIndex {
+    sessions: SessionEntry[];
+}
+/** Streaming JSONL audit log reader. */
+export declare class AuditReader {
+    private readonly path;
+    constructor(path: string);
+    /** Stream all events, optionally filtered. */
+    stream(filter?: AuditFilter): AsyncIterable<AuditEvent>;
+    /** Read all events into memory (for small-to-medium logs). */
+    readAll(filter?: AuditFilter): Promise<AuditEvent[]>;
+    /** Get aggregate statistics. */
+    summarize(filter?: AuditFilter): Promise<AuditSummary>;
+    /** Get events grouped by session. */
+    sessionIndex(): Promise<SessionIndex>;
+    /** Check if the audit log file exists. */
+    exists(): boolean;
+    /** Get file size in bytes. */
+    size(): number;
+    /** Get the path to the audit log. */
+    getPath(): string;
+}

package/dist/audit-reader.js

@@ -0,0 +1,150 @@
+// Audit reader — streaming JSONL reader with query capabilities.
+//
+// Reads the append-only audit log and provides filtering, summarization,
+// and session indexing. This is the read counterpart to audit.ts's writer.
+// Used by the compliance export (export.ts) and the dashboard (future).
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { createInterface } from "node:readline";
+/** Streaming JSONL audit log reader. */
+export class AuditReader {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    /** Stream all events, optionally filtered. */
+    async *stream(filter) {
+        if (!existsSync(this.path))
+            return;
+        const rl = createInterface({
+            input: createReadStream(this.path, "utf-8"),
+            crlfDelay: Infinity,
+        });
+        for await (const line of rl) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const event = JSON.parse(trimmed);
+                if (matchesFilter(event, filter)) {
+                    yield event;
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+    }
+    /** Read all events into memory (for small-to-medium logs). */
+    async readAll(filter) {
+        const events = [];
+        for await (const event of this.stream(filter)) {
+            events.push(event);
+        }
+        return events;
+    }
+    /** Get aggregate statistics. */
+    async summarize(filter) {
+        const sessionIds = new Set();
+        let events = 0;
+        let governed = 0;
+        let blocked = 0;
+        let budgetExceeded = 0;
+        let drifts = 0;
+        let signatureBlocked = 0;
+        let first = "";
+        let last = "";
+        for await (const event of this.stream(filter)) {
+            events++;
+            sessionIds.add(event.sessionId);
+            if (event.timestamp) {
+                if (!first || event.timestamp < first)
+                    first = event.timestamp;
+                if (!last || event.timestamp > last)
+                    last = event.timestamp;
+            }
+            if (event.classification?.governed)
+                governed++;
+            if (event.outcome === "blocked")
+                blocked++;
+            if (event.type === "budget_exceeded")
+                budgetExceeded++;
+            if (event.type === "temporal_drift")
+                drifts++;
+            if (event.outcome === "blocked" && event.signature?.status && event.signature.status !== "verified") {
+                signatureBlocked++;
+            }
+        }
+        return {
+            sessions: sessionIds.size,
+            events,
+            governed,
+            blocked,
+            budgetExceeded,
+            drifts,
+            signatureBlocked,
+            dateRange: { first, last },
+        };
+    }
+    /** Get events grouped by session. */
+    async sessionIndex() {
+        const sessions = new Map();
+        for await (const event of this.stream()) {
+            let entry = sessions.get(event.sessionId);
+            if (!entry) {
+                entry = {
+                    id: event.sessionId,
+                    startedAt: event.timestamp,
+                    events: 0,
+                    governed: 0,
+                    blocked: 0,
+                };
+                sessions.set(event.sessionId, entry);
+            }
+            entry.events++;
+            if (event.timestamp < entry.startedAt)
+                entry.startedAt = event.timestamp;
+            if (!entry.endedAt || event.timestamp > entry.endedAt)
+                entry.endedAt = event.timestamp;
+            if (event.classification?.governed)
+                entry.governed++;
+            if (event.outcome === "blocked")
+                entry.blocked++;
+            if (event.type === "session_end")
+                entry.endedAt = event.timestamp;
+        }
+        return { sessions: Array.from(sessions.values()) };
+    }
+    /** Check if the audit log file exists. */
+    exists() {
+        return existsSync(this.path);
+    }
+    /** Get file size in bytes. */
+    size() {
+        if (!this.exists())
+            return 0;
+        return statSync(this.path).size;
+    }
+    /** Get the path to the audit log. */
+    getPath() {
+        return this.path;
+    }
+}
+/** Check if an event matches the filter criteria. */
+function matchesFilter(event, filter) {
+    if (!filter)
+        return true;
+    if (filter.sessionId && event.sessionId !== filter.sessionId)
+        return false;
+    if (filter.type) {
+        const types = Array.isArray(filter.type) ? filter.type : [filter.type];
+        if (!types.includes(event.type))
+            return false;
+    }
+    if (filter.from && event.timestamp < filter.from)
+        return false;
+    if (filter.to && event.timestamp > filter.to)
+        return false;
+    if (filter.outcome && event.outcome !== filter.outcome)
+        return false;
+    return true;
+}

package/dist/audit.d.ts

@@ -1,3 +1,4 @@
+import type { SignatureResult } from "kcp-agent";
 import type { Classification } from "./classifier.js";
 import type { GovernanceDecision } from "./governor.js";
 import type { LedgerSnapshot } from "./budget-ledger.js";
@@ -39,6 +40,8 @@ export interface AuditEvent {
         movedUnits?: number;
         newPlanAsOf?: string;
     };
+    /** Manifest signature verification result. */
+    signature?: SignatureResult;
 }
 /** Append-only audit log writer. */
 export declare class AuditLog {
@@ -71,3 +74,5 @@ export declare function buildBudgetEvent(sessionId: string, sequence: number, ac
 }): AuditEvent;
 /** Build a temporal drift event. */
 export declare function buildDriftEvent(sessionId: string, sequence: number, drift: DriftResult): AuditEvent;
+/** Redact sensitive values from tool arguments for audit logging. */
+export declare function sanitizeArgs(toolName: string, args: Record<string, unknown>): Record<string, unknown>;

package/dist/audit.js

@@ -61,6 +61,7 @@ export function buildEvent(sessionId, sequence, toolName, args, classification,
         outcome,
         durationMs,
         error,
+        signature: governance?.signature,
     };
 }
 /** Build a session lifecycle event. */
@@ -106,7 +107,7 @@ export function buildDriftEvent(sessionId, sequence, drift) {
     };
 }
 /** Redact sensitive values from tool arguments for audit logging. */
-function sanitizeArgs(toolName, args) {
+export function sanitizeArgs(toolName, args) {
     const sanitized = { ...args };
     // Redact content from Write calls (could be large/sensitive)
     if (toolName === "Write" && sanitized["content"]) {

package/dist/budget-ledger.js

@@ -25,6 +25,14 @@ export class BudgetLedger {
     /** Record a spend event. Returns whether it was accepted. */
     record(source, cost) {
         const currency = cost.currency || "USDC";
+        // Reject negative amounts — no refunds through the ledger
+        if (cost.amount < 0) {
+            return {
+                accepted: false,
+                total: this.totals.get(currency) ?? 0,
+                reason: `negative spend rejected: ${cost.amount} ${currency}`,
+            };
+        }
         const currentTotal = this.totals.get(currency) ?? 0;
         const newTotal = round6(currentTotal + cost.amount);
         // Check ceiling

package/dist/classifier.d.ts

@@ -29,7 +29,7 @@ export declare function extractTargets(toolName: string, args: Record<string, un
     paths: string[];
     urls: string[];
 };
-/** Normalize a file path: strip leading ./ and trailing /, collapse //. */
+/** Normalize a file path: resolve ../, strip leading ./, collapse //. */
 export declare function normalizePath(p: string): string;
 /** Check if a path starts with a prefix (directory-boundary-aware). */
 export declare function matchesPrefix(path: string, prefix: string): boolean;

package/dist/classifier.js

@@ -60,7 +60,7 @@ export function classify(toolName, args, domains) {
         }
     }
     // Rule 3: extract path and match against governed path prefixes
-    const pathExtractor = PATH_EXTRACTORS[toolName];
+    const pathExtractor = Object.hasOwn(PATH_EXTRACTORS, toolName) ? PATH_EXTRACTORS[toolName] : undefined;
     if (pathExtractor) {
         const target = pathExtractor(args);
         if (target) {
@@ -82,7 +82,7 @@ export function classify(toolName, args, domains) {
         }
     }
     // Rule 4: extract URL and match against governed URL prefixes
-    const urlExtractor = URL_EXTRACTORS[toolName];
+    const urlExtractor = Object.hasOwn(URL_EXTRACTORS, toolName) ? URL_EXTRACTORS[toolName] : undefined;
     if (urlExtractor) {
         const target = urlExtractor(args);
         if (target) {
@@ -130,12 +130,26 @@ export function extractTargets(toolName, args) {
 function str(v) {
     return typeof v === "string" ? v : undefined;
 }
-/** Normalize a file path: strip leading ./ and trailing /, collapse //. */
+/** Normalize a file path: resolve ../, strip leading ./, 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
+    // Resolve ../ segments to prevent traversal bypass
+    const parts = n.split("/");
+    const resolved = [];
+    for (const part of parts) {
+        if (part === "..") {
+            if (resolved.length > 0 && resolved[resolved.length - 1] !== "..") {
+                resolved.pop();
+            }
+            // else: leading ../ — keep it (can't resolve beyond root)
+        }
+        else if (part !== ".") {
+            resolved.push(part);
+        }
+    }
+    n = resolved.join("/");
     return n;
 }
 /** Check if a path starts with a prefix (directory-boundary-aware). */
@@ -170,8 +184,20 @@ function extractPathPrefix(pattern) {
 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"'|;&]+)/;
+    // Match common file-access commands: read, copy, move, link, archive
+    const fileCommands = /\b(?:cat|head|tail|less|more|vi|vim|nano|code|cp|mv|ln|tar|zip|scp|rsync)\s+(?:-[^\s]*\s+)*["']?([^\s"'|;&]+)/;
     const m = command.match(fileCommands);
-    return m?.[1] ?? undefined;
+    if (m?.[1])
+        return m[1];
+    // Match redirect targets: > or >> followed by a path
+    const redirect = /[>]\s*["']?([^\s"'|;&]+)/;
+    const r = command.match(redirect);
+    if (r?.[1])
+        return r[1];
+    // Match programming language file access: python/node/ruby -c '...open("path")...'
+    const langRead = /\bopen\s*\(\s*["']([^"']+)["']\s*\)/;
+    const l = command.match(langRead);
+    if (l?.[1])
+        return l[1];
+    return undefined;
 }