docs · project

Release notes#

The latest release is Hekma 0.11.0, from 17 October 2026. It adds ACP agents, cached-token metering and detached agents that stay in one run across commands, and deprecates the hermes kind. Each release below lists its highlights, anything that breaks, and what to do when you upgrade. The full commit lists are on GitHub Releases.

Unreleased#

Unreleased: after 0.11.0. Everything in this section is merged on Hekma's main branch and ships in the next release.

Highlights

  • hekma serve, a long-running host that adopts every agent in a state directory and supervises it until it gets SIGTERM, then stops each agent through the graceful stop sequence. A lock file refuses a second host on the same directory. Also available as a standalone hekma-host binary. See Run Hekma as a service.
  • Control API v0: with --listen and --bearer-secret, hekma serve exposes a local HTTP and JSON API for the fleet, lifecycle, config and live events. It is marked unstable and has no send route. See Control API.
  • Outbox export: one durable, acknowledged journal of every event across all agents, read through the Control API. See Export.
  • Log capture modes: hekma serve --log-capture full, metadata or off.
  • Hosted agents get a minimal environment: under hekma serve, an agent sees only the variables its adapter declares, plus PATH and HOME (and a few Windows system variables).
  • Static Linux build: an x86_64-unknown-linux-musl archive with hekma, hkm and hekma-host, and a container recipe that runs it FROM scratch.
  • logs --follow shows the backlog: it starts with the last 200 raw lines a detached agent wrote while no command was running. Set HEKMA_LOGS_BACKLOG_LINES to change the number.

Fixes

  • If Hekma changes an agent's state but cannot write the matching line to instance.log, it now puts the state back, so the database and the log never disagree. The error says so.

For embedders

  • hekma-engine moves to 0.8.0. It adds Engine::open_with_options with EngineOptions (the fixed metering port, the minimal child environment and the log capture mode), the export methods export_events and ack_export, and log_capture_mode.
  • RegistryError gains OutboxOpenRefused and ServeOptionsOpenTimeOnly, and SpawnSpec gains an inherit_env field. Code that matches RegistryError exhaustively, or builds SpawnSpec by hand, needs a change.

v0.11.0#

Released 17 October 2026. Release page · All changes since v0.9.0

There was no v0.10.0 release. The version was set on the main branch during development and skipped at release time, so 0.11.0 follows 0.9.0.

PlatformArchiveChecksum
macOS, Apple Siliconhekma-v0.11.0-aarch64-apple-darwin.tar.gzsha256
macOS, Intelhekma-v0.11.0-x86_64-apple-darwin.tar.gzsha256
Linux x86_64 (glibc)hekma-v0.11.0-x86_64-unknown-linux-gnu.tar.gzsha256
Windows x86_64hekma-v0.11.0-x86_64-pc-windows-msvc.zipsha256
All platformshekma-v0.11.0-checksums.txt

Highlights

  • ACP agents. hekma agent register NAME --kind acp runs any Agent Client Protocol agent: set acp.command and acp.args. Hekma does the handshake at start, turns each send into one prompt turn, sends session/cancel on stop, denies permission requests, and resumes the session at the next start when the agent supports it. Verified against OpenCode and Hermes Agent's hermes-acp. In 0.11.0, prompt turns need a program that embeds the engine; see Supervision and detached runs.
  • Cached tokens are tracked end to end: in usage lines (optional cached_tokens), in the ledger, in list, show and usage, and in cost, with a new cost.rate.cached price. Without it, cached tokens are priced at the input rate.
  • Anthropic usage is read by the metering proxy, alongside OpenAI-style usage. See Meter token usage.
  • ACP context usage: an ACP agent's context-window figure is shown in show and JSON (acp_context_usage), never billed. An ACP agent with no billed usage shows — and a note naming what Hekma tried.
  • Detached agents stay in one run across commands. Per-run totals keep adding up, and a breach already fired in the run does not fire again when the next command adopts the agent.
  • A Supervision column in list and show, and a supervision JSON field: detached, session, or — when no process is recorded.
  • Pauses across commands: an agent you paused with hekma agent pause is resumed when the command exits, so it is never left frozen with nobody watching. An agent paused by a budget breach stays paused.
  • logs --follow streams what a detached agent writes after the command starts, from its raw agent.log, with a note that those timestamps are when Hekma read the lines.

Deprecation

  • The hermes kind is deprecated in favour of --kind acp with acp.command hermes-acp. It keeps working unchanged and will not be removed before a major release. Metering and memory delivery work the same under acp. See Supported agents.

Fixes

  • Attaching or detaching memory in one terminal while starting the agent in another can no longer leave the two out of step. The losing command fails with a retryable error and changes nothing.
  • On Windows, a detached agent no longer keeps the starting command's output pipes open.
  • An ACP stop records the session/cancel it sent in the agent's log.

Upgrade notes

  • The state database is upgraded to schema 9 the first time 0.11.0 opens it. Older Hekma versions refuse to open it afterwards, so upgrade every copy that shares a state directory.
  • Agents left running by an older version are adopted as usual and get a run id at that point; Hekma prints a one-time note.
  • Nothing else changes for the CLI: JSON documents gain only optional fields and keep their schema_versions, and exit codes are unchanged.

For embedders

  • hekma-engine 0.7.0 replaces 0.4.0 on crates.io (0.5 and 0.6 were never published). It adds variants to exhaustive enums (EngineError::AcpTurnInFlight, EngineError::MemoryBackingChangedUnderStart, TransitionCause::DetachedResumed, and five StoreError variants), fields to FleetEntry, SpawnRecord and SpawnSpec, and the method read_raw_output_since. See Upgrade from 0.4.
  • The conformance kit gains run_conformance_with and TckConfig: a per-section timeout, a state directory you own, and a chosen subset of sections. Its errors now name the stage that failed.

v0.9.0#

Released 18 September 2026. Release page

Highlights

No behaviour changed. Upgrade with hekma self-update.

v0.8.1#

Released 18 September 2026. Release page

Fixes

  • hekma self-update and the update check now look for releases at github.com/Ktesio/hekma, the repository's new home after the rename. A v0.8.0 binary still finds later releases through GitHub's redirect.

v0.8.0#

Released 18 September 2026. Release page

Breaking changes

  • Ktesio is now Hekma. The commands are hekma and its short alias hkm; kt is gone. The crate is hekma (the ktesio crate stays at 0.7.0), the Homebrew formula is ktesio/tap/hekma, and the library crates continue as hekma-engine 0.4.0, hekma-adapter-api 0.2.0 and hekma-adapters-hermes 0.2.0.
  • kt self-update cannot reach this release. Re-run the installer, or use cargo install hekma --force or brew upgrade ktesio/tap/hekma. Upgrade from kt has the steps for each install method.

Highlights

  • hekma agent start --detach keeps an agent running after the command exits; the next command adopts it. Engine-observed agents refuse --detach.
  • The metering proxy works with real providers: HTTPS upstreams through a bundled TLS stack, and streaming responses, by asking the provider for a final usage frame.
  • For embedders: resync_events to catch up on events after a crash or a lag, and a DiagnosticSink to route the engine's diagnostic lines into your own writer.
  • Sturdier supervision: a dedicated error when resuming an agent whose pause is unsupported, budgets checked at once when a command adopts an agent, a process that cannot be checked repeatedly is treated as crashed, and adopted agents on Windows can now be stopped and confirmed dead.

Upgrade notes

  • Your data stays where it is: the same state directory is used and nothing is moved. KTESIO_* environment variables keep working, with new HEKMA_* names alongside. JSON output, exit codes, the KTESIO_USAGE line and the adapter contract are unchanged.
  • The state database moves to schema 6 (it records whether an agent is detached).

Older releases#

These were released as Ktesio, with the kt command. Their notes are on GitHub.

VersionDateSummary
v0.7.010 Sep 2026The engine becomes an embeddable library on crates.io, with an event stream; the adapter contract is frozen at 1.0.0 and the conformance kit ships; the native Hermes adapter.
v0.6.0Never released. Planned as the switch from skills manager to agent runner, which shipped in v0.7.0.
v0.5.01 Jul 2026New documentation site.
v0.4.03 Jun 2026Hosted installers, the update notice and self-update.
v0.3.12 Jun 2026Skills manager: fallback skill discovery.
v0.3.01 Jun 2026Skills manager: progress output for init.
v0.2.02 Jun 2026Skills manager: search, shorthand installs and polished output.
v0.1.131 May 2026First release, as a skills package manager.