kcp-harness 0.1.0

package/dist/integrations/copilot.js

@@ -0,0 +1,69 @@
+// GitHub Copilot integration — .vscode/mcp.json + .github/copilot-instructions.md
+//
+// IMPORTANT: VS Code Copilot uses "servers" as the top-level key,
+// NOT "mcpServers" like every other agent. MCP tools are only
+// available in Agent mode.
+import { harnessServerEntry, governedPathsBlock, manifestRef } from "./generate.js";
+export function generateCopilot(options) {
+    const server = harnessServerEntry(options);
+    const manifest = manifestRef(options);
+    // VS Code uses "servers" (not "mcpServers")
+    const vscodeMcp = {
+        path: ".vscode/mcp.json",
+        content: JSON.stringify({
+            servers: {
+                "kcp-harness": {
+                    type: "stdio",
+                    ...server,
+                },
+            },
+        }, null, 2) + "\n",
+        commitToGit: true,
+        description: "VS Code MCP config — note: uses 'servers' key (not 'mcpServers'). Agent mode only.",
+    };
+    const instructions = {
+        path: ".github/copilot-instructions.md",
+        content: `# Knowledge Governance
+
+This project uses the KCP Compliance Harness for deterministic knowledge governance.
+
+## Governed Paths
+
+${governedPathsBlock(options)}
+
+These paths are governed by \`${manifest}\`. Use the kcp-harness MCP server to access them.
+
+## Rules
+
+1. Always call \`kcp_plan\` or \`kcp_load\` (via the kcp-harness MCP server) before reading governed files
+2. The harness enforces budget ceilings, temporal validity, and access control
+3. Use \`harness_status\` to check governance state
+4. Direct file reads of governed paths may be blocked by the governance layer
+
+## Available MCP Tools
+
+- \`kcp_plan\` — deterministic load plan
+- \`kcp_load\` — plan + load content
+- \`kcp_trace\` — decision trace (13-gate cascade)
+- \`harness_budget\` — session spend tracking
+- \`harness_temporal_check\` — plan drift detection
+`,
+        commitToGit: true,
+        description: "GitHub Copilot instructions — governance rules",
+    };
+    return {
+        agent: "copilot",
+        name: "GitHub Copilot",
+        files: [vscodeMcp, instructions],
+        instructions: `## GitHub Copilot Integration
+
+**IMPORTANT:** VS Code Copilot uses \`"servers"\` as the top-level key in \`.vscode/mcp.json\` — NOT \`"mcpServers"\`. MCP tools are only available in **Agent mode** (not Ask or Edit mode).
+
+**Setup:**
+1. Place \`.vscode/mcp.json\` in your project root
+2. Place \`.github/copilot-instructions.md\` in your project root
+3. In VS Code, switch Copilot Chat to Agent mode to access kcp-harness tools
+
+For Copilot CLI, add to \`~/.copilot/mcp-config.json\` instead (uses \`mcpServers\` key + \`tools: ["*"]\`).`,
+    };
+}

package/dist/integrations/crush.d.ts

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

package/dist/integrations/crush.js

@@ -0,0 +1,48 @@
+// Crush integration — MCP config + PrepareStep pattern documentation.
+//
+// Crush is a multi-model agent (30+ models) with native MCP support.
+// The PrepareStep pattern lets Crush pre-load knowledge before the
+// main task runs, ensuring governed knowledge is available in context.
+import { harnessServerEntry, manifestRef } from "./generate.js";
+export function generateCrush(options) {
+    const server = harnessServerEntry(options);
+    const manifest = manifestRef(options);
+    const crushJson = {
+        path: "crush.json",
+        content: JSON.stringify({
+            mcpServers: {
+                "kcp-harness": server,
+            },
+            prepareSteps: [
+                {
+                    name: "load-knowledge",
+                    description: "Pre-load governed knowledge via KCP harness",
+                    tool: "kcp_plan",
+                    arguments: {
+                        task: "{{task}}",
+                        manifest: manifest,
+                    },
+                },
+            ],
+        }, null, 2) + "\n",
+        commitToGit: true,
+        description: "Crush MCP config with PrepareStep for knowledge pre-loading",
+    };
+    return {
+        agent: "crush",
+        name: "Crush",
+        files: [crushJson],
+        instructions: `## Crush Integration
+
+**Setup:**
+1. Place \`crush.json\` in your project root
+2. Crush will auto-discover the kcp-harness MCP server
+
+The \`prepareSteps\` configuration runs \`kcp_plan\` before each task, pre-loading the governance plan. This ensures:
+- The harness has an approved plan before Crush accesses any files
+- Plan-first mode kicks in for subsequent reads (fast path)
+- Budget is tracked from the first tool call
+
+The \`{{task}}\` placeholder is replaced with Crush's current task description.`,
+    };
+}

package/dist/integrations/cursor.d.ts

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

package/dist/integrations/cursor.js

@@ -0,0 +1,65 @@
+// Cursor integration — .cursor/mcp.json + .cursor/rules/kcp-governance.mdc
+import { harnessServerEntry, governedPathsBlock, manifestRef } from "./generate.js";
+export function generateCursor(options) {
+    const server = harnessServerEntry(options);
+    const manifest = manifestRef(options);
+    const paths = options.paths ?? ["docs/", "src/"];
+    const mcpJson = {
+        path: ".cursor/mcp.json",
+        content: JSON.stringify({
+            mcpServers: {
+                "kcp-harness": server,
+            },
+        }, null, 2) + "\n",
+        commitToGit: true,
+        description: "Cursor MCP config — adds kcp-harness as governance proxy",
+    };
+    const rulesFile = {
+        path: ".cursor/rules/kcp-governance.mdc",
+        content: `---
+globs: [${paths.map((p) => `"${p}**"`).join(", ")}]
+alwaysApply: true
+---
+
+# KCP Knowledge Governance
+
+This project enforces deterministic knowledge governance via the KCP Compliance Harness.
+
+## Governed Paths
+
+${governedPathsBlock(options)}
+
+These paths are governed by \`${manifest}\`. Access is controlled by the kcp-agent planner (13-gate cascade).
+
+## Required Workflow
+
+1. **Before reading governed files**, call \`kcp_plan\` or \`kcp_load\` via the kcp-harness MCP server
+2. The harness will classify your tool calls and route knowledge-navigation through the planner
+3. Direct file reads of governed paths will be blocked if no approved plan exists
+
+## Available Tools (via kcp-harness MCP server)
+
+- \`kcp_plan\` — produce a load plan without loading content
+- \`kcp_load\` — plan + load content of eligible units
+- \`kcp_trace\` — see the 13-gate decision trace
+- \`harness_status\` — check governance state
+- \`harness_budget\` — check remaining budget
+- \`harness_temporal_check\` — verify plan temporal validity
+`,
+        commitToGit: true,
+        description: "Cursor rules — governance instructions scoped to governed paths",
+    };
+    return {
+        agent: "cursor",
+        name: "Cursor",
+        files: [mcpJson, rulesFile],
+        instructions: `## Cursor Integration
+
+1. Place \`.cursor/mcp.json\` in your project root — Cursor loads MCP servers from here
+2. Place \`.cursor/rules/kcp-governance.mdc\` — Cursor applies these rules when editing governed paths
+
+**Setup:** Copy the generated files to your project root. Restart Cursor to pick up the MCP server.
+
+The \`.mdc\` file uses glob-scoped rules so governance instructions only activate when working in governed directories.`,
+    };
+}

package/dist/integrations/generate.d.ts

@@ -0,0 +1,13 @@
+import type { AgentTarget, IntegrationOutput, IntegrationOptions } from "./types.js";
+/** Generate integration files for a specific agent. */
+export declare function generate(agent: AgentTarget, options?: IntegrationOptions): IntegrationOutput;
+/** Generate integration files for all agents. */
+export declare function generateAll(options?: IntegrationOptions): IntegrationOutput[];
+/** List all supported agent targets. */
+export declare function listAgents(): AgentTarget[];
+/** Build the MCP server entry for kcp-harness. */
+export declare function harnessServerEntry(options: IntegrationOptions): Record<string, unknown>;
+/** Build governed paths description for rules files. */
+export declare function governedPathsBlock(options: IntegrationOptions): string;
+/** Build manifest reference for rules files. */
+export declare function manifestRef(options: IntegrationOptions): string;

package/dist/integrations/generate.js

@@ -0,0 +1,60 @@
+// Integration generator — produce agent-specific configs from harness config.
+//
+// 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 { generateClaudeCode } from "./claude-code.js";
+import { generateCursor } from "./cursor.js";
+import { generateWindsurf } from "./windsurf.js";
+import { generateCline } from "./cline.js";
+import { generateContinue } from "./continue.js";
+import { generateCopilot } from "./copilot.js";
+import { generateCrush } from "./crush.js";
+import { generateOpenClaw } from "./openclaw.js";
+const GENERATORS = {
+    "claude-code": generateClaudeCode,
+    cursor: generateCursor,
+    windsurf: generateWindsurf,
+    cline: generateCline,
+    continue: generateContinue,
+    copilot: generateCopilot,
+    "copilot-cli": generateCopilot, // Same format, different path
+    crush: generateCrush,
+    openclaw: generateOpenClaw,
+};
+/** Generate integration files for a specific agent. */
+export function generate(agent, options = {}) {
+    const gen = GENERATORS[agent];
+    if (!gen)
+        throw new Error(`unsupported agent: ${agent}`);
+    return gen(options);
+}
+/** Generate integration files for all agents. */
+export function generateAll(options = {}) {
+    return Object.keys(GENERATORS).map((agent) => generate(agent, options));
+}
+/** List all supported agent targets. */
+export function listAgents() {
+    return Object.keys(GENERATORS);
+}
+// -- Shared helpers for generators ------------------------------------------
+/** Build the MCP server entry for kcp-harness. */
+export function harnessServerEntry(options) {
+    return {
+        command: options.harnessCommand ?? "npx",
+        args: options.harnessArgs ?? [
+            "kcp-harness",
+            "serve",
+            ...(options.harnessConfig ? ["--config", options.harnessConfig] : []),
+        ],
+    };
+}
+/** Build governed paths description for rules files. */
+export function governedPathsBlock(options) {
+    const paths = options.paths ?? ["docs/", "src/"];
+    return paths.map((p) => `  - \`${p}\``).join("\n");
+}
+/** Build manifest reference for rules files. */
+export function manifestRef(options) {
+    return options.manifest ?? "./knowledge.yaml";
+}

package/dist/integrations/openclaw.d.ts

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

package/dist/integrations/openclaw.js

@@ -0,0 +1,67 @@
+// OpenClaw integration — openclaw.json + plugin hooks documentation.
+//
+// OpenClaw is an open-source multi-channel agent with plugin hooks:
+//   - before_prompt_build: inject kcp-loaded knowledge into prompt
+//   - before_agent_finalize: post-synthesis claim verification
+//
+// OpenClaw's MCP support uses the standard mcpServers key.
+import { harnessServerEntry, manifestRef } from "./generate.js";
+export function generateOpenClaw(options) {
+    const server = harnessServerEntry(options);
+    const manifest = manifestRef(options);
+    const openclawJson = {
+        path: "openclaw.json",
+        content: JSON.stringify({
+            mcpServers: {
+                "kcp-harness": server,
+            },
+            plugins: {
+                "kcp-governance": {
+                    hooks: {
+                        before_prompt_build: {
+                            tool: "kcp_load",
+                            arguments: {
+                                task: "{{task}}",
+                                manifest: manifest,
+                            },
+                            description: "Load governed knowledge via KCP harness before prompt assembly",
+                        },
+                        before_agent_finalize: {
+                            tool: "kcp_trace",
+                            arguments: {
+                                task: "{{task}}",
+                                manifest: manifest,
+                            },
+                            description: "Run decision trace for audit trail before finalizing agent response",
+                        },
+                    },
+                },
+            },
+        }, null, 2) + "\n",
+        commitToGit: true,
+        description: "OpenClaw MCP config with plugin hooks for knowledge governance",
+    };
+    return {
+        agent: "openclaw",
+        name: "OpenClaw",
+        files: [openclawJson],
+        instructions: `## OpenClaw Integration
+
+**Setup:**
+1. Place \`openclaw.json\` in your project root
+2. OpenClaw will auto-discover the kcp-harness MCP server
+
+**Plugin Hooks:**
+- \`before_prompt_build\` — calls \`kcp_load\` to inject governed knowledge before the prompt is assembled. This ensures the model sees governed knowledge as part of its context, not as a separate tool call.
+- \`before_agent_finalize\` — calls \`kcp_trace\` after the agent produces its response, creating a decision trace for the audit log.
+
+The \`{{task}}\` placeholder is replaced with OpenClaw's current task description.
+
+**Available MCP Tools:**
+- \`kcp_plan\` — deterministic load plan
+- \`kcp_load\` — plan + load content
+- \`kcp_trace\` — 13-gate decision trace
+- \`harness_budget\` — session spend tracking
+- \`harness_temporal_check\` — plan drift detection`,
+    };
+}

package/dist/integrations/types.d.ts

@@ -0,0 +1,51 @@
+/** Supported agent targets for integration generation. */
+export type AgentTarget = "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. */
+    agent: AgentTarget;
+    /** Display name. */
+    name: string;
+    /** Files to write (path → content). */
+    files: IntegrationFile[];
+    /** Human-readable setup instructions (markdown). */
+    instructions: string;
+}
+/** A file to write as part of the integration. */
+export interface IntegrationFile {
+    /** Relative path from project root. */
+    path: string;
+    /** File content. */
+    content: string;
+    /** Whether this file should be committed to git. */
+    commitToGit: boolean;
+    /** Description of what this file does. */
+    description: string;
+}
+/** Options for generating an integration. */
+export interface IntegrationOptions {
+    /** Path to the harness YAML config. */
+    harnessConfig?: string;
+    /** Governed knowledge.yaml path. */
+    manifest?: string;
+    /** Governed path prefixes. */
+    paths?: string[];
+    /** Project root (for relative path resolution). */
+    projectRoot?: string;
+    /** Custom harness command (default: npx kcp-harness serve). */
+    harnessCommand?: string;
+    /** Custom harness args. */
+    harnessArgs?: string[];
+}
+/** Agent metadata. */
+export interface AgentInfo {
+    target: AgentTarget;
+    name: string;
+    mcpSupport: boolean;
+    configFile: string;
+    rulesFile?: string;
+    topLevelKey: string;
+    notes?: string;
+}
+/** Registry of all supported agents. */
+export declare const AGENTS: Record<AgentTarget, AgentInfo>;

package/dist/integrations/types.js

@@ -0,0 +1,78 @@
+// Integration types — shared across all agent integration packages.
+/** Registry of all supported agents. */
+export const AGENTS = {
+    "claude-code": {
+        target: "claude-code",
+        name: "Claude Code",
+        mcpSupport: true,
+        configFile: ".mcp.json",
+        rulesFile: "CLAUDE.md",
+        topLevelKey: "mcpServers",
+        notes: "First-class MCP + hooks (PreToolUse)",
+    },
+    cursor: {
+        target: "cursor",
+        name: "Cursor",
+        mcpSupport: true,
+        configFile: ".cursor/mcp.json",
+        rulesFile: ".cursor/rules/kcp-governance.mdc",
+        topLevelKey: "mcpServers",
+    },
+    windsurf: {
+        target: "windsurf",
+        name: "Windsurf",
+        mcpSupport: true,
+        configFile: "~/.codeium/windsurf/mcp_config.json",
+        rulesFile: ".windsurfrules",
+        topLevelKey: "mcpServers",
+        notes: "Global config only (no per-project MCP file)",
+    },
+    cline: {
+        target: "cline",
+        name: "Cline",
+        mcpSupport: true,
+        configFile: "cline_mcp_settings.json",
+        rulesFile: ".clinerules",
+        topLevelKey: "mcpServers",
+        notes: "Config managed via VS Code extension UI",
+    },
+    continue: {
+        target: "continue",
+        name: "Continue",
+        mcpSupport: true,
+        configFile: ".continue/mcpServers/kcp-harness.yaml",
+        topLevelKey: "mcpServers",
+    },
+    copilot: {
+        target: "copilot",
+        name: "GitHub Copilot",
+        mcpSupport: true,
+        configFile: ".vscode/mcp.json",
+        rulesFile: ".github/copilot-instructions.md",
+        topLevelKey: "servers",
+        notes: "Uses 'servers' not 'mcpServers'. Agent mode only.",
+    },
+    "copilot-cli": {
+        target: "copilot-cli",
+        name: "GitHub Copilot CLI",
+        mcpSupport: true,
+        configFile: "~/.copilot/mcp-config.json",
+        topLevelKey: "mcpServers",
+    },
+    crush: {
+        target: "crush",
+        name: "Crush",
+        mcpSupport: true,
+        configFile: "crush.json",
+        topLevelKey: "mcpServers",
+        notes: "PrepareStep pattern for knowledge pre-loading",
+    },
+    openclaw: {
+        target: "openclaw",
+        name: "OpenClaw",
+        mcpSupport: true,
+        configFile: "openclaw.json",
+        topLevelKey: "mcpServers",
+        notes: "Plugin hooks: before_prompt_build, before_agent_finalize",
+    },
+};

package/dist/integrations/windsurf.d.ts

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

package/dist/integrations/windsurf.js

@@ -0,0 +1,67 @@
+// Windsurf (Codeium) integration — global MCP config + .windsurfrules
+import { harnessServerEntry, governedPathsBlock, manifestRef } from "./generate.js";
+export function generateWindsurf(options) {
+    const server = harnessServerEntry(options);
+    const manifest = manifestRef(options);
+    // Windsurf uses a GLOBAL config — we generate the snippet to add
+    const mcpSnippet = {
+        path: "windsurf-mcp-snippet.json",
+        content: JSON.stringify({
+            "kcp-harness": server,
+        }, null, 2) + "\n",
+        commitToGit: false,
+        description: "MCP snippet to add to ~/.codeium/windsurf/mcp_config.json (global config)",
+    };
+    const rulesFile = {
+        path: ".windsurfrules",
+        content: `# KCP Knowledge Governance
+
+This project uses the KCP Compliance Harness for deterministic knowledge access control.
+
+## Governed Paths
+
+${governedPathsBlock(options)}
+
+These paths are governed by \`${manifest}\`.
+
+## Rules
+
+1. Always call \`kcp_plan\` or \`kcp_load\` (via the kcp-harness MCP server) before reading governed files
+2. The harness intercepts tool calls and routes knowledge access through the kcp-agent planner
+3. Budget and temporal governance are enforced automatically
+4. Use \`harness_status\` to check the current governance state
+
+## Available MCP Tools
+
+- \`kcp_plan\` — deterministic load plan (no content)
+- \`kcp_load\` — plan + load eligible unit content
+- \`kcp_trace\` — 13-gate decision trace
+- \`harness_budget\` — session spend tracking
+- \`harness_temporal_check\` — plan drift detection
+`,
+        commitToGit: true,
+        description: "Windsurf rules — governance instructions for Cascade",
+    };
+    return {
+        agent: "windsurf",
+        name: "Windsurf",
+        files: [mcpSnippet, rulesFile],
+        instructions: `## Windsurf Integration
+
+Windsurf uses a **global** MCP config (not per-project).
+
+**Setup:**
+1. Add the kcp-harness entry to \`~/.codeium/windsurf/mcp_config.json\`:
+   \`\`\`json
+   {
+     "mcpServers": {
+       "kcp-harness": { ... }  // ← merge from windsurf-mcp-snippet.json
+     }
+   }
+   \`\`\`
+2. Place \`.windsurfrules\` in your project root
+3. Restart Windsurf
+
+The \`.windsurfrules\` file instructs Cascade to use kcp_load for governed knowledge access.`,
+    };
+}

package/dist/kcp-bridge.d.ts

@@ -0,0 +1,2 @@
+/** Call a KCP tool and return the result as a JSON string. */
+export declare function callKcpTool(name: string, args: Record<string, unknown>): Promise<string>;

package/dist/kcp-bridge.js

@@ -0,0 +1,85 @@
+// KCP bridge — call kcp-agent's planner functions from the harness.
+//
+// Instead of importing kcp-agent's internal MCP handler (which isn't part
+// of the public API), we use the exported planner functions directly.
+// This gives us the same results with type safety and a stable API surface.
+import { planTree, plans, loadPlannedUnits, loadManifest, trace as traceDecision, validateLocation, dedupeLoaded, } from "kcp-agent";
+/** Accept a JSON array or a comma-separated string — MCP callers send both. */
+function toList(v) {
+    if (Array.isArray(v))
+        return v.map(String);
+    if (typeof v === "string")
+        return v.split(",").map((s) => s.trim()).filter(Boolean);
+    return undefined;
+}
+/** Map MCP-style arguments to kcp-agent's FollowOptions. */
+function toFollowOptions(args) {
+    const methods = toList(args["methods"]);
+    const credentials = toList(args["credentials"]);
+    const planOptions = {
+        env: args["env"] === undefined ? undefined : String(args["env"]),
+        asOf: args["as_of"] === undefined ? undefined : String(args["as_of"]),
+        maxUnits: args["max_units"] === undefined ? undefined : Number(args["max_units"]),
+        strict: args["strict"] === true,
+        budget: args["budget"] === undefined
+            ? undefined
+            : { amount: Number(args["budget"]), currency: args["currency"] === undefined ? undefined : String(args["currency"]) },
+        contextBudget: args["context_budget"] === undefined ? undefined : Number(args["context_budget"]),
+        capabilities: {
+            ...(args["role"] === undefined ? {} : { role: String(args["role"]) }),
+            ...(methods ? { paymentMethods: methods } : {}),
+            ...(credentials ? { credentials } : {}),
+            ...(args["attest"] === undefined ? {} : { attestationProvider: String(args["attest"]) }),
+        },
+    };
+    return {
+        planOptions,
+        maxDepth: args["follow"] === true ? (args["max_depth"] === undefined ? 1 : Number(args["max_depth"])) : 0,
+        maxNodes: args["max_nodes"] === undefined ? undefined : Number(args["max_nodes"]),
+        fetchGuard: { allowPrivate: args["allow_private_hosts"] === true },
+    };
+}
+/** Call a KCP tool and return the result as a JSON string. */
+export async function callKcpTool(name, args) {
+    switch (name) {
+        case "kcp_plan": {
+            const tree = await planTree(String(args["manifest"] ?? ""), String(args["task"] ?? ""), toFollowOptions(args));
+            if (tree.error)
+                throw new Error(`${tree.location}: ${tree.error}`);
+            return JSON.stringify(tree, null, 2);
+        }
+        case "kcp_load": {
+            const follow = toFollowOptions(args);
+            const tree = await planTree(String(args["manifest"] ?? ""), String(args["task"] ?? ""), follow);
+            if (tree.error)
+                throw new Error(`${tree.location}: ${tree.error}`);
+            const loaded = [];
+            const unavailable = [];
+            for (const p of plans(tree)) {
+                const r = await loadPlannedUnits(p, follow.fetchGuard);
+                loaded.push(...r.loaded);
+                unavailable.push(...r.unavailable);
+            }
+            const { units, deduped, bytesSaved } = dedupeLoaded(loaded, args["known"]);
+            return JSON.stringify({ plan: tree, units, unavailable, deduped, bytesSaved }, null, 2);
+        }
+        case "kcp_trace": {
+            const follow = toFollowOptions(args);
+            const manifest = await loadManifest(String(args["manifest"] ?? ""), follow.fetchGuard);
+            const t = traceDecision(manifest, String(args["task"] ?? ""), follow.planOptions);
+            return JSON.stringify(t, null, 2);
+        }
+        case "kcp_validate": {
+            const guard = { allowPrivate: args["allow_private_hosts"] === true };
+            const report = await validateLocation(String(args["manifest"] ?? ""), guard);
+            return JSON.stringify(report, null, 2);
+        }
+        case "kcp_replay": {
+            // Replay requires importing the replay function — use dynamic import
+            // to keep the bridge lightweight for non-replay use cases.
+            throw new Error("kcp_replay not yet bridged — call kcp-agent directly");
+        }
+        default:
+            throw new Error(`unknown KCP tool: ${name}`);
+    }
+}

package/dist/proxy.d.ts

@@ -0,0 +1,37 @@
+import type { HarnessConfig } from "./config.js";
+import { type AuditWriter } from "./audit.js";
+import { type SessionState } from "./session.js";
+interface JsonRpcRequest {
+    jsonrpc?: string;
+    id?: number | string | null;
+    method?: string;
+    params?: Record<string, unknown>;
+}
+export interface ProxyOptions {
+    config: HarnessConfig;
+    audit?: AuditWriter;
+}
+export declare class HarnessProxy {
+    private readonly config;
+    private readonly downstream;
+    private readonly audit;
+    private readonly session;
+    constructor(options: ProxyOptions);
+    /** Start the proxy: spawn downstream servers and begin serving. */
+    start(): Promise<void>;
+    /** Shut down the proxy and all downstream connections. */
+    stop(): Promise<void>;
+    /** Handle one JSON-RPC message from the agent. */
+    handleMessage(msg: JsonRpcRequest): Promise<object | null>;
+    /** List all available tools (downstream + harness + KCP). */
+    private listTools;
+    /** Handle a tool call through the governance pipeline. */
+    private handleToolCall;
+    /** Handle harness-internal tools. */
+    private handleHarnessTool;
+    /** Expose session for testing. */
+    getSession(): SessionState;
+}
+/** Serve the harness proxy over stdio until stdin closes. */
+export declare function serveProxy(config: HarnessConfig): Promise<void>;
+export {};