Skip to content

Events and records ​

Read a run in four places: the hmz exec --json stream while an epic runs, the messages of an attached epic, the record on disk, and the notices the daemon raises when a run ends or asks for input.

The event stream ​

hmz exec --json writes NDJSON to standard output, flushing one JSON object per event as it happens. See The command line for usage and CLI for flags.

The kind, agent and first words of each event of one run, printed by jqThe kind, agent and first words of each event of one run, printed by jq

Keys ​

Every object carries these ten keys.

KeyTypeValue
atnumberUnix time the event was recorded.
agentstringThe agent's own name, never the role it fills.
clistringThe harness.
modelstringThe model the agent was configured with.
sessionstringThe harness's own id for the session. "" before it has one, and for an event not about one session.
kindstringOne of the kinds below.
textstringThe event's words.
whosestringFor subagent and subagent-ends, the harness's id for the subagent. Otherwise "".
tokensobjectOn result, tokens by model, where the harness reports them. Otherwise {}.
spentobjectOn result, tokens by kind, where the harness reports them. Otherwise {}.

One result event with all ten keys, printed by jqOne result event with all ten keys, printed by jq

Kinds ​

kindWhentext
beginsA turn opens.The prompt.
textThe agent says something.What it said.
reasoningThe agent thinks aloud.The thinking.
toolThe agent uses a tool.The tool's name, a space, then its arguments.
subagentThe agent starts an agent of its own.The subagent's name, a space, then what it was asked to do.
subagent-endsThat subagent ends.The same.
asksThe agent or the flow asks its person a question.The question.
tookWords put into a running turn are now in front of the agent.Those words.
noticeHumanize acts on the turn: it waits out a rate limit, carries on under another account, or cuts the turn off.What it is doing.
resultThe turn ends with an answer. Exactly one closes a turn.The answer.
failedThe turn ends without an answer.What went wrong.
endsThe turn closes.""

The keys of spent are input, output, cache_read, cache_write and reasoning. A harness omits any kind it does not count.

Rules ​

  • Nothing else reaches standard output. What the flow prints goes to standard error.
  • The stream has no object for the end of the epic. The exit status says how it ended.
  • Nobody is at the prompt: a question is answered at once, and its asks event is still written.
  • Only hmz exec has --json. hmz chat does not.

Messages of an attached epic ​

epic.attach opens an epic subscription. Each message arrives as an epic.event notification, or as one item of for message in link in Python. See Daemon and wire for the methods and SDK for the link. Every message is a JSON object with a type key. Readers must ignore unknown types and keys.

Order ​

Besides workspace, slot and scratch, epic.attach takes replay (default true), since ({epoch, seq} or null) and figures (default false). The host sends these messages in order with nothing between them:

  1. welcome.
  2. Every kept history record, oldest first. With replay set to false, none. With since, only records after that seq if epoch still matches the host and all records are still kept; otherwise, all of them.
  3. One snapshot of each kind, in order: clients, claims, away, run, sessions, calls, waiting, pending, usage, board, envs.
  4. live.

After live, each history record and changed snapshot arrives as it happens. gone is the last message of a subscription.

typeKeys
welcomeclient, name, kind, workspace, slot, pid (the host's process), protocol, epoch (a text naming this life of the host).
liveseq, that of the last history record, and elided, the number of records dropped from the front.
figuresOnly with figures set to true: after live, then at most once a second while it changes. run, elapsed, lasting, ended, agents, sessions, handovers, latest, spending, reckoning, tally.
gonewhy: let go, the host was closed, too far behind; attach again or the host went away.
term, term_exitThe output of a terminal (term, data) and its end (term, status), sent only to the frontends that view it. They carry no seq and are not replayed.

History records ​

Every history record has seq, an integer that increases by one with each record. Every record except printed has run, the number of its epic. A host keeps up to 32 MiB of records for the current or last epic. It drops the oldest records first and counts them in elided on live.

typeKeys
startedkind (flow or chat), flow, ref, task, by, client, roles, names, outworlders, agents, envs, params, budget, profile_flow, profile_environment, backup, resume, began, at.
openedrole, key (<agent>/<n>), agent, cli, model, counts, forks, person, kept, env, harness, mono, wall.
eventkey, mono, and the keys of the event stream, except that the harness's id for the session is ident, and session is key, or "" for an event not about one session.
askedquestion (q<n>), role, text, options, mode (ask or listen), key, schema (a JSON Schema, or null for text), context, face, session.
answeredquestion, role, by, client, text.
withdrawnquestion, why: away or over.
shownrole, session, context: blocks shown to a person with no question.
saidtext, key, by, client.
refusedagent, text, because.
unheldagent, texts.
droppedgiven, queued, because: stopped or ended.
shellkey, command, out, err, status: a ! command a chat ran.
printedtext: one line printed in the host process.
noticetext.
stoppingby, client.
endedhow (done, stopped, budget, refused, failed or crashed), why, mono, result (what the flow returned for done, otherwise null).
env_usedenv, by (the frontend's name), what, and path where one was named.

In env_used, what is wrote, made, renamed, removed, opened a terminal, staged, unstaged, discarded, committed or rewound. The host writes one record for each change a frontend makes from the Files, Terminal and Changes panels.

Snapshots ​

The host keeps the latest snapshot of each kind and sends a new one whenever it changes.

typeKeys
clientsclients: one {client, name, kind} per attached frontend.
claimsclaims: {role: client}.
awayall (a boolean) and of ({role: boolean}).
runstate (idle at first), the keys of started for the epic going or the last, stopping, epic, chat, slot, and for a chat turn.
sessionsrun, open (the keys still open), working (the keys with a turn open).
callscalls: one {ref, name, depth, since, id, parent} per flow call going.
waitingqueued and given: lines said and not yet taken.
pendingpending: the questions not yet answered, each with the keys of its asked, run and owner.
usagerun, usage, budget. Sent at most once a second.
boarditems: one {key, value, about, whose, by, at} each, or null for an epic with no board.
envsenvs: the environments of the epic.

Records on disk ​

Each epic and chat keeps an append-only JSON Lines record on disk. See Files on disk for the rest of the directory.

FileRecord of
epic.jsonlOne epic.
epic.<flow>_<id>.jsonlOne call of a flow by a flow inside the epic. <id> is six hex digits. A flow called twice has two.
chat.jsonlOne chat.

Every line is a JSON object with event (the event name), at (the UTC time it was written, as in 2026-11-21T05:13:22.007Z), and that event's keys. The file is UTF-8 with non-ASCII characters escaped. Readers must ignore unknown keys and events.

The four events of a short epic's record, printed by jqThe four events of a short epic's record, printed by jq

Events of an epic record ​

eventWritten whenKeys
beganThe epic begins. Always first.See below.
openedA session's harness first states the session's id.See below.
calledThe flow calls a flow.flow (the called flow's reference), task, epic (the file name of the call record).
returnedThat call ends, however it ends.flow and epic, equal to those of its called.
usageJust before each ended.cost (US dollars, left out where it is not a finite number), output_tokens, seconds: what the budget counted since the record began or was last reopened.
endedThe flow stops.how: done, failed or stopped.
backedEach time the epic is backed up.to (the target), ok, error ("" when ok), why: session, interval, end or manual.
importedThe epic is imported or downloaded from a backup.from (the archive's file name, or the backup it came from), head (the workspace commit the archive states, or "").

how is stopped when the flow was stopped from outside or ran out of budget, failed when it raised any other exception, and done otherwise.

Keys of began ​

KeyValue
kindflow.
flowThe flow as it was named.
taskThe task.
workspaceThe absolute path of the workspace.
resumableWhether the flow can be picked up.
refThe flow's canonical reference. Only where known.
picked_upThe name of the epic this one resumes. Only for an epic that resumes another.
agentsOne object per role: agent (the role), name (the agent filling it), backend (the harness), model, effort, provider (the account, "" for none).
envsThe env specs given, one per env.
usedWhere each env was placed. Only where it differs from envs.
paramsThe params given to the flow.
budgetduration (seconds), cost (US dollars), output_tokens and graceful. A limit that is not set is null; cost may also read "Infinity". graceful is a boolean, or an object with one boolean per limit.
profile_flowtrue. Only where the flow's Python is profiled.
profile_environmenttrue. Only where the epic's processes are profiled.
backupThe names of the epic's backup targets. Only where there are any.
spelling2, the spelling envs and used follow.

Keys of opened ​

KeyValue
agentThe agent's name, never its role.
backendThe harness.
providerThe account, or local for none.
sessionThe id the harness gave the session. The same value as session in the event stream.
name<agent>-<backend>@<provider>-<session>.
whereThe directory that holds the session's files: sessions/<cli> inside the epic directory, or an absolute path.
parentThe session this one was forked from. Only for a fork.
harnesslocal, env or <backend>:<name>: where the harness ran. Only where the env is on another machine.

A session whose harness never stated an id has no opened.

Events of a call record ​

A call record holds only began, opened, called, returned and ended. Its began has flow, task, workspace, resumable and under (the file name of the calling flow's record). Nested calls write to the called flow's record. Match each returned to its called by epic to reconstruct the call tree.

Events of a chat record ​

eventWritten whenKeys
beganThe chat begins. Always first, and written once.task (the first message), workspace, agents (one object, whose agent is assistant), and where they apply backup, prefer, permission, workdir, env, title, adopted, forked.
setThe chat's preference, agent, permission, env or title changes, or it is archived or put back.Any of prefer, agents, permission (here also workspace-write), env, title, archived (a boolean).
openedAs in an epic record.As in an epic record.
reopenedThe chat is carried on.task, the message that carried it on.
usageJust before each ended.As in an epic record.
endedThe chat folds away.how: stopped or failed.
backedAs in an epic record.As in an epic record.
importedThe chat is downloaded from a backup.As in an epic record.
Key of beganValue
prefernative or flow. Only where the chat overrides the preference.
permissionread-only or danger-full-access. Absent means workspace-write.
workdirThe absolute path of the worktree the assistant works in.
envThe env the chat began in, written as -e writes one after the role. In place of workdir.
titleThe title. Only for a fork and for a chat made from a harness session.
adopted<harness>:<id>, the harness session the chat was made from.
forkedThe name of the chat this one is a fork of.

Read prefer, agents, permission, env, title and archived from the last event that sets them, including began. Without title, the title is the first line of task.

Reading a record ​

  • A record has ended when an ended follows its last reopened. An epic record never has reopened.
  • A record with no such ended is running or unfinished. It is running while a shared lock on .held in its directory cannot be taken.
  • Total spend for an epic or chat is the sum of its usage events.
  • backed and imported may follow the last ended.
  • Ignore backup on began and every backed before the last imported.
  • Side questions are never recorded.

Notices ​

The daemon raises a notice when an epic or chat changes state. Read them over the daemon's methods; see Daemon and wire. Notifications describes how each interface displays them.

Kinds ​

kindRaised when
doneAn epic ended done, or a chat finished a turn.
failedAn epic or a chat failed or crashed, an epic ran out of budget, or an epic was refused after an interface asked to start it.
stoppedAn epic was stopped or forced.
askedA flow asked a person a question.
listeningA flow waits for the next thing a person says.

A chat never raises stopped or listening. An epic that runs out of budget raises failed here, even though its record says stopped.

Keys ​

KeyValue
idAn integer, greater than every id this machine raised before, across restarts of the daemon.
kindOne of the kinds above.
workspaceThe workspace.
slotThe host slot that holds the run.
epicThe epic's name. "" for a chat.
chatThe chat's name. "" for an epic.
flowThe flow. chat for a chat.
taskThe task.
roleThe role a question concerns. Otherwise "".
textOne line: the question, or the last line of why the run ended. May be "".
atUnix seconds when it was raised.

Methods ​

MethodTakesAnswers
notices.listafter, an id; default 0.notices, those kept after it, oldest first, and last, the newest id or 0.
notices.subscribeafter, an id; absent for from now.sub and last. Each notice then arrives as a notices.event notification with sub and notice.
notices.unsubscribesub.{}

Rules ​

  • The daemon keeps the latest 200 notices. Pass the last id you saw as after to resume from there.
  • A subscription that falls too far behind ends with a notices.event whose gone says so in place of notice. Subscribe again.
  • State from before the daemon started is not noticed, and each question is noticed once.
  • The daemon does not filter by kind. Each interface chooses which kinds to show.

Open source on github.com/humanfia · RSS: blog · news