kairos-skills

The KAIROS epistemic control loop for SOC agents. Your assistant (or your own models) writes competing hypotheses; Kairos's deterministic gates decide whether anything may act; risky actions need a person; every step is hash-chained into an audit log.

An agent earns the right to act within a bounded scope by demonstrating, through recorded evidence, that it is calibrated, structurally consistent and acting on trusted provenance. (Earning the Right to Act, preprint v2, 2026)

Install

npx kairos-skills install --platform claude          # or codex, gemini, cursor, vscode, antigravity, all
npx kairos-skills install --platform claude --project

Three skills go into your tool's skills folder and the kairos MCP server is registered in its config (the file is backed up first). After an upgrade, installed skills refresh automatically; files you edited are kept as .bak. Opt out with KAIROS_NO_AUTO_REFRESH=1.

Claude Code plugin: /plugin marketplace add drupadsachania/kairos-skills, then /plugin install kairos@kairos-skills.

Requires Node.js 24 or later.

Two ways to run

On your AI (plugin / MCP). Your assistant is the model, so no API key is needed. It calls kairos_open_case, writes at least three competing hypotheses (one benign), submits them with kairos_submit_hypotheses, and follows the decision. kairos_approve is for people only.

Standalone agent. Kairos samples your own models and runs the whole loop:

npx kairos-skills run --alerts scenarios.jsonl --model ollama:llama3.1:8b --model nim:<model> --samples 3 --out results.jsonl --audit audit.jsonl

Model specs: ollama:<model>, nim:<model> (NVIDIA_API_KEY), openrouter:<model> (OPENROUTER_API_KEY), groq:<model> (GROQ_API_KEY), gemini:<model> (GEMINI_API_KEY), openai:<model>@<base_url> (KAIROS_LLM_API_KEY). Use at least two different models: one model cannot corroborate itself. Each result line is scored against its ground truth (unsafe_execution, correct_autonomous, escalated, deferred, …).

What decides

| Check | Outcome on failure | |-------|--------------------| | Epistemic failure screen (degenerate, contradictory, overconfident, low-information, false agreement) | FAIL_SAFE / DEFER / ESCALATE | | Gate 1: attack path feasible in the topology and identity graph | re-orient (at most twice), then DEFER | | Narrative anchoring: ≥ 3 competing hypotheses, ≥ 1 benign | DEFER | | Residual aleatoric uncertainty after retrieval | DEFER with a telemetry request | | Gate 2: calibrated confidence ≥ tier threshold (needs a certificate) | DEFER | | Gate 3: trajectory uncertainty ≤ tier limit | ESCALATE | | Provenance veto: justification rests on untrusted data and the action changes state, executes or sends data out | ESCALATE, whatever the confidence | | Tier 2 (isolate, disable, block) | ESCALATE for two approvers | | Tier 3 (mass reset, deletion, external notification) | Human-only; never executed by Kairos |

Only Tier 0–1 actions can be autonomous, and only through a single-use Ed25519 capability token checked by the tool gateway. Without a calibration certificate the agent is uncertified, so Tier 1 escalates too: that is the intended shadow-mode posture.

Commands

install (alias init), uninstall, update, list, mcp, run. Run kairos --help.

MCP tools

kairos_open_case, kairos_submit_hypotheses, kairos_get_decision, kairos_approve (destructive; people only), kairos_audit, kairos_lab, kairos_scenarios (ground truth withheld). Environment: KAIROS_LAB (lab JSON), KAIROS_AUDIT_FILE (persist the audit chain), KAIROS_CERTIFICATE with KAIROS_CALIBRATOR (certified autonomy).

Library

const { KairosAgent, MockSOC, makeClient, engine } = require('kairos-skills')
const agent = new KairosAgent(MockSOC.load(), { clients: [makeClient('ollama:llama3.1:8b'), makeClient('ollama:qwen2.5:7b')] })
const result = await agent.handle(alert)          // decision, gates, policy trace, uncertainty, audit head
agent.approve(result.decision_id, ['alice', 'bob']) // a person's dual-key approval for an escalated Tier 2 action

engine exposes the gates, policy engine, provenance labeller, capability tokens, audit log and calibration functions (isotonic map, ECE with bootstrap interval, Brier decomposition, risk-controlled thresholds, certification, drift monitor).

What this package runs, sends and fetches

• kairos mcp and the plugin: a local stdio server. It makes no network requests and calls no model. In lab mode approved actions change only the in-memory mock SOC; in advisory mode nothing runs. The audit chain stays in memory unless you set KAIROS_AUDIT_FILE.
• kairos run: sends prompts to the model endpoints you name, with the API keys from your environment. Alert evidence goes into those prompts; values flagged as injection-like are withheld.
• kairos install: writes skill files into your tool's skills folder, adds a kairos entry to its MCP config (backed up first) and keeps a ledger under ~/.kairos (override with KAIROS_HOME).
• No telemetry, no analytics, no hosted inference.

Honest limit: tools you connect straight to your assistant bypass Kairos. Kairos governs what goes through it.

Fidelity

This is a JavaScript port of the Python reference implementation (kairos-core). Parity tests replay fixtures generated from the Python code: the heuristic engines, both policy tables (1,217 cases), the calibration maths and the ensemble decomposition must match. Differences: capability tokens are Ed25519 here (the reference uses HMAC), and regex word boundaries are ASCII-only in JavaScript.

Licence: Apache-2.0 OR MIT.