> ## Documentation Index
> Fetch the complete documentation index at: https://kensa.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> What's new in Kensa.

<Note>Release notes for Kensa. Full notes are available on [GitHub Releases](https://github.com/kensa-sh/kensa/releases).</Note>

## 0.22.0

The `kensa-setup` skill can now discover which agent frameworks a repository imports before manual tracing begins.

* `detect_frameworks.py --root .` scans a repository read-only for imports of 47 known agent frameworks and returns each match as an unconfirmed candidate alongside that framework's documentation URL.
* Detector output is import evidence only: it never ranks candidates, selects a production target, or establishes relevance, confidence, or readiness, and an empty or incomplete result never blocks the existing source-tracing workflow.
* Version and documentation lookups run only after a candidate is confirmed against actual application control flow, resolved from installed package metadata or the repository's dependency and lock data.

[View the 0.22.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.22.0).

## 0.21.0

Traces can now dual-export to any OTLP HTTP collector, and setup, inspect, and doctor output carry versioned contracts for other tooling to consume.

* `instrument()` dual-exports spans to a standard OTLP HTTP endpoint via `otlp_endpoint` or `KENSA_OTLP_ENDPOINT`, while keeping local JSONL capture and isolating export failures from the traced process; standard `OTEL_EXPORTER_OTLP_*` variables never enable export on their own.
* `kensa.behavior_candidate.v1` publishes an inspect idea as a strict public model with a deterministic `semantic_fingerprint` over its normalized failure and outcome semantics.
* `kensa init --non-interactive --json --project-root ...` emits a versioned `kensa.init_manifest.v1` changed-file manifest, and `kensa doctor --json` emits versioned `kensa.doctor_diagnostics.v1` codes.

[View the 0.21.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.21.0).

## 0.20.0

Judge defaults, agent setup, and Langfuse imports now track the production systems they run against.

* OpenAI judges now default to `gpt-5.6-luna`, while Anthropic judges default to `claude-sonnet-5`; older model IDs remain available as explicit overrides.
* The `kensa-setup` skill now connects `kensa_run` to approved production agent code, preserves one conversation across turns, and asks before changing the harness or allowing model spend and live side effects.
* Legacy Langfuse imports now respect the v1 observation limit of 100, while v2 imports retain their 1,000-item page size.

[View the 0.20.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.20.0).

## 0.19.1

Tool-call traces now expose structured evidence for precise assertions over arguments, results, ordering, and execution status.

* `ToolCallEvidence` provides immutable normalized records with sequence, name, arguments, result, capture-presence flags, status, span ID, and duration.
* `result.trace.tools.matching(...)` and `.called(...)` filter calls by recursive argument and result subsets plus status, while existing name assertions remain available.
* `record_tool_call()` accepts strict JSON arguments and results, supports capturing a result inside the tool context, and persists normalized `tool_calls` alongside the existing `tools` list.

[View the 0.19.1 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.19.1).

## 0.19.0

Run-result artifacts now have a strict, versioned public contract for reliable downstream tooling.

* **Breaking:** every initial, incremental, interrupted, and completed result artifact now uses `schema_version: "kensa.result.v1"`; unversioned, unsupported, legacy, or internally inconsistent artifacts are rejected.
* `kensa.results` exposes immutable typed models plus `load_run_result()` for loading complete, interrupted, and initial snapshots with path-specific validation errors.
* Writes normalize and deterministically order trials, derive aggregates and summaries from the same v1 data, validate before atomic replacement, and preserve full evidence during watchdog recovery.

[View the 0.19.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.19.0).

## 0.18.0

Trials now carry structured failure provenance so agent behavior is separated from eval-system failures.

* **Breaking:** trial artifacts replace the legacy `error` and `error_kind` fields with one validated `failure` object containing a category, kind, message, and JSON evidence.
* Reliability, latency, and cost metrics include only passes, assertion failures, and errors attributed to the agent; excluded errors still fail the eval gate and are reported by category.
* `KensaEvalError`, `TrialFailure`, and `FailureCategory` support explicit attribution, while `JudgeResult.require()` distinguishes negative verdicts from judge execution and contract errors.

[View the 0.18.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.18.0).

## 0.17.0

Eval adapters can now attach structured evidence from target-owned agents without Kensa importing, invoking, or connecting to them.

* `AgentRunEvidence` records execution attestation, ordered trajectory events, provider trace references, observed state, and independent trajectory and state completeness.
* `attach_agent_run()` snapshots evidence during the active case operation and preserves it across result, trace, failure, and timeout artifacts.
* External tool and LLM events feed the existing trace, turn, and cost accessors; target state remains separate under `result.trace.agent_runs`.

[View the 0.17.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.17.0).

## 0.16.1

Eval reports now quantify reliability and make incomplete cost data explicit.

* Terminal, Markdown, and JSON reports include `pass^k` reliability with cohort counts, latency percentiles, mean LLM turns, and cost per pass.
* Trace cost is `None` when any billable span is unpriced, while `known_cost_usd` preserves the sum of priced spans.
* Timeouts distinguish setup, agent call, and teardown failures while preserving the active instrumented GenAI operation.

[View the 0.16.1 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.16.1).

## 0.16.0

Conversational evals now model multi-turn agent interactions and return structured run evidence.

* **Breaking:** the `kensa_run` fixture now returns a case-aware agent with `respond(messages)`, and `case.run(kensa_run)` returns a `CaseResult` instead of the raw agent output.
* Cases can start from message history, and optional simulators can drive bounded conversations with explicit termination metadata.
* Successful results expose messages, output, termination, and a read-only trace; pass `trace=result.trace` to `judge(...)` when a criterion needs trajectory evidence.

[View the 0.16.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.16.0).

## 0.15.0

Project configuration is now explicit in `pyproject.toml`, failed eval runs can be diagnosed against repository evidence, and console output is easier to scan.

* **Breaking:** Kensa no longer reads `.kensa/settings.json`; trace source and redaction model settings now live under `[tool.kensa]` in the nearest `pyproject.toml`, and readiness is computed live.
* `kensa init` installs a read-only `kensa-diagnose` skill that analyzes failed or errored result JSON against the current repository's source and tests.
* `kensa eval` keeps periodic heartbeat details behind `--verbose` and prints a compact aggregate and per-trial summary.

[View the 0.15.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.15.0).

## 0.14.0

Kensa trials now run in parallel across four local pytest workers by default.

* Use `kensa eval --workers N` to tune concurrency or `--workers 1` for sequential execution.
* Timeout handling preserves completed results and the latest evidence from a timed-out trial.
* **Breaking:** worker processes do not share process globals or session-scoped fixtures, and provider concurrency increases.

[View the 0.14.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.14.0).

## 0.13.0

Eval runs now have hard per-trial timeouts and bounded judge calls.

* Trials stop after 300 seconds by default. Use `--trial-timeout` or `@pytest.mark.kensa(timeout_s=...)` to change the limit.
* Timeout artifacts preserve completed results, set `complete` to `false`, and include a structured interruption.
* Judge calls time out after 30 seconds by default.

[View the 0.13.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.13.0).

## 0.12.0

Imported trace evidence is now minimized to a versioned, allowlisted TraceView before mandatory redaction.

* Only eval-required fields are retained, and trace and span identifiers use import-local aliases.
* **Breaking:** persisted TraceView artifacts use the v2 evidence contract.

[View the 0.12.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.12.0).

## 0.11.1

Redaction setup is now automatic and fails clearly when incomplete.

* Selecting a trace source installs missing redaction dependencies as a development dependency.
* Setup output reports one protection status and preserves actionable diagnostics on failure.

[View the 0.11.1 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.11.1).

## 0.11.0

Trace redaction is now mandatory and fails closed across import, inspection, trace access, and eval generation.

* Redaction happens in memory before connected Langfuse payloads reach disk.
* Safe import manifests are bound to the exact artifact with SHA-256. Missing or mismatched manifests block access.
* `kensa doctor` reports missing redaction readiness and unsafe or modified artifacts.
* **Breaking:** `kensa import` no longer accepts `--redact`. Redaction cannot be disabled or bypassed.

[View the 0.11.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.11.0).

## 0.10.3

* `kensa connect langfuse` now validates the endpoint and credentials without reading trace data.
* Langfuse imports use the CLI's default scope unless you explicitly request a different one.

[View the 0.10.3 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.10.3).

## 0.10.2

Connected Langfuse imports now use the official Langfuse SDK while preserving legacy trace and observations v2 import formats.

[View the 0.10.2 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.10.2).

## 0.10.1

* Langfuse observation input and output are parsed locally instead of sent as unsupported request parameters.
* `kensa init` can connect Langfuse before judge credentials are configured and now surfaces clearer setup errors.

[View the 0.10.1 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.10.1).

## 0.10.0

Langfuse imports now support events-only deployments by reconstructing traces from observations v2 when the legacy traces API is unavailable.

[View the 0.10.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.10.0).

## 0.9.4

* `kensa connect langfuse` reports endpoint, authentication, and import-readiness checks separately.
* Omitted endpoints now resolve from `LANGFUSE_BASE_URL` before using the cloud default.

[View the 0.9.4 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.9.4).

## 0.9.3

* The interactive agent picker starts on Claude Code and offers one agent at a time. `kensa init --agent all` remains available for non-interactive setup.
* README assets and the license link now render correctly on PyPI.

[View the 0.9.3 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.9.3).

## 0.9.2

`kensa init --agent` now supports explicit agent choices and `all`, persists the selection in `.kensa/settings.json`, and fails clearly when automatic detection finds no supported agent.

[View the 0.9.2 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.9.2).

## 0.9.1

Relaxed lower dependency bounds improve compatibility with existing Python environments while retaining Python 3.11+ support.

[View the 0.9.1 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.9.1).

## 0.9.0

Added Kensa's pytest-native eval workflow for turning agent traces into plain pytest tests with deterministic assertions, repeated trials, optional LLM judges, and CI reporting.

[View the 0.9.0 release notes](https://github.com/kensa-sh/kensa/releases/tag/v0.9.0).

## Legacy releases

> \[!WARNING]
> Versions 0.1.0 through 0.8.0 are part of Kensa's legacy implementation and have been yanked from PyPI. Kensa 0.9.0 is a complete rewrite with a new API. These release notes are preserved for historical reference.

[View the legacy changelog](https://github.com/satyaborg/kensa/blob/main/docs/changelog.mdx).