kcp-harness 0.1.0

package/dist/proxy.js

@@ -0,0 +1,394 @@
+// MCP proxy server — the harness's main entry point.
+//
+// The proxy sits between an agent (upstream) and downstream MCP servers.
+// It presents itself as a single MCP server to the agent, aggregating
+// tools from all downstream servers plus the harness's own governance tools.
+//
+// Every tool call flows through the pipeline:
+//   classify → govern → execute → audit
+//
+// Governed calls are routed through the kcp-agent planner before the
+// downstream server is contacted. The agent can't bypass governance
+// because it only has access to the proxy's stdio — not the downstream
+// servers' stdio directly.
+import { createInterface } from "node:readline";
+import { classify } from "./classifier.js";
+import { govern } from "./governor.js";
+import { AuditLog, buildEvent, buildLifecycleEvent, buildDriftEvent, } from "./audit.js";
+import { createSession, nextSequence } from "./session.js";
+import { DownstreamManager } from "./downstream.js";
+import { callKcpTool } from "./kcp-bridge.js";
+const HARNESS_VERSION = "0.1.0";
+const PROTOCOL_VERSION = "2025-06-18";
+const rpcResult = (id, result) => ({
+    jsonrpc: "2.0",
+    id: id ?? null,
+    result,
+});
+const rpcError = (id, code, message) => ({
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: { code, message },
+});
+// -- Harness-specific tools --------------------------------------------------
+const HARNESS_TOOLS = [
+    {
+        name: "harness_status",
+        description: "Show the harness's current governance state: session ID, approved plans, " +
+            "known units, budget spent, and audit log path.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "harness_session",
+        description: "Show the current session's approved plans and their selected units. " +
+            "Use this to see what knowledge the governance layer has approved.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "harness_budget",
+        description: "Show the session budget ledger: ceiling, running totals, remaining budget, " +
+            "and itemized spend history.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "harness_temporal_check",
+        description: "Check all approved plans for temporal drift: re-evaluate against current " +
+            "time and report any plans that would produce different results now.",
+        inputSchema: { type: "object", properties: {} },
+    },
+];
+/** KCP tool names that the harness routes to kcp-agent directly. */
+const KCP_TOOLS = new Set(["kcp_plan", "kcp_load", "kcp_trace", "kcp_validate", "kcp_replay"]);
+export class HarnessProxy {
+    config;
+    downstream;
+    audit;
+    session;
+    constructor(options) {
+        this.config = options.config;
+        this.downstream = new DownstreamManager();
+        this.audit = options.audit ?? new AuditLog(options.config.audit.path);
+        // Derive budget ceiling from policy
+        const policy = options.config.governance.policy;
+        const ceiling = policy.budget
+            ? { amount: policy.budget.amount, currency: policy.budget.currency ?? "USDC" }
+            : undefined;
+        this.session = createSession(ceiling);
+    }
+    /** Start the proxy: spawn downstream servers and begin serving. */
+    async start() {
+        // Emit session start event
+        const seq = nextSequence(this.session);
+        this.audit.emit(buildLifecycleEvent(this.session.id, seq, "session_start", {
+            domains: this.config.governance.domains.length,
+            downstream: this.config.downstream.map((d) => d.name),
+            budget: this.session.ledger.getCeiling(),
+        }));
+        // Spawn and initialize downstream servers
+        for (const ds of this.config.downstream) {
+            try {
+                await this.downstream.add(ds);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                process.stderr.write(`[kcp-harness] failed to spawn downstream ${ds.name}: ${msg}\n`);
+            }
+        }
+    }
+    /** Shut down the proxy and all downstream connections. */
+    async stop() {
+        // Emit session end event
+        const seq = nextSequence(this.session);
+        this.audit.emit(buildLifecycleEvent(this.session.id, seq, "session_end", {
+            totalCalls: this.session.sequence,
+            budgetSnapshot: this.session.ledger.snapshot(),
+            plansCount: this.session.plans.size,
+            knownUnitsCount: this.session.known.size,
+        }));
+        await this.downstream.shutdown();
+    }
+    /** Handle one JSON-RPC message from the agent. */
+    async handleMessage(msg) {
+        switch (msg.method) {
+            case "initialize":
+                return rpcResult(msg.id, {
+                    protocolVersion: typeof msg.params?.["protocolVersion"] === "string"
+                        ? msg.params["protocolVersion"]
+                        : PROTOCOL_VERSION,
+                    capabilities: { tools: {} },
+                    serverInfo: { name: "kcp-harness", version: HARNESS_VERSION },
+                });
+            case "ping":
+                return rpcResult(msg.id, {});
+            case "tools/list":
+                return rpcResult(msg.id, { tools: this.listTools() });
+            case "tools/call": {
+                const name = String(msg.params?.["name"] ?? "");
+                const args = (msg.params?.["arguments"] ?? {});
+                return this.handleToolCall(msg.id, name, args);
+            }
+            default:
+                // Notifications (no id) are acknowledged silently
+                if (msg.id === undefined || msg.method?.startsWith("notifications/"))
+                    return null;
+                return rpcError(msg.id, -32601, `method not found: ${msg.method}`);
+        }
+    }
+    /** List all available tools (downstream + harness + KCP). */
+    listTools() {
+        const downstreamTools = this.downstream.allTools();
+        // Import KCP tools from kcp-agent
+        const kcpTools = [
+            {
+                name: "kcp_plan",
+                description: "Produce a deterministic, inspectable load plan for a task against a KCP knowledge.yaml. " +
+                    "Routes through the governance harness for compliance tracking.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        task: { type: "string", description: "The task to plan knowledge loading for" },
+                        manifest: { type: "string", description: "Path, directory, or HTTPS URL of a knowledge.yaml" },
+                    },
+                    required: ["task", "manifest"],
+                },
+            },
+            {
+                name: "kcp_load",
+                description: "Plan and load knowledge content through the governance harness. " +
+                    "Automatically tracks session dedup and budget.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        task: { type: "string", description: "The task to plan knowledge loading for" },
+                        manifest: { type: "string", description: "Path, directory, or HTTPS URL of a knowledge.yaml" },
+                    },
+                    required: ["task", "manifest"],
+                },
+            },
+            {
+                name: "kcp_trace",
+                description: "Produce a decision trace: every unit annotated with gate cascade verdicts.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        task: { type: "string", description: "The task to trace" },
+                        manifest: { type: "string", description: "Path, directory, or HTTPS URL of a knowledge.yaml" },
+                    },
+                    required: ["task", "manifest"],
+                },
+            },
+            {
+                name: "kcp_validate",
+                description: "Validate (lint) a knowledge.yaml.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        manifest: { type: "string", description: "Path, directory, or HTTPS URL of a knowledge.yaml" },
+                    },
+                    required: ["manifest"],
+                },
+            },
+            {
+                name: "kcp_replay",
+                description: "Cross-examine a saved plan artifact against live manifests.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        artifact: { description: "The plan artifact JSON" },
+                    },
+                    required: ["artifact"],
+                },
+            },
+        ];
+        return [...HARNESS_TOOLS, ...kcpTools, ...downstreamTools];
+    }
+    /** Handle a tool call through the governance pipeline. */
+    async handleToolCall(id, toolName, args) {
+        const startTime = Date.now();
+        const seq = nextSequence(this.session);
+        try {
+            // Step 1: Classify
+            const classification = classify(toolName, args, this.config.governance.domains);
+            // Step 2: Govern (for governed calls)
+            let governance;
+            if (classification.governed) {
+                governance = await govern(classification, toolName, args, this.session, this.config.governance.policy);
+                if (!governance.approved) {
+                    // Blocked — emit audit and return error
+                    const event = buildEvent(this.session.id, seq, toolName, args, classification, governance, "blocked", Date.now() - startTime);
+                    this.audit.emit(event);
+                    return rpcResult(id, {
+                        content: [
+                            {
+                                type: "text",
+                                text: `[kcp-harness] BLOCKED: ${governance.reason}`,
+                            },
+                        ],
+                        isError: true,
+                    });
+                }
+            }
+            // Step 3: Execute
+            let result;
+            if (HARNESS_TOOLS.some((t) => t.name === toolName)) {
+                // Harness-internal tool
+                result = await this.handleHarnessTool(toolName, args);
+            }
+            else if (KCP_TOOLS.has(toolName)) {
+                // KCP tool — delegate to kcp-agent via the bridge
+                const text = await callKcpTool(toolName, args);
+                result = { content: [{ type: "text", text }], isError: false };
+            }
+            else {
+                // Downstream tool — forward to the owning downstream server
+                result = await this.downstream.callTool(toolName, args);
+            }
+            // Step 4: Audit
+            const outcome = classification.governed ? "approved" : "pass-through";
+            if (this.config.governance.policy.audit_all || classification.governed) {
+                const event = buildEvent(this.session.id, seq, toolName, args, classification, governance, outcome, Date.now() - startTime);
+                this.audit.emit(event);
+            }
+            return rpcResult(id, result);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            // Audit the error
+            const classification = classify(toolName, args, this.config.governance.domains);
+            const event = buildEvent(this.session.id, seq, toolName, args, classification, undefined, "error", Date.now() - startTime, msg);
+            this.audit.emit(event);
+            return rpcResult(id, {
+                content: [{ type: "text", text: `[kcp-harness] error: ${msg}` }],
+                isError: true,
+            });
+        }
+    }
+    /** Handle harness-internal tools. */
+    async handleHarnessTool(name, _args) {
+        switch (name) {
+            case "harness_status": {
+                const status = {
+                    session: {
+                        id: this.session.id,
+                        startedAt: this.session.startedAt,
+                        sequence: this.session.sequence,
+                        plansCount: this.session.plans.size,
+                        knownUnitsCount: this.session.known.size,
+                        budgetSpent: this.session.budgetSpent,
+                    },
+                    governance: {
+                        domains: this.config.governance.domains.length,
+                        policy: this.config.governance.policy,
+                    },
+                    downstream: this.config.downstream.map((d) => d.name),
+                    audit: { path: this.audit.getPath() },
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(status, null, 2) }],
+                    isError: false,
+                };
+            }
+            case "harness_session": {
+                const plans = {};
+                for (const [manifest, approved] of this.session.plans) {
+                    plans[manifest] = {
+                        task: approved.task,
+                        approvedAt: approved.approvedAt,
+                        selected: approved.plan.selected.map((u) => ({
+                            id: u.id,
+                            path: u.path,
+                            score: u.score,
+                            loadEligible: u.loadEligible,
+                        })),
+                        skipped: approved.plan.skipped.length,
+                    };
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ sessionId: this.session.id, plans }, null, 2) }],
+                    isError: false,
+                };
+            }
+            case "harness_budget": {
+                const snapshot = this.session.ledger.snapshot();
+                const entries = this.session.ledger.getEntries();
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                ...snapshot,
+                                entries: entries.map((e) => ({
+                                    seq: e.seq,
+                                    timestamp: e.timestamp,
+                                    manifest: e.source.manifest,
+                                    unitId: e.source.unitId,
+                                    amount: e.cost.amount,
+                                    currency: e.cost.currency,
+                                    method: e.cost.method,
+                                    runningTotal: e.runningTotal,
+                                })),
+                            }, null, 2),
+                        }],
+                    isError: false,
+                };
+            }
+            case "harness_temporal_check": {
+                const watchResult = await this.session.temporalWatch.check();
+                // Emit drift audit events for any drifted plans
+                for (const drift of watchResult.drifted) {
+                    const driftSeq = nextSequence(this.session);
+                    this.audit.emit(buildDriftEvent(this.session.id, driftSeq, drift));
+                }
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                checked: watchResult.checked,
+                                stable: watchResult.stable,
+                                drifted: watchResult.drifted.map((d) => ({
+                                    manifest: d.manifest,
+                                    task: d.task,
+                                    summary: d.summary,
+                                    moves: d.diff?.moves.length ?? 0,
+                                    scoreChanges: d.diff?.scoreChanges.length ?? 0,
+                                })),
+                                errors: watchResult.errors,
+                            }, null, 2),
+                        }],
+                    isError: false,
+                };
+            }
+            default:
+                return {
+                    content: [{ type: "text", text: `unknown harness tool: ${name}` }],
+                    isError: true,
+                };
+        }
+    }
+    /** Expose session for testing. */
+    getSession() {
+        return this.session;
+    }
+}
+/** Serve the harness proxy over stdio until stdin closes. */
+export async function serveProxy(config) {
+    const proxy = new HarnessProxy({ config });
+    await proxy.start();
+    const rl = createInterface({ input: process.stdin, terminal: false });
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            process.stdout.write(JSON.stringify(rpcError(null, -32700, "parse error")) + "\n");
+            continue;
+        }
+        const response = await proxy.handleMessage(msg);
+        if (response)
+            process.stdout.write(JSON.stringify(response) + "\n");
+    }
+    await proxy.stop();
+}

package/dist/session.d.ts

@@ -0,0 +1,50 @@
+import type { AgentPlan } from "kcp-agent";
+import { BudgetLedger, type BudgetCeiling } from "./budget-ledger.js";
+import { TemporalWatch } from "./temporal-watch.js";
+/** An approved plan — the set of units the agent is allowed to access. */
+export interface ApprovedPlan {
+    /** The manifest this plan came from. */
+    manifest: string;
+    /** The task the plan was created for. */
+    task: string;
+    /** The full plan from kcp-agent. */
+    plan: AgentPlan;
+    /** Timestamp when the plan was approved. */
+    approvedAt: string;
+}
+/** Session state for one agent connection. */
+export interface SessionState {
+    /** Unique session identifier. */
+    id: string;
+    /** Approved plans indexed by manifest source. */
+    plans: Map<string, ApprovedPlan>;
+    /** Units the session has loaded (id → sha256) for dedup. */
+    known: Map<string, string>;
+    /** Cumulative money budget spent this session. */
+    budgetSpent: number;
+    /** Monotonic sequence counter for audit events. */
+    sequence: number;
+    /** Session start time (ISO 8601). */
+    startedAt: string;
+    /** Budget ledger — itemized spend tracking. */
+    ledger: BudgetLedger;
+    /** Temporal watcher — detects plan drift. */
+    temporalWatch: TemporalWatch;
+}
+/** Create a fresh session state. */
+export declare function createSession(budgetCeiling?: BudgetCeiling): SessionState;
+/** Register an approved plan in the session. */
+export declare function addPlan(session: SessionState, manifest: string, task: string, plan: AgentPlan): void;
+/** Check if a file path is in any approved plan's selected units. */
+export declare function isPathApproved(session: SessionState, path: string): ApprovedPlan | undefined;
+/** Record a loaded unit's sha256 for session dedup. */
+export declare function recordLoaded(session: SessionState, id: string, sha256: string): void;
+/** Get the known[] set for passing to kcp_load. */
+export declare function getKnown(session: SessionState): Array<{
+    id: string;
+    sha256: string;
+}>;
+/** Record budget expenditure. */
+export declare function recordSpend(session: SessionState, amount: number): void;
+/** Get next sequence number (auto-increments). */
+export declare function nextSequence(session: SessionState): number;

package/dist/session.js

@@ -0,0 +1,82 @@
+// Session state — tracks approved plans, known units, and budget across calls.
+//
+// The session is the harness's ephemeral governance state. It lives for one
+// agent session (process lifetime) and is never persisted. All durable state
+// goes to the audit log.
+//
+// Key responsibilities:
+// 1. Track which plans the agent has established (approved unit sets)
+// 2. Track known[] for session dedup (units already loaded)
+// 3. Track cumulative budget spend
+// 4. Assign monotonic sequence numbers for audit correlation
+import { randomUUID } from "node:crypto";
+import { BudgetLedger } from "./budget-ledger.js";
+import { TemporalWatch } from "./temporal-watch.js";
+/** Create a fresh session state. */
+export function createSession(budgetCeiling) {
+    return {
+        id: randomUUID(),
+        plans: new Map(),
+        known: new Map(),
+        budgetSpent: 0,
+        sequence: 0,
+        startedAt: new Date().toISOString(),
+        ledger: new BudgetLedger(budgetCeiling),
+        temporalWatch: new TemporalWatch(),
+    };
+}
+/** Register an approved plan in the session. */
+export function addPlan(session, manifest, task, plan) {
+    session.plans.set(manifest, { manifest, task, plan, approvedAt: new Date().toISOString() });
+}
+/** Check if a file path is in any approved plan's selected units. */
+export function isPathApproved(session, path) {
+    for (const approved of session.plans.values()) {
+        for (const unit of approved.plan.selected) {
+            if (unit.loadEligible && pathMatchesUnit(path, unit, approved.manifest)) {
+                return approved;
+            }
+        }
+    }
+    return undefined;
+}
+/** Check if a unit path matches a target file path (relative resolution). */
+function pathMatchesUnit(targetPath, unit, manifestSource) {
+    const unitPath = unit.path;
+    // Direct match
+    if (targetPath === unitPath)
+        return true;
+    if (targetPath.endsWith("/" + unitPath))
+        return true;
+    if (targetPath.endsWith(unitPath))
+        return true;
+    // Resolve relative to manifest directory
+    if (manifestSource) {
+        const manifestDir = manifestSource.replace(/\/[^/]*$/, "");
+        const resolved = manifestDir + "/" + unitPath;
+        if (targetPath === resolved)
+            return true;
+        if (normalizePath(targetPath) === normalizePath(resolved))
+            return true;
+    }
+    return false;
+}
+function normalizePath(p) {
+    return p.replace(/\/+/g, "/").replace(/^\.\//, "");
+}
+/** Record a loaded unit's sha256 for session dedup. */
+export function recordLoaded(session, id, sha256) {
+    session.known.set(id, sha256);
+}
+/** Get the known[] set for passing to kcp_load. */
+export function getKnown(session) {
+    return Array.from(session.known.entries()).map(([id, sha256]) => ({ id, sha256 }));
+}
+/** Record budget expenditure. */
+export function recordSpend(session, amount) {
+    session.budgetSpent += amount;
+}
+/** Get next sequence number (auto-increments). */
+export function nextSequence(session) {
+    return ++session.sequence;
+}

package/dist/temporal-watch.d.ts

@@ -0,0 +1,63 @@
+import { type AgentPlan, type PlanDiff, type FollowOptions } from "kcp-agent";
+/** A plan registered for temporal watching. */
+export interface WatchedPlan {
+    /** The manifest source. */
+    manifest: string;
+    /** The task the plan was created for. */
+    task: string;
+    /** The approved plan. */
+    plan: AgentPlan;
+    /** FollowOptions used to create the plan (for re-evaluation). */
+    followOptions: FollowOptions;
+    /** When the plan was registered. */
+    registeredAt: string;
+    /** Last time this plan was checked. */
+    lastChecked?: string;
+}
+/** Result of checking a single plan for temporal drift. */
+export interface DriftResult {
+    /** The manifest that was checked. */
+    manifest: string;
+    /** The task. */
+    task: string;
+    /** Whether the plan has drifted. */
+    drifted: boolean;
+    /** The diff (if drifted). */
+    diff?: PlanDiff;
+    /** The new plan (if drifted). */
+    newPlan?: AgentPlan;
+    /** Human-readable summary. */
+    summary: string;
+    /** Timestamp of the check. */
+    checkedAt: string;
+}
+/** Result of checking all watched plans. */
+export interface WatchResult {
+    /** Total plans checked. */
+    checked: number;
+    /** Plans that have drifted. */
+    drifted: DriftResult[];
+    /** Plans that are still valid. */
+    stable: number;
+    /** Plans that couldn't be re-evaluated (manifest unavailable, etc.). */
+    errors: Array<{
+        manifest: string;
+        error: string;
+    }>;
+}
+/** Temporal plan watcher. */
+export declare class TemporalWatch {
+    private watched;
+    /** Register a plan for temporal watching. */
+    register(manifest: string, task: string, plan: AgentPlan, followOptions: FollowOptions): void;
+    /** Remove a plan from watching (e.g., after invalidation). */
+    unregister(manifest: string): void;
+    /** Check all watched plans for temporal drift. */
+    check(): Promise<WatchResult>;
+    /** Check a single plan for temporal drift. */
+    checkOne(watched: WatchedPlan): Promise<DriftResult>;
+    /** Get all watched plans. */
+    getWatched(): ReadonlyMap<string, WatchedPlan>;
+    /** Get a watched plan by manifest. */
+    get(manifest: string): WatchedPlan | undefined;
+}