Kineti OS v0.3.6

Spend cap, transactional undo, and proof receipts for AI coding agents.
A lightweight open-source (MIT) safety harness that runs under Claude Code, Cursor, OpenCode, Codex, Antigravity, Cline, and fx.sh.

$ kineti spend status
total $0 of $50; entries 0; tripped=false

$ kineti spend log --stage build --model sonnet --tokens-in 400000 --tokens-out 200000
logged $4.2 (stage build); run total $4.2

$ kineti spend log --stage build --model opus --tokens-in 100000 --tokens-out 60000
kineti: SPEND BREAKER TRIPPED: stage build total $10.2 reached ceiling $9.5 (exit code 3)

$ kineti spend check
kineti: TRIPPED: stage build total $10.2 reached ceiling $9.5 (exit code 3)

$ kineti spend reset
kineti: reset requires --i-am-human (breakers are human-only) (exit code 2)

$ kineti spend reset --i-am-human
breaker reset by human (exit code 0)

Key Pillars

1. The 360º Human Model & Epistemic Engine

Personalized agents must understand the full human context without hallucinating, overriding user statements, or quietly mutating goals when third-party systems push back:

• Multi-Scope Context Isolation: Strict context isolation across Global, Domain (Health, Work, Finance, Schedule, Taste), and Relationship (person-to-person) scopes. Scoped facts never leak into generic or un-scoped queries.
• Epistemic Certainty Tiers: Enforces DirectlyKnown (explicit user ground truth) > ObservedPattern (behavioral patterns) > Inferred (hypotheses). Machine inferences are strictly blocked from overwriting explicit user statements.
• Rule-Exception Hierarchies: Resolves complex user lifestyles unambiguously: BaselineRule (e.g. Vegetarian) $\to$ PermittedException (e.g. Eats eggs) $\to$ Preference (e.g. Prefers low dairy) $\to$ SafetyCeiling (e.g. Peanut allergy).
• Verbatim Root Goal & Anti-Drift Engine: Anchors autonomous task chains to the exact, unmodified words uttered by the user and their explicit definition of "Done". Every step is inspected against the original ask, eliminating the multi-step "telephone game". Intermediate steps and tools are treated as expendable scaffolding.
• Friction Triage Ladder ("Clean No over Dirty Yes"): Triages real-world obstacles through 3 levels:
  1. Noise: Transient blips auto-retry with exponential backoff.
  2. Broken Surface: Broken websites or portals silently reroute to alternatives.
  3. Real Constraint: Hard third-party refusals escalate immediately with a clean impossibility report. Sunk costs are written off ($0 sunk-cost fallacy), and quiet compromises (such as accepting budget overruns) are strictly blocked.
• Commitment-Time Verification: Re-checks perishable facts (fares, seat availability, stock levels, auth tokens) at the exact millisecond of external or financial commit, never trusting cached plan snapshots.
• Asymmetric Gap-Filling: Cheap, reversible gaps are filled automatically and disclosed in audit evidence; expensive or irreversible gaps halt execution to ask the user.
• Reputation Gating & Ingress Defense: Outbound communication is treated as a non-regenerating resource (knowing an identity does not equal permission to contact). Incoming external messages and webhooks arrive as untrusted data, never instructions.

2. Native Rust Nervous System Substrate (core-native/)

• Double-Buffered Atomic Snapshots: Two-slot RwLock snapshot design with thread-safe read paths and deferred epoch reclamation of retired instances. Latency figures are withheld until reproducible benchmark scripts land in the repo.
• Universal 20-Entity Provenance Kernel: Content-addressed RFC 8785 JSON canonicalization with BLAKE3 and SHA-256 digests (hand-rolled under a zero-external-dependency constraint; see docs/PLAN.md for rationale and test vectors).
• Monotonic Hybrid Logical Clock (HLC): Physical and logical causality tracking under clock skew.
• 3-Way Graph Commit Gate: Rejects causal inversions, topological DAG cycles, and single-byte state tampering.
• Sensory Reflex Triage: Fast sensory classification dispatching zero-token emoji reactions for low-information conversational stimuli.
• Protocolized Connectors: Standard KinetiConnectorProtocol trait with consequence level gating (Trivial, Operational, HighConsequence) and single-use SHA-256 payload authorization tokens.
• Spend Circuit Breaker: Deterministic trip at 95% of limit ($47.50 of $50.00 ceiling) with OS exit code 3 halt.

3. TypeScript Governance Control Plane (bin/, src/)

• 13-Stage Software Factory: Strict stage-gated lifecycle ensuring specifications, implementations, and test proofs precede release.
• Transactional SAGA Undo Stack: Guarantees LIFO file reversibility before every mutation.
• Cryptographic Evidence Binding: Cryptographic SHA-256 receipts bound to exact workspace code fingerprints via kineti-evidence.ts.
• Apple HIG Visual Companion: Local web dashboard built with Apple Human Interface Guidelines (<12 KB payload, zero runtime JS frameworks).
• Universal Model Context Protocol (MCP): 12 native governance tools exposed to Cursor, Claude Code, Antigravity, and Codex.

4. Verified Test Counts & Evaluation Roadmap

• What is verified today: 168 TypeScript governance tests and 251 native Rust tests (unit plus integration suites), 0 failures (419 total passed tests), bound to workspace code fingerprints through delimited SHA-256 evidence receipts (bin/kineti-evidence.ts).
• Frontier figures in src/harness/benchmark.ts are design targets, not measured results: the ALE 76.4% pass rate, SWE-bench 4.2 min MTTR, and $0.31 per-outcome numbers are goal constants for the evaluation program. They have not been produced by empirical runs.
• Kineti Hostile 100 (in development): a public suite of 100 hostile tool calls against the gate with published method and published failures. This is the benchmark the project intends to be judged by.
• Directional Normalized Trust-Weighted Impact (DNTI): three-factor loss-averse outcome verification ($\Phi \times \sigma_\tau(SE) \times \Psi(\mathcal{T})$) designed to resist Goodhart-style metric gaming.
• Cost Per Verified Outcome ($/Outcome): design goal of pricing work in verified business outcomes instead of raw token consumption.

Quickstart

1. Install via npm

Prerequisite: The CLI is distributed on npm and runs on Node.js (>= 18), but requires Bun (>= 1.1) installed on the system for governance execution (curl -fsSL https://bun.sh/install | bash).

# Install globally (latest)
npm install -g kineti

# Or pin to the current stable release
npm install -g kineti@0.3.6

# Or run directly with npx
npx kineti --help

2. Connect to Your AI Editor or Agent Host

Run Kineti directly as an MCP governance server inside your AI editor to enforce spend caps ($50 ceiling), transactional SAGA undo, and cryptographic test verification.

Automatic Setup for All Hosts

Run Kineti's auto-configurator in your project directory:

kineti init

This automatically detects your installed hosts (Claude, Cursor, OpenCode, Codex, Antigravity, fx.sh, Gemini, Cline) and links project rules and MCP configurations.

Manual Configuration by Editor

Claude Code (CLI):

claude mcp add kineti npx -y kineti mcp

Cursor & Windsurf: Add to your project's .cursor/mcp.json or Cursor Settings $\to$ Features $\to$ MCP:

{
  "mcpServers": {
    "kineti": {
      "command": "npx",
      "args": ["-y", "kineti", "mcp"]
    }
  }
}

OpenCode:

opencode mcp add kineti npx -y kineti mcp

Or add to ~/.config/opencode/opencode.jsonc.

Codex (CLI): Add to ${CODEX_HOME:-$HOME/.codex}/config.toml:

[mcp.servers.kineti]
command = "npx"
args = ["-y", "kineti", "mcp"]

Google Antigravity & Gemini: Run the automated host configurator:

kineti init --host antigravity

Fx.sh: Install skill rules directly to your fx environment:

kineti init --host fx

Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "kineti": {
      "command": "npx",
      "args": ["-y", "kineti", "mcp"]
    }
  }
}

Cline / Roo Code: Add a new stdio MCP server in settings:

• Server Name: kineti
• Command: npx
• Args: ["-y", "kineti", "mcp"]

3. Core Governance Commands

# Start the visual companion dashboard (Apple HIG)
kineti companion
# Open http://127.0.0.1:8788

# Start the MCP governance server directly
kineti mcp

# Check spend circuit breaker status ($50 default ceiling)
kineti spend check

# Run tests and save cryptographic proof receipt
kineti test -- echo hello

# Verify cryptographic test evidence freshness
kineti test check --label test

# Run stage-agnostic CI verification
kineti ci

4. Native Rust Engine & Crates.io

All 8 native crates are published on crates.io:

# Add native core nervous system to your Rust project
cargo add kineti-core

# Or install the native CLI binary directly
cargo install kineti-cli@0.3.6

# Run all 251 native Rust unit and integration tests locally
cargo test --manifest-path core-native/Cargo.toml

# Run the 5 native verification demo flows
cargo run --package kineti-cli -- test-all

Repository Structure