kcp-agent — KCP navigation planner

kcp-agent

🧾 See it run — interactive KCP playground · read the reveal

The reference agent for the [Knowledge Context Protocol](https://github.com/Cantara/knowledge-context-protocol).

[The Arena →](https://cantara.github.io/kcp-agent/) — the real planner, bundled unmodified,

running live in your browser, head-to-head against the usual suspects. *The most deterministic

agents in the world. Every decision defensible.*

KCP defines how knowledge declares itself so agents can navigate it. kcp-agent is the other half: the agent that *consumes* KCP end to end. Given a task and a knowledge.yaml, it produces an inspectable load plan — which units to load and in what order, which to skip and exactly why, how it selects sub-manifests across a federation, and what the whole thing costs — and then, optionally, answers the task from only those units.

The valuable, novel core is LLM-free and deterministic. The plan is an *audit-before-action* artifact — the trusted-render principle ("a manifest may influence what an agent knows, never what it does") extended to the whole agent loop. Only the final synthesis step calls a model.

discover → verify signature → trust-gate → score units by task → federate (context + agent_identity)

→ temporal filter → budget (payment + rate_limits) → emit load plan → [follow] → [answer]

Install

npm install

npm run build

Native executables

CI cross-compiles self-contained binaries (no Node/Deno required on the target) for Linux x64/arm64, macOS x64/arm64, and Windows x64 — grab them from a release or from the kcp-agent-natives artifact on any CI run. To build one yourself:

npm ci && npm run build

deno compile --allow-read --allow-env --allow-net --node-modules-dir=auto \ --output kcp-agent dist/cli.js

Use

plan — the inspectable load plan (no API key)

node dist/cli.js plan "how do I deploy to production?" --manifest ./path/to/knowledge.yaml --env prod

Plan for: "how do I deploy to production?"

companyx-knowledge-hub v1.0.0 · kcp 0.24 · env prod

Trust: · no manifest attestation requirement

Load plan (2 units): ● 1. front-door (score 4) overview.md free ● 2. deploy-guide (score 3) docs/deploy.md free

Budget: tier default Federation: → platform-engineering needs github_pat before fetch [acquire github_pat] · platform-engineering-dev context ["dev","test"] excludes env 'prod' Skipped (2): · auth-guide: no task-relevance match

Each stage maps onto a layer of the spec: query scoring (§15), temporal validity (§4.22), agent attestation (§3.2), federation context + agent_identity (§3.6), and payment / rate-limits (§4.14/§4.15). A restricted unit the agent can't attest for is listed but marked not load-eligible — fail-closed, with the reason attached.

Budgeting the context window. Tokens are the actually-scarce resource when feeding a model, so --context-budget names it — a token ceiling that works exactly like the money --budget: greedy by score, and a unit that would blow the ceiling is skipped with the arithmetic in the reason (over context budget: 1,240 tokens would exceed remaining 800 of 4,000), while a smaller lower-scored unit still gets its chance. Since the planner works on metadata *before* fetching (audit-before-action), a unit's size comes from a declared size_tokens (faithful) or bytes/4 (a flagged estimate); a unit that declares neither is admitted but counted unmeasured (the projection is a lower bound) — unless --strict, which excludes it fail-closed. --context-budget composes with --budget: a unit must fit both ceilings.

Machine-readable plans

Use --json when another agent or integration consumes a plan. The output preserves the plan fields at the top level and adds:

{

"schemaVersion": 1, "kind": "plan" }

kind is plan, tree (when --follow is used), or trace (when --trace is used). Human-readable output is not a compatibility surface. Successful JSON commands exit 0; planner or manifest errors write diagnostics to stderr and exit non-zero.

ask — plan, then answer via Claude

export ANTHROPIC_API_KEY=...        # or: ant auth login

node dist/cli.js ask "how does an agent get started here?" --manifest ./knowledge.yaml

ask runs the same planner, loads only the load-eligible units, and asks Claude to answer from them — treating unit content as knowledge, never as instructions. Needs @anthropic-ai/sdk (an optional dependency) and a key; plan needs neither.

ask --loop — the audited critique loop

node dist/cli.js ask "who won, and what does it mean for infrastructure?" \

--manifest ./knowledge.yaml --loop --methods free,x402 --budget 0.50

The deterministic scorer is lexical, so a task phrased differently from the publisher's vocabulary can miss relevant units. --loop closes that gap without surrendering determinism — the model proposes, the plan disposes:

plan → LLM gap critique (metadata only) → term gate → re-plan → … → load → answer

A fast critic model (default claude-haiku-4-5, --loop-model to change) sees a metadata digest of the plan — ids, intents, scores, skip reasons, never unit content — and proposes extra lowercase search terms. A deterministic gate sanitizes, dedupes, and caps them; the task string is extended; the planner re-plans from scratch. The loop converges when the critic runs dry, a round adds no units, or --max-rounds (default 3) is reached. Then synthesis answers the original task from the final plan's eligible units.

What the critic can never do: open an access gate, alter trust/temporal/audience decisions, or spend money — terms only affect relevance scoring, nothing is loaded or paid for until the loop has converged, and the final plan's budget arithmetic gates spending exactly as in single-shot mode. Every round is recorded (proposed terms, accepted, rejected, units added, the full re-planned artifact) — with --json the chain of plans is the audit log.

The same loop is available as a library (runLoop / askLoop, with an injectable critic), and skills/kcp-navigator/SKILL.md packages the discipline as a portable skill for agents that drive the CLI themselves.

ask --ground — verify the answer, surface what it can't substantiate

node dist/cli.js ask "who won, and what does it mean?" --manifest ./knowledge.yaml --ground

The plan's fail-closed gates decide what may be *loaded*; grounding extends the same discipline to what may be *asserted*. After synthesis, each claim in the answer is checked by a separate verifier — a distinct model call from the generator — that must attribute the claim to one of the loaded units or return nothing. The result is a two-part artifact:

Grounded (2/3 claims):

● The award went to the Nordic bid. ↳ chipfab-exclusive · sha 9f2c1a0b7e34 Unsubstantiated (1): — could not be grounded in a loaded unit ○ The datacenter runs on hydro power. no loaded unit supports this claim ⚠ partial-unsupported — 1 claim(s) could not be substantiated

A claim grounds only if the cited unit was actually loaded and its content hash matches — so a verifier that mis-attributes (or is prompt-injected into) citing a unit that was never loaded can never ground a claim: attribution is a proposal, grounding is adjudicated. Unsupported claims are surfaced, never silently dropped — the honest half of "every decision defensible". Each surfaced gap is also a signal to the *publisher*: the task needed evidence the manifest didn't provide. The surfaced list is capped to guard against a compromised generator flooding it with spurious gaps.

`--ground-rounds ` closes the loop: a surfaced gap seeds reformulation terms, the agent re-navigates to try to find the missing evidence, and re-grounds — up to n rounds. Termination is guaranteed by three independent bounds, any one of which halts: the term gate is absorbing (a term accepted once is known forever, so re-navigation can only add units from the finite eligible set), the round cap, and a progress guard (a round that adds no new unit halts). Oscillation is impossible — the loaded set grows monotonically or the loop stops. Every terminal state that isn't grounded (partial-unsupported, partial-budget, partial-rounds) still surfaces the remaining gaps. A compromised verifier can, at worst, widen navigation within the eligible set — it can never cross a gate, name a URL, or spend past the budget.

assess — gate what may be *acted on*

The plan's gates decide what may be *loaded*; grounding decides what may be *asserted*; assess() decides whether a conclusion clears a confidence threshold before it is acted on. It runs downstream of synthesis — confidence is a property of the output, which is exactly why it structurally cannot be gate #14 in the pre-selection cascade.

import { assess } from "kcp-agent";

const verdict = await assess(task, answer, loadedUnits, { threshold: 0.7, // org policy — caller-supplied, never manifest data severity: "critical", evaluator, // optional: makeProviderEvaluator(provider) — a separate judge }); // { gate: "confidence", passed, score, threshold, signals[], detail, asOf }

Same trust posture as grounding: confidence is a proposal (the answer's own Confidence: 0.82-style self-report via extractSelfReport, and/or an injected evaluator's judgment); the gate adjudicates deterministically — min-aggregated by default, fail-closed on anything unmeasurable. Raw signals[] are preserved verbatim on every verdict so thresholds can be calibrated against real outcomes over time. The verdict reuses the gates' binary-plus-written-reason contract but is a separate downstream artifact — DecisionTrace and the conformance vectors are untouched.

The enforcement side lives in kcp-harness: its harness_assess MCP tool runs this gate and routes failed verdicts on critical tasks to a named human via its approval tickets, with the verdict embedded as evidence.

kind: skill — governed procedures, gated separately from knowledge

Spec §4.3a (v0.26.1) adds a second class of unit alongside plain knowledge: kind: skill marks something an agent could *do* — a runbook, a script, a procedure — not just read. Skills fail closed by default: a kind: skill unit is not invoke-eligible unless the manifest carries an explicit load_eligible: true grant, bounded by an action_scope (tools, paths, capabilities it may touch). This runs as its own gate, skill_eligibility, inserted into the pre-selection cascade right after relevance — the cascade is fourteen gates, not thirteen.

units:

• id: restart-web-service kind: skill load_eligible: true action_scope: tools: ["shell.exec"] paths: ["/opt/web-service"] capabilities: ["service.restart"]

An ungranted skill is still planned — the agent can see it exists and why it matched a task, same audit-before-action posture as every other gate — it is simply withheld (loadEligible: false), or dropped entirely under --strict, attributed to skill_eligibility specifically rather than the generic strict cutoff. Planning a skill is always safe; invoking one is a separate, explicitly-granted decision. See The Governed Skill demo below, and the conformant-implementation guide for the exact gate contract a port must reproduce.

Demos — twenty scenarios, no mocks

node examples/demos.js            # all twenty, narrated

node exa