@credence/kit

The facade + the agent tool surface + a standalone MCP server. One object carries the ledger, the rules engine, snapshots, matrix views and decision assessment; buildTools exposes the whole surface to any agent.

Renamed from @credence/tools in 0.4.0. That package still ships at 0.5.0 as a deprecated re-export and will be removed in a later minor.

import { createCredence, buildTools } from "@credence/kit";
// the MCP server lives on its own subpath, so a caller who only wants the tools
// never pulls the MCP SDK into their graph:
import { createMcpServer } from "@credence/kit/mcp";

// One call instead of three factories: ledger + rules engine + facade.
const credence = await createCredence({
  ontology,
  rules,
  views,
  actor: "agent:mcp",
  // stamped into every snapshot, so two that differ can say whether the world
  // changed or the agent did
  snapshotMeta: { policyBundle: "v7", model: "claude-opus-4-8" },
});

// Framework-agnostic descriptors (name, description, zod input shape, handler):
const tools = buildTools(credence);

// ...or serve over MCP (stdio):
const server = createMcpServer(credence);

createCredence is a convenience, not a requirement. The three-factory wiring (createLedger → createRulesEngine → new Credence({...})) still works and is the right shape when a host needs to hold the pieces apart.

Tools

open_case · resolve_entity · record_claim · record_absence · list_claims · record_relation · list_relations · resolve_ref · get_index · get_matrix · next_steps · check_coverage · scan_contradictions · dismiss_finding · open_obligation · list_obligations · transition_obligation · create_snapshot · diff_snapshots · record_decision · explain_decision · check_stale_decisions · verify_chain · checkpoint · hold_case · release_case · oversight_status · declare_intervention_point · list_intervention_points · set_autonomy_limit · record_iteration · add_source · add_evidence · list_findings · list_snapshots · list_decisions · merge_entities · search_entities · invalidate_claim · record_expectation.

Some of these carry the project's posture into the agent loop:

• record_claim / record_relation / add_evidence / transition_obligation take stance on every evidence entry (supports / contradicts / cited). Omit it to leave the link UNSTATED — never inferred, never defaulted to supports. cited is spelled out in the tool description on purpose: an agent that never learns the difference will only ever write supports. A verified write whose evidence all explicitly declines to support is refused.

• record_decision / explain_decision / check_stale_decisions — a decision records not only what was decided and why, but on what: a snapshotId pinning the epistemic baseline and a dependsOn list naming the claims, relations, findings and obligations it rested on. explain_decision then answers the question an auditor asks second — does it still stand? — by recomputing from the data, never from a stored flag. A decision recorded without a basis reports INDETERMINATE, never CURRENT: silence about what a decision rested on is not the same as nothing having changed, and putting the reassuring word on the decisions nobody can check is the exact failure this exists to prevent. Cite a finding with role: "contradicts" when deciding despite a known objection — when that objection later closes, the decision may be available on better terms, which reads very differently from a support going away.

• check_coverage — ask before paying for a lookup the ledger already answers. Advisory: it reports, the agent decides. Pass minStatus: "verified" when the lookup exists to verify, so hearsay doesn't suppress it. A contested key (open conflict, or a disputed claim) is reported as not covered — the ledger holding two answers is a reason to run the lookup, not to skip it.

• next_steps — open findings, pending expectations and outstanding obligations. With a phase catalogue configured, items gated behind a later phase are listed separately, never hidden.

• transition_obligation — marking something done requires evidence here too. A fulfilment you cannot point at is a promise, not a fact.

• scan_contradictions — cross-key contradictions, which need a judge. With none configured it says so plainly instead of returning an empty result that looks like "nothing wrong".

• verify_chain — recomputes the append-only hash chain and reports ok, broken (led by a !! CHAIN BROKEN !! marker line, with the failing sequence number and a reason code) or indeterminate. A case written before chaining existed can never read as ok: a clean bill of health on unverifiable history is worse than no answer. Every outcome states witnessed: yes|no, because a chain checked against nothing but itself proves only internal consistency to whoever holds the database. A broken chain is not returned as a tool error — the call succeeded; the trail is what failed. Credence stores no verdict: anyone holding the database can recompute this.

• checkpoint — exports that chain head as a small, self-describing attestation (caseId, seq, headHash, at, algorithm). Keep it where Credence cannot reach it and pass it back to verify_chain as witness; that is the only thing that catches a truncation the chain and its local anchor cannot see. Credence does not notarize, sign, or timestamp it — where the checkpoint lives is your control, not this library's.

• hold_case / release_case — stop a case for human review, and lift it. A hold never refuses a write: a ledger that stopped recording during a stop would destroy the very facts the human was called in to weigh. It changes what every read surface says and produces a blocker the caller gates on. A release supersedes the hold, it does not erase it — a case that was reviewed and let through must not become indistinguishable from one nobody looked at.

• oversight_status — held or not, by whom and since when, how many stops are on record, and every blocker reason by name rather than a boolean. "Blocked" cannot tell a human stop from a budget nobody instrumented, and those two call for opposite responses.

• set_autonomy_limit / record_iteration — an advisory ceiling on autonomous iterations, reported in three states. Declaring a budget and never calling record_iteration reports as unreported — a blocker, printed without a fraction, because "0/20 iterations" is the most reassuring line on the page and it is exactly what a loop nobody instrumented would produce. You decide what an iteration is; Credence will not invent a unit for your runtime.

• declare_intervention_point / list_intervention_points — the catalogue of points at which a human may be brought in. Policy in data: Credence ships zero points and never decides when one applies. required is mechanism, not policy — an uncited required point is reported as its own blocker reason and still stops nothing. Unlike a relation predicate, a pointId is hard validated with no discovery mode: an unrecognised predicate is still a true statement about the world, but a hold citing a point that does not exist is a false statement about governance that reads as legitimate in every report.

next_steps leads with oversight blockers, above findings, obligations and expectations — an agent that reads one line must not read past a human stop to get to a missing tax id.

scan_contradictions takes the judge structurally (ContradictionScanner) rather than importing @credence/judge — otherwise every MCP server would inherit a vendor SDK, including ones that never adjudicate anything. For the same reason the MCP server itself is only on @credence/kit/mcp: a caller wiring buildTools into their own loop never loads it.

Attribution matters here. The kit's default actor is agent:mcp — a machine identity, which the judge excludes from its calibration dataset. Anything this surface dismisses is the model's own opinion, and treating it as a human label would let the model grade itself. Pass a person's identity as actor (or as by on the call) when a human is really behind the tool call.

The actor is also what lands in the audit chain for every claim, relation, decision and obligation transition this surface writes, so "who asserted this?" is answerable from the ledger rather than from a trace that may have been rotated away. Pass assertedBy on an individual record_claim or record_relation when a specific identity is behind that one assertion; it never enters the object's identity, so the same fact asserted by two actors stays one claim with two attribution entries.

The kit adds agent ergonomics: auto-recompute after writes, a default case, and flat evidence input ({ sourceKind, sourceUri, page, bbox }). Point any MCP-capable client at createMcpServer(kit) and every tool appears — the fastest path to adoption.