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 standalonehekma-hostbinary. See Run Hekma as a service.- Control API v0: with
--listenand--bearer-secret,hekma serveexposes a local HTTP and JSON API for the fleet, lifecycle, config and live events. It is marked unstable and has nosendroute. 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,metadataoroff. - Hosted agents get a minimal environment: under
hekma serve, an agent sees only the variables its adapter declares, plusPATHandHOME(and a few Windows system variables). - Static Linux build: an
x86_64-unknown-linux-muslarchive withhekma,hkmandhekma-host, and a container recipe that runs itFROM scratch. logs --followshows the backlog: it starts with the last 200 raw lines a detached agent wrote while no command was running. SetHEKMA_LOGS_BACKLOG_LINESto 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-enginemoves to 0.8.0. It addsEngine::open_with_optionswithEngineOptions(the fixed metering port, the minimal child environment and the log capture mode), the export methodsexport_eventsandack_export, andlog_capture_mode.RegistryErrorgainsOutboxOpenRefusedandServeOptionsOpenTimeOnly, andSpawnSpecgains aninherit_envfield. Code that matchesRegistryErrorexhaustively, or buildsSpawnSpecby 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.
| Platform | Archive | Checksum |
|---|---|---|
| macOS, Apple Silicon | hekma-v0.11.0-aarch64-apple-darwin.tar.gz | sha256 |
| macOS, Intel | hekma-v0.11.0-x86_64-apple-darwin.tar.gz | sha256 |
| Linux x86_64 (glibc) | hekma-v0.11.0-x86_64-unknown-linux-gnu.tar.gz | sha256 |
| Windows x86_64 | hekma-v0.11.0-x86_64-pc-windows-msvc.zip | sha256 |
| All platforms | hekma-v0.11.0-checksums.txt |
Highlights
- ACP agents.
hekma agent register NAME --kind acpruns any Agent Client Protocol agent: setacp.commandandacp.args. Hekma does the handshake at start, turns eachsendinto one prompt turn, sendssession/cancelon stop, denies permission requests, and resumes the session at the next start when the agent supports it. Verified against OpenCode and Hermes Agent'shermes-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, inlist,showandusage, and in cost, with a newcost.rate.cachedprice. 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
showand 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
listandshow, and asupervisionJSON field:detached,session, or—when no process is recorded. - Pauses across commands: an agent you paused with
hekma agent pauseis resumed when the command exits, so it is never left frozen with nobody watching. An agent paused by a budget breach stays paused. logs --followstreams what a detached agent writes after the command starts, from its rawagent.log, with a note that those timestamps are when Hekma read the lines.
Deprecation
- The
hermeskind is deprecated in favour of--kind acpwithacp.command hermes-acp. It keeps working unchanged and will not be removed before a major release. Metering and memory delivery work the same underacp. 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/cancelit 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-engine0.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 fiveStoreErrorvariants), fields toFleetEntry,SpawnRecordandSpawnSpec, and the methodread_raw_output_since. See Upgrade from 0.4.- The conformance kit gains
run_conformance_withandTckConfig: 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
- Hekma is open source under the Apache License 2.0, replacing the noncommercial licence of earlier releases. A
NOTICEfile is added. Contributions are still made under the Contributor License Agreement.
No behaviour changed. Upgrade with hekma self-update.
v0.8.1#
Released 18 September 2026. Release page
Fixes
hekma self-updateand the update check now look for releases atgithub.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
hekmaand its short aliashkm;ktis gone. The crate ishekma(thektesiocrate stays at 0.7.0), the Homebrew formula isktesio/tap/hekma, and the library crates continue ashekma-engine0.4.0,hekma-adapter-api0.2.0 andhekma-adapters-hermes0.2.0. kt self-updatecannot reach this release. Re-run the installer, or usecargo install hekma --forceorbrew upgrade ktesio/tap/hekma. Upgrade from kt has the steps for each install method.
Highlights
hekma agent start --detachkeeps 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_eventsto catch up on events after a crash or a lag, and aDiagnosticSinkto 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 newHEKMA_*names alongside. JSON output, exit codes, theKTESIO_USAGEline 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.
| Version | Date | Summary |
|---|---|---|
| v0.7.0 | 10 Sep 2026 | The 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.0 | Never released. Planned as the switch from skills manager to agent runner, which shipped in v0.7.0. | |
| v0.5.0 | 1 Jul 2026 | New documentation site. |
| v0.4.0 | 3 Jun 2026 | Hosted installers, the update notice and self-update. |
| v0.3.1 | 2 Jun 2026 | Skills manager: fallback skill discovery. |
| v0.3.0 | 1 Jun 2026 | Skills manager: progress output for init. |
| v0.2.0 | 2 Jun 2026 | Skills manager: search, shorthand installs and polished output. |
| v0.1.1 | 31 May 2026 | First release, as a skills package manager. |
Read next#
- Status and roadmap: what ships today and what is coming.
- Install: how to update.
- Upgrade from kt: moving from Ktesio to Hekma.