Agent Governance SDK for the CodeRifts API. Validate API changes before tool invocations in AI agent infrastructure (LangChain, AutoGen, Copilot, Claude, Grok, etc.).
npm install @coderifts/[email protected]import { CodeRifts } from '@coderifts/sdk';
const client = new CodeRifts({ apiKey: 'cr_live_...' });
const result = await client.preflightCheck({
tool_name: 'get_refund_status',
old_spec: oldYaml,
new_spec: newYaml,
});
if (!result.safe) {
console.error('Blocked:', result.decision, result.reflex_triggers);
process.exit(1);
}Check whether it is safe to proceed with a tool invocation.
const result = await client.preflightCheck({
tool_name: 'get_refund_status',
old_spec: '...',
new_spec: '...',
});
// result.decision: 'BLOCK' | 'REQUIRE_APPROVAL' | 'WARN' | 'ALLOW'
// result.omega_api: number
// result.safe: boolean
// result.reflex_triggers: Array<{ rule: string; decision: string }>
// result.affected_tools: Array<{ tool_name: string; status: string }>Full analysis of two OpenAPI specs.
const result = await client.diff({
before: '...',
after: '...',
});
// result.omega_decision: string
// result.risk_score: number
// result.breaking_changes: BreakingChange[]
// result.should_block: booleanHuman-readable explanation of why a decision was made.
const explanation = await client.explainDecision({
omega_api: 43.95,
decision: 'BLOCK',
reflex_triggers: [...],
});
// explanation.summary: string
// explanation.components: Array<{ name: string; value: number; description: string }>Actionable steps to resolve a BLOCK decision.
const steps = await client.howToUnblock({
decision: 'BLOCK',
breaking_changes: [...],
detected_patterns: [...],
});
// steps.actions: Array<{ step: number; description: string; code_example?: string }>Score an MCP manifest for agent safety.
const score = await client.scoreMcp({
manifest: { tools: [...] },
});
// score.overall_score: number (0-100)
// score.band: 'STRONG' | 'GOOD' | 'NEEDS_WORK' | 'POOR' | 'CRITICAL'Query compliance ledger entries.
const ledger = await client.getLedger({
repo: 'owner/repo',
decision: 'BLOCK',
limit: 10,
});
// ledger.entries: LedgerEntry[]
// ledger.total: numberTest a YAML policy against two OpenAPI specs.
const result = await client.simulatePolicy({
policy_yaml: '...',
old_spec: '...',
new_spec: '...',
});
// result.effective_action: string
// result.matched_rules: MatchedRule[]These return the decision-result.v1.1 envelope with a top-level execution_action
(CONTINUE | CONTINUE_WITH_MONITORING | REQUEST_APPROVAL | STOP) and a signed chain receipt.
Preflight a multi-artifact change set (POST /api/v1/preflight). Required top-level
preflight_mode: 'analyze' | 'authorize' (Decision Spec v2; server returns 400 if omitted).
Prefer the wrappers so the two meanings cannot be mixed:
// Risk-only (informational — not permission)
const risk = await client.analyzeChangeSet({
artifacts: [{ id: 'payments', type: 'openapi', before: oldSpec, after: newSpec }],
});
// Operation-bound authorize (requires context.operation; may mint a receipt)
const auth = await client.authorizeChangeSet({
artifacts: [{ id: 'payments', type: 'openapi', before: oldSpec, after: newSpec }],
context: { operation: 'merge', environment: 'production' },
idempotency_key: 'pr-1234',
});
// Or set the mode explicitly:
const res = await client.preflightChangeSet({
preflight_mode: 'authorize',
artifacts: [{ id: 'payments', type: 'openapi', before: oldSpec, after: newSpec }],
context: { operation: 'merge' },
});Verify a chain receipt's signature and integrity. No API key required (public endpoint).
POST /api/v1/verify-receipt.
const v = await client.verifyReceipt(receiptToken);
// v.valid (boolean), v.status ('VERIFIED_CURRENT' | 'VERIFIED_EXPIRED' | ...), v.payload?Look up a stored decision by decision_id or fingerprint; returns the stored envelope + meta.
POST /api/v1/decisions/lookup.
const d = await client.getDecisionDetails({ decision_id: 'dec_...' });
// d.decision_result (DecisionResultEnvelope), d.metaPure helper (no network) to read a governance decision from any CodeRifts response, fail-closed.
Envelope-first, then top-level execution_action, then a decision→action map, else STOP. Never throws.
import { readDecision } from '@coderifts/sdk';
const { executionAction, decision, envelope, receipt } = readDecision(res);
if (executionAction === 'STOP' || executionAction === 'REQUEST_APPROVAL') {
// block or gate the tool call
}All methods throw a typed CodeRiftsError on non-2xx responses:
import { CodeRifts, CodeRiftsError } from '@coderifts/sdk';
try {
const result = await client.preflightCheck({ ... });
} catch (err) {
if (err instanceof CodeRiftsError) {
console.error(err.code, err.message);
}
}Full API documentation: https://coderifts.com/docs
MIT