kcp-harness 0.4.2 → 0.5.1

package/README.md

@@ -88,7 +88,7 @@ kcp-harness init          # creates harness.yaml
 ### 2. Generate agent integration
 
 ```bash
-kcp-harness integrate claude-code    # or: cursor, copilot, windsurf, cline, continue, crush, openclaw
+kcp-harness integrate claude-code    # or: pi, cursor, copilot, windsurf, cline, continue, crush, openclaw
 ```
 
 ### 3. Start coding
@@ -107,6 +107,7 @@ Your agent now routes knowledge access through the harness. Every decision is lo
 | **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` |
+| **Pi** | `.pi/mcp.json` + project skills | `kcp-harness integrate pi` |
 
 Each agent has its own MCP config format, rules file, and quirks. The `integrate` command handles
 them all — one governance layer, any agent.

package/dist/cli.js

@@ -29,14 +29,14 @@ Usage:
   kcp-harness --version                        Show version
   kcp-harness --help                           Show this help
 
-Agents: claude-code, cursor, windsurf, cline, continue, copilot, copilot-cli, crush, openclaw
+Agents: pi, 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.4.1";
+const VERSION = "0.5.1";
 const TEMPLATE = `# kcp-harness configuration
 version: "1.0"
 

package/dist/config.d.ts

@@ -49,6 +49,11 @@ export interface AuditConfig {
     /** Path to the append-only JSONL audit log. */
     path: string;
 }
+/** Optional dashboard telemetry sink for decision traces. */
+export interface DashboardConfig {
+    /** Full URL of the kcp-dashboard /trace endpoint (e.g. http://localhost:7734/trace). */
+    url?: string;
+}
 /** Top-level harness configuration. */
 export interface HarnessConfig {
     version: string;
@@ -58,6 +63,8 @@ export interface HarnessConfig {
     };
     downstream: DownstreamConfig[];
     audit: AuditConfig;
+    /** Opt-in decision-trace telemetry sink (absent = disabled). */
+    dashboard?: DashboardConfig;
 }
 /** Default governance policy. */
 export declare const DEFAULT_POLICY: GovernancePolicy;

package/dist/config.js

@@ -31,13 +31,21 @@ export function parseConfig(text) {
     const policy = parsePolicy(governance?.["policy"]);
     const downstream = parseDownstream(raw["downstream"]);
     const audit = parseAudit(raw["audit"]);
+    const dashboard = parseDashboard(raw["dashboard"]);
     return {
         version: String(raw["version"] ?? "1.0"),
         governance: { domains, policy },
         downstream,
         audit,
+        ...(dashboard ? { dashboard } : {}),
     };
 }
+function parseDashboard(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const d = raw;
+    return { url: d["url"] === undefined ? undefined : String(d["url"]) };
+}
 function parseDomains(raw) {
     if (!Array.isArray(raw))
         return [];

package/dist/integrations/claude-code.js

@@ -20,19 +20,99 @@ export function generateClaudeCode(options) {
             hooks: {
                 PreToolUse: [
                     {
-                        matcher: "Read|Edit|Write|Glob|Grep",
+                        matcher: "Bash|Read|Edit|Write|Glob|Grep",
                         hooks: [
                             {
                                 type: "command",
                                 command: "node",
                                 args: ["-e", `
-const args = JSON.parse(process.env.TOOL_INPUT || '{}');
-const path = args.file_path || args.path || '';
-const governed = ${JSON.stringify(paths)}.some(p => path.startsWith(p) || path.includes('/' + p));
-if (governed) {
-  console.log(JSON.stringify({ decision: "block", reason: "Use kcp_load to access governed knowledge at " + path }));
-  process.exit(2);
-}
+const deny = (reason) => {
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  }));
+  process.exit(0);
+};
+// Path matching mirrors src/classifier.ts so native file tools can't slip past
+// with a Bash command, a Glob/Grep pattern, a case variant, or a backslash
+// separator. Plain string ops only — this runs as an inline node script.
+const BS = String.fromCharCode(92);
+const GOV = ${JSON.stringify(paths)}.map((p) => {
+  let b = String(p).split(BS).join("/").toLowerCase();
+  while (b.slice(-1) === "/") b = b.slice(0, -1);
+  return b;
+}).filter(Boolean);
+const norm = (p) => {
+  let n = String(p == null ? "" : p).split(BS).join("/");
+  while (n.indexOf("//") >= 0) n = n.split("//").join("/");
+  if (n.slice(0, 2) === "./") n = n.slice(2);
+  const parts = n.split("/"), out = [];
+  for (let i = 0; i < parts.length; i++) {
+    const s = parts[i];
+    if (s === "..") { if (out.length && out[out.length - 1] !== "..") out.pop(); }
+    else if (s !== "." && s !== "") out.push(s);
+  }
+  return out.join("/").toLowerCase();
+};
+const isGoverned = (t) => {
+  if (!t) return false;
+  const n = norm(t);
+  return GOV.some((b) => n === b || n.indexOf(b + "/") === 0 || n.indexOf("/" + b + "/") >= 0);
+};
+const globPrefix = (pattern) => {
+  const s = String(pattern || "");
+  let idx = -1;
+  for (let i = 0; i < s.length; i++) { if ("*?[{".indexOf(s[i]) >= 0) { idx = i; break; } }
+  if (idx <= 0) return "";
+  const pre = s.slice(0, idx), ls = pre.lastIndexOf("/");
+  if (ls > 0) return pre.slice(0, ls);
+  if (pre.length > 0 && pre.indexOf(".") < 0) { let r = pre; while (r.slice(-1) === "/") r = r.slice(0, -1); return r; }
+  return "";
+};
+const tokens = (cmd) => {
+  const s = String(cmd || ""), seps = " " + String.fromCharCode(9) + String.fromCharCode(10) + ";|&<>()" + String.fromCharCode(34) + String.fromCharCode(39);
+  let cur = "", out = [];
+  for (let i = 0; i < s.length; i++) { const ch = s[i]; if (seps.indexOf(ch) >= 0) { if (cur) { out.push(cur); cur = ""; } } else cur += ch; }
+  if (cur) out.push(cur);
+  return out;
+};
+const bashTarget = (cmd) => {
+  const toks = tokens(cmd);
+  const readCmds = ["cat","head","tail","less","more","vi","vim","nano","code","cp","mv","ln","tar","zip","scp","rsync"];
+  for (let i = 0; i < toks.length; i++) {
+    if (readCmds.indexOf(toks[i]) >= 0) {
+      for (let j = i + 1; j < toks.length; j++) { if (toks[j][0] !== "-" && isGoverned(toks[j])) return toks[j]; }
+    }
+  }
+  if (String(cmd || "").indexOf(">") >= 0) { for (let j = 0; j < toks.length; j++) { if (isGoverned(toks[j])) return toks[j]; } }
+  return "";
+};
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    // Fail-closed: an unreadable payload means we cannot prove the target is
+    // ungoverned, so we must not let it through.
+    deny("kcp-harness: could not parse PreToolUse input — failing closed");
+    return;
+  }
+  const tool = input.tool_name || "";
+  const a = input.tool_input || {};
+  let targets;
+  if (tool === "Glob" || tool === "Grep") targets = [a.path || "", globPrefix(a.pattern)];
+  else if (tool === "Bash") targets = [bashTarget(a.command)];
+  else targets = [a.file_path || a.path || ""];
+  const hit = targets.filter(Boolean).find(isGoverned);
+  if (hit) {
+    deny("Use kcp_load to access governed knowledge at " + hit);
+  }
+});
                   `.trim()],
                             },
                         ],

package/dist/integrations/generate.js

@@ -3,6 +3,7 @@
 // Each agent has its own MCP config format, rules file, and setup pattern.
 // The generator takes a harness config and produces the files needed to
 // integrate the harness with a specific agent.
+import { generatePi } from "./pi.js";
 import { generateClaudeCode } from "./claude-code.js";
 import { generateCursor } from "./cursor.js";
 import { generateWindsurf } from "./windsurf.js";
@@ -12,6 +13,7 @@ import { generateCopilot } from "./copilot.js";
 import { generateCrush } from "./crush.js";
 import { generateOpenClaw } from "./openclaw.js";
 const GENERATORS = {
+    pi: generatePi,
     "claude-code": generateClaudeCode,
     cursor: generateCursor,
     windsurf: generateWindsurf,

package/dist/integrations/pi.d.ts

@@ -0,0 +1,2 @@
+import type { IntegrationOutput, IntegrationOptions } from "./types.js";
+export declare function generatePi(options: IntegrationOptions): IntegrationOutput;

package/dist/integrations/pi.js

@@ -0,0 +1,68 @@
+// Pi integration — project-local MCP config plus an agent operating skill.
+import { governedPathsBlock, harnessServerEntry, manifestRef } from "./generate.js";
+export function generatePi(options) {
+    const server = harnessServerEntry(options);
+    const manifest = manifestRef(options);
+    const mcpJson = {
+        path: ".pi/mcp.json",
+        content: JSON.stringify({
+            settings: { toolPrefix: "server", directTools: false },
+            mcpServers: { "kcp-harness": { ...server, lifecycle: "lazy" } },
+        }, null, 2) + "\n",
+        commitToGit: true,
+        description: "Pi MCP config — connects Pi to the lazy kcp-harness governance proxy",
+    };
+    const skill = {
+        path: ".pi/skills/kcp-harness/SKILL.md",
+        content: `---
+name: kcp-harness
+description: Use the kcp-harness MCP proxy for governed project knowledge. Load before reading governed paths or making architecture decisions.
+---
+
+# KCP Harness for Pi
+
+This project uses kcp-harness to govern knowledge access through \`knowledge.yaml\`.
+
+## Prerequisite: an MCP client extension
+
+Stock Pi has no built-in MCP client, so \`.pi/mcp.json\` is inert until an MCP
+client extension (for example \`pi-mcp-adapter\`) is installed. If the
+\`kcp_plan\`/\`kcp_load\` tools are not available in this session, tell the
+operator to install one — do not fall back to direct reads of governed paths.
+
+## Governed paths
+
+${governedPathsBlock(options)}
+
+## Agent workflow
+
+1. Call \`kcp_plan\` with the task and manifest \`${manifest}\`.
+2. Call \`kcp_load\` to load only the approved units.
+3. Use \`harness_status\` and \`harness_budget\` when the task has governance or budget implications.
+4. Treat plan and audit metadata as evidence; do not bypass the harness with direct reads of governed paths.
+5. Re-check temporal validity with \`harness_temporal_check\` before relying on an old plan.
+
+The harness owns governance. This skill teaches the agent how to use it; it does not reimplement planner gates.
+`,
+        commitToGit: true,
+        description: "Pi skill — instructs the agent to use kcp-harness plan/load and diagnostics",
+    };
+    return {
+        agent: "pi",
+        name: "Pi",
+        files: [mcpJson, skill],
+        instructions: `## Pi Integration
+
+1. The .pi/mcp.json registers kcp-harness as a lazy MCP server.
+2. The .pi/skills/kcp-harness/SKILL.md teaches Pi to call kcp_plan and kcp_load for governed knowledge.
+3. Keep directTools disabled by default to avoid flattening the provider's full tool surface.
+
+Prerequisite: stock Pi ships without an MCP client — .pi/mcp.json takes effect
+only once an MCP client extension such as pi-mcp-adapter is installed
+(\`pi install npm:pi-mcp-adapter\`). The skill still loads either way from
+.pi/skills/ after the project is trusted.
+
+Review generated files before committing them. Regenerate with \`--dry-run\` to inspect output without writing.
+`,
+    };
+}

package/dist/integrations/types.d.ts

@@ -1,5 +1,5 @@
 /** Supported agent targets for integration generation. */
-export type AgentTarget = "claude-code" | "cursor" | "windsurf" | "cline" | "continue" | "copilot" | "copilot-cli" | "crush" | "openclaw";
+export type AgentTarget = "pi" | "claude-code" | "cursor" | "windsurf" | "cline" | "continue" | "copilot" | "copilot-cli" | "crush" | "openclaw";
 /** Integration output — generated files for a specific agent. */
 export interface IntegrationOutput {
     /** Which agent this integration is for. */

package/dist/integrations/types.js

@@ -1,6 +1,15 @@
 // Integration types — shared across all agent integration packages.
 /** Registry of all supported agents. */
 export const AGENTS = {
+    pi: {
+        target: "pi",
+        name: "Pi",
+        mcpSupport: true,
+        configFile: ".pi/mcp.json",
+        rulesFile: ".pi/skills/kcp-harness/SKILL.md",
+        topLevelKey: "mcpServers",
+        notes: "Project-local MCP config plus Agent Skills guidance",
+    },
     "claude-code": {
         target: "claude-code",
         name: "Claude Code",

package/dist/proxy.d.ts

@@ -27,6 +27,12 @@ export declare class HarnessProxy {
     private listTools;
     /** Handle a tool call through the governance pipeline. */
     private handleToolCall;
+    /**
+     * Ship a decision trace to the dashboard when one is available (kcp_trace)
+     * and a dashboard URL is configured. Opt-in and fully fail-open — any error
+     * here is swallowed so telemetry never affects the tool result.
+     */
+    private maybeEmitTrace;
     /** Handle harness-internal tools. */
     private handleHarnessTool;
     /** Expose session for testing. */

package/dist/proxy.js

@@ -18,6 +18,7 @@ import { AuditLog, buildEvent, buildLifecycleEvent, buildDriftEvent, } from "./a
 import { createSession, nextSequence } from "./session.js";
 import { DownstreamManager } from "./downstream.js";
 import { callKcpTool } from "./kcp-bridge.js";
+import { toTraceEvent, emitTrace } from "./trace-emit.js";
 const HARNESS_VERSION = "0.1.0";
 const PROTOCOL_VERSION = "2025-06-18";
 const rpcResult = (id, result) => ({
@@ -238,6 +239,8 @@ export class HarnessProxy {
                 // KCP tool — delegate to kcp-agent via the bridge
                 const text = await callKcpTool(toolName, args);
                 result = { content: [{ type: "text", text }], isError: false };
+                // Opt-in, fail-open: ship the decision trace to the dashboard.
+                this.maybeEmitTrace(toolName, args, text);
             }
             else {
                 // Downstream tool — forward to the owning downstream server
@@ -263,6 +266,27 @@ export class HarnessProxy {
             });
         }
     }
+    /**
+     * Ship a decision trace to the dashboard when one is available (kcp_trace)
+     * and a dashboard URL is configured. Opt-in and fully fail-open — any error
+     * here is swallowed so telemetry never affects the tool result.
+     */
+    maybeEmitTrace(toolName, args, text) {
+        const url = this.config.dashboard?.url;
+        if (!url || toolName !== "kcp_trace")
+            return;
+        try {
+            const trace = JSON.parse(text);
+            emitTrace(url, toTraceEvent(trace, {
+                sessionId: this.session.id,
+                project: process.cwd(),
+                manifest: typeof args["manifest"] === "string" ? args["manifest"] : undefined,
+            }));
+        }
+        catch {
+            /* fail-open: never let telemetry break governance */
+        }
+    }
     /** Handle harness-internal tools. */
     async handleHarnessTool(name, _args) {
         switch (name) {

package/dist/trace-emit.d.ts

@@ -0,0 +1,47 @@
+import type { DecisionTrace } from "kcp-agent";
+/** One unit's gate-cascade verdict in the wire event. */
+export interface TraceEventUnit {
+    id: string;
+    path?: string;
+    outcome: string;
+    rejected_by?: string;
+    score?: number;
+    gates: Array<{
+        gate: string;
+        verdict: "pass" | "fail";
+        detail?: string;
+    }>;
+}
+/** The compact wire event POSTed to the dashboard. */
+export interface TraceEvent {
+    kind: "decision_trace";
+    session_id: string;
+    ts: string;
+    project?: string;
+    manifest?: string;
+    task: string;
+    as_of?: string;
+    selected: number;
+    skipped: number;
+    gate_summary: Array<{
+        gate: string;
+        passed: number;
+        failed: number;
+    }>;
+    units: TraceEventUnit[];
+}
+/** Context the trace itself doesn't carry (session, project, source manifest). */
+export interface TraceContext {
+    sessionId: string;
+    project?: string;
+    manifest?: string;
+    /** Override the timestamp (tests); defaults to now. */
+    ts?: string;
+}
+/** Project a DecisionTrace into the compact, content-free wire event. */
+export declare function toTraceEvent(trace: DecisionTrace, ctx: TraceContext): TraceEvent;
+/**
+ * Fire-and-forget POST of a trace event to the dashboard. Never throws and
+ * never blocks: governance must not depend on the dashboard being up.
+ */
+export declare function emitTrace(url: string, event: TraceEvent): void;

package/dist/trace-emit.js

@@ -0,0 +1,60 @@
+// Decision-trace emitter — POST a compact, content-free projection of a
+// kcp-agent DecisionTrace to a kcp-dashboard `/trace` endpoint.
+//
+// This is the emit side of the thought-graph decision layer. It is:
+//   - opt-in   — only fires when a dashboard URL is configured;
+//   - fail-open — a POST never throws or blocks governance;
+//   - content-free — unit ids, paths, gate names/verdicts, scores only. No
+//     unit content, no intents, no command bodies.
+//
+// See kcp-dashboard docs/thought-graph-phase2.md for the wire contract.
+/** Project a DecisionTrace into the compact, content-free wire event. */
+export function toTraceEvent(trace, ctx) {
+    const units = trace.units.map((u) => ({
+        id: u.id,
+        ...(u.path ? { path: u.path } : {}),
+        outcome: u.outcome,
+        ...(u.rejectedBy ? { rejected_by: u.rejectedBy } : {}),
+        ...(u.score !== undefined ? { score: u.score } : {}),
+        gates: u.gates.map((g) => ({
+            gate: g.gate,
+            verdict: g.passed ? "pass" : "fail",
+            ...(g.detail ? { detail: g.detail } : {}),
+        })),
+    }));
+    return {
+        kind: "decision_trace",
+        session_id: ctx.sessionId,
+        ts: ctx.ts ?? new Date().toISOString(),
+        ...(ctx.project ? { project: ctx.project } : {}),
+        ...(ctx.manifest ? { manifest: ctx.manifest } : {}),
+        task: trace.task,
+        ...(trace.asOf ? { as_of: trace.asOf } : {}),
+        selected: units.filter((u) => u.outcome === "selected").length,
+        skipped: units.filter((u) => u.outcome === "skipped").length,
+        gate_summary: (trace.gateSummary ?? []).map((g) => ({
+            gate: g.gate,
+            passed: g.passed,
+            failed: g.failed,
+        })),
+        units,
+    };
+}
+/**
+ * Fire-and-forget POST of a trace event to the dashboard. Never throws and
+ * never blocks: governance must not depend on the dashboard being up.
+ */
+export function emitTrace(url, event) {
+    try {
+        void fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(event),
+        }).catch(() => {
+            /* fail-open: the dashboard is best-effort telemetry */
+        });
+    }
+    catch {
+        /* never throw — e.g. malformed URL — governance continues regardless */
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcp-harness",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "mcpName": "no.cantara/kcp-harness",
   "description": "KCP Compliance Harness — MCP proxy that enforces deterministic knowledge governance for any agent",
   "type": "module",