docs · reference

Adapter manifest#

An adapter.toml file tells Hekma how to run any program as an agent: the command that starts it, what it can do on each OS, where its token counts come from, and how config keys reach it. This page is the field reference; Bring your own agent walks through writing one.

You register a manifest with hekma agent register NAME --manifest DIR, where DIR holds adapter.toml (or point at the file itself). Hekma parses and checks the whole file before writing anything. Unknown fields are rejected, so a typo fails registration instead of being ignored, and the error names the section at fault.

Complete example#

contract_version = "1.0.0"

[adapter]
kind = "worker"
name = "Worker"

[lifecycle.start]
exec = "/usr/local/bin/worker"
args = ["--serve"]
env = { LOG_LEVEL = "info" }

[capabilities.pause]
linux = "guaranteed"
macos = "guaranteed"
windows = "best-effort"

[capabilities.interaction]
linux = "guaranteed"
macos = "guaranteed"
windows = "guaranteed"

[metering]
source = "self-reported"

[interaction]
channel = "stdio"

[config.model]
env = "MODEL"

[config."memory.dir"]
env = "WORKER_MEMORY_DIR"
SectionRequiredPurpose
contract_versionyesThe adapter contract version the file is written for.
[adapter]yesThe adapter's kind and display name.
[lifecycle]yes, with startHow to launch the agent.
[capabilities]yesWhat the agent supports on each OS.
[metering]yesWhere token counts come from.
[interaction]noWhich input channel the agent uses.
[config]noHow config keys reach the agent.

Hekma reports the first required section that is missing or invalid.

contract_version#

The version of the adapter contract the manifest targets. Hekma 0.11.0 speaks 1.0.0, so write:

contract_version = "1.0.0"

The value must be a full X.Y.Z version: 1.0, 1 and v1.0.0 are rejected. A suffix such as 1.0.0-rc.1 is accepted. Hekma loads a manifest only when its major version matches its own; the minor and patch parts are not compared. A mismatch fails registration with exit code 1 and names both versions:

✗ The adapter manifest at '/Users/you/agents/worker/adapter.toml' cannot load: incompatible adapter contract: manifest declares 2.1.0, engine speaks 1.0.0 — compatible iff the major versions match (contract v1 policy, docs/adapter-contract.md#versioning). Ask the adapter author to retarget the manifest's contract_version to this engine's contract major — see docs/adapter-contract.md.

Versions 0.x are rejected too. See Versioning for the full rule.

[adapter]#

FieldTypeRequiredMeaning
kindstringyesThe adapter's identifier, shown in the Kind column. Lowercase letters, digits, - and _, starting with a letter or digit.
namestringnoA display name.

[lifecycle]#

[lifecycle.start] is required. It is the command Hekma runs to start the agent.

FieldTypeRequiredMeaning
execstringyesThe program: a name found on PATH when the agent starts, or an absolute path.
argslist of stringsnoIts arguments. Default none.
envtable of stringsnoExtra environment variables. Default none.

The agent runs with its Agent Home as its working directory and inherits the environment of the hekma command that started it, plus env and any mapped config. A config mapping that sets the same variable as env wins, and Hekma prints a note saying so at start.

Hekma copies the start command when you register. Editing adapter.toml later does not change an agent that is already registered; remove it and register it again.

You may also write [lifecycle.stop], [lifecycle.pause] and [lifecycle.resume] with the same three fields. Hekma 0.11.0 checks them but never runs them. Stopping is always done by signal: SIGTERM to the agent's process group on Unix, then SIGKILL after the stop timeout; on Windows Hekma waits out the timeout and then ends the process's job. Pausing uses SIGSTOP and SIGCONT where the capabilities say guaranteed.

An agent should therefore exit cleanly on SIGTERM. An agent that exits on its own while running, even with code 0, counts as a crash and is handled by the restart policy. An agent that exits within the first 300 milliseconds fails the start instead.

[capabilities]#

The capability declaration: one table per capability, rating it per OS.

[capabilities.pause]
linux = "guaranteed"
macos = "guaranteed"
windows = "best-effort"
CapabilityWhat it governs
pausehekma agent pause and resume, and the pause breach action.
interactionWhether the agent gets a stdin pipe and accepts hekma agent send.

Each table takes the keys linux, macos and windows, each set to one of:

LevelMeaning
guaranteedHekma relies on it. A pause really suspends the process.
best-effortHekma does it, and labels the result as cooperative. On Windows, pause is never stronger than this.
unsupportedThe command fails at once with exit code 5, quoting the declaration.

An OS left out of a table counts as unsupported. The manifest must declare at least one capability that is not unsupported on some OS, or registration fails.

Declare interaction supported only if the agent reads stdin. An agent with interaction support gets a stdin pipe when started without --detach; one without it gets a closed stdin, so it never blocks reading input that will not arrive.

[metering]#

Where the agent's token counts come from, its metering source.

[metering]
source = "self-reported"
sourceHow usage is counted
self-reportedThe agent prints a usage line on stdout for each model call (below).
engine-observedHekma runs a proxy on 127.0.0.1 and reads token counts from the model provider's responses. Map metering.base_url in [config] so the agent sends its requests to the proxy, and set metering.upstream_base_url on the agent. Such an agent cannot be started with --detach.

A self-reporting agent prints one line per usage event to stdout, starting with KTESIO_USAGE and a space, then a JSON object with sequence, input_tokens, output_tokens and optionally cached_tokens:

KTESIO_USAGE {"sequence": 0, "input_tokens": 1200, "output_tokens": 300, "cached_tokens": 400}

Hekma adds the agent name, run, source and time itself, and counts each sequence once per run. A line that breaks the format is skipped without stopping the agent. Self-reported usage is the full reference for the fields and rules; Meter token usage covers both sources step by step.

[interaction]#

Optional. Names the channel the agent takes input on.

FieldTypeMeaning
channel"stdio" or "http"stdio: the agent reads stdin. http: the agent takes input over its own HTTP API.

The field is descriptive in 0.11.0: Hekma behaves the same for both values. Whether the agent gets a stdin pipe depends on the interaction capability, and hekma agent send always writes to stdin. An HTTP-only agent can declare http so the manifest describes it accurately, but send will not reach it. Any other value is rejected.

[config]: config key mapping#

Optional. Maps config keys to the agent's own settings, so the same key works for every agent. Each [config.KEY] table names exactly one target:

# As an environment variable.
[config.model]
env = "MODEL"

# As a command-line flag: appended as two arguments, --model <value>.
[config.model]
flag = "--model"

# As a value in a TOML file in the Agent Home, at a dotted key.
[config.model]
file = { path = "config/agent.toml", key = "llm.model" }

(Pick one; a key can have only one target.)

TargetRules
env = "NAME"The variable is set in the agent's environment.
flag = "--name"The flag and the value are appended to [lifecycle.start] args.
file = { path, key }Hekma writes a TOML file at path, relative to the Agent Home, with the value at the dotted key. path may not be absolute or contain ... Several keys mapped to the same file are written to one document.

Keys a mapping can name:

  • Any key on Config keys, such as model. A key nobody sets is simply not delivered.
  • The reserved key memory.dir: the path of the agent's memory/ folder when a filesystem memory backing is attached. Quote it: [config."memory.dir"]. Without this mapping the folder is still kept, but the agent is not told where it is, and Hekma says so on stderr at start.
  • The reserved key metering.base_url: the proxy address for engine-observed metering, usually mapped to the variable the agent reads its API base URL from, such as OPENAI_BASE_URL.

You do not map agent.* keys: Hekma always passes agent.NAME as the environment variable NAME.

Things to know when you write mappings:

  • Secrets. A secret:NAME value is delivered in clear text to the target. Prefer env or file for secrets. A flag puts the secret on the command line, where other local users can read it; Hekma warns when that happens.
  • JSON-configured agents. The file target writes TOML only. For an agent that reads JSON config, map a key to the environment variable it reads whole config from (for example OpenCode's OPENCODE_CONFIG_CONTENT).
  • Placeholders. If the agent fills {env:VAR} placeholders in its own config and treats a missing variable as empty, make sure every such variable is mapped and set, or the agent will run with an empty value without warning.
  • Self-updating agents. Map the agent's setting that turns off self-update, so the version you tested is the one that runs.
  • Isolation. If several agents of the same program share a machine, map the settings that move the program's data and config folders into each Agent Home (for example XDG_DATA_HOME and XDG_CONFIG_HOME for XDG-based programs). The adapter contract lists these duties.