Skip to content

Daemon reference ​

The daemon: one process per machine and user, the one JSON-RPC endpoint every client reaches -- on its socket, and on whatever it listens on beside it -- and which speaks for each client to the host of the workspace it names: one process per workspace and slot, holding that workspace's runs. Every client is a client of a daemon over a session of the wire protocol: frames and JSON-RPC 2.0 whose methods protocol/openrpc.json lists. A frontend is an hmz interface (kind tui), the web interface hmz web serves (kindweb, named browser), or a program linked through the SDK (kindsdk). Package: hmz.daemon. Notation: Conventions.

text
 hmz (alice@tui) ──┐ daemon.sock (trusted)          ┌─ host process, ~/src/api ─────────────┐
 hmz web (browser) ┼────────────── daemon ─────┬──▶│ Host: the run, claims, away, queued  │
 program (ci@sdk) ─┘                (one per   │   │ lines, questions, history, snapshots │
 another machine ── tcp/ws/relay ── machine)   │   └──────────────────────────────────────┘
   (mutual TLS)     webrtc (DTLS)              └──▶┌─ host process, ~/src/web ─────────────┐
                                                   │ …                                     │
 JSON-RPC sessions end at the daemon, which        └───────────────────────────────────────┘
 speaks to each host down a link of its own.

Terms ​

TermDefinition
hosthmz.runtime.Host: a workspace's runs as every attached frontend shares them. Held in a host process (or, for an epic run on fakes, in the calling program's private daemon).
daemonThe detached process, one per machine and user, serving JSON-RPC on daemon.sock and its listeners, and speaking to the host process of each workspace for its clients.
host processThe detached process, one per workspace and slot, started by the daemon, standing in that workspace and holding its Host. Reached only by the daemon, down a socket pair.
sessionOne client's connection to the daemon: session.hello, then calls, answers and notifications.
frontendOne attachment to a host: one epic subscription (epic.attach), held by a Link. Has a client id (c1, c2, …) and a name.
runOne run of one flow on the host, numbered from 1 per host.
requestA call to an epic, epic.<do>; a Link takes it as a JSON object with do.
messageA JSON object the host sends, with type, carried as the notification epic.event.

When a daemon is used ​

CallerHost
hmz, whatever the terminalA host process, found or started (see CLI › Where the runs are held). After 3 failed attempts, 0.5 s apart, stderr says hmz: the daemon cannot be reached: <why> and it exits 1.
hmz webA host process, found or started with attach, tried 3 times 0.5 s apart; where none can be had it says so and exits 1.
hmz exec, Hmz().run()A host process on a new exec slot (exec:<hex>) of the workspace, started by this machine's daemon.
Hmz().run() with a driver object, fakes.run_fake()A host in the calling program's own private daemon.
Daemons().host(), hmz.daemon.host()A host process, found or started.

Files ​

Directory: <tmp>/humanize-<uid>/, where <tmp> is Python's tempfile.gettempdir() ($TMPDIR, $TEMP or $TMP, else /tmp) and <uid> the user's id: hmz.machine(), shared with other caches. Made 0700 where missing; one that is not a directory, not this user's, or that its group or others can write is refused with PermissionError: <dir> is not a directory only this user can write; remove it. Never under $HUMANIZE_HOME: a daemon is one machine's process, and a home directory several machines mount would list each machine's daemon on every other.

FileWrittenModeContentRemoved
daemon.sockwhen the daemon binds0600Unix stream socket, backlog 64. A stale one is unlinked only after the lock is held.when the daemon closes
ai-<hex>.sockbefore the host of the Ai-chan conversation of slot ai:<hex> starts0600Unix stream socket: that conversation's scoped link.when that host goes, and when the daemon closes
daemon.jsonafter binding, atomically (.daemon.json.<random>.new, fsync → rename)0600See below.when the daemon closes
daemon.lockat start0600Empty. Held with flock(LOCK_EX | LOCK_NB) for the daemon's lifetime; the kernel releases it when the process ends.never
daemon.logat start; append0600What belongs to no run: the daemon's file descriptors 1 and 2, a host process's before it has held a run, start failures, socket-path chdir failures. Never rotated.never

What a host process writes while it holds a run goes into that run's epic instead, as host.log (0600, append, never rotated) beside its epic.jsonl: the host's file descriptors 1 and 2 (output of CLIs the run spawns), and entries written by logged(). The run is the one going, else the one stopping, else the last.

json
{
  "pid": 41237,
  "started": "2026-09-30T08:15:42Z",
  "kind": "daemon",
  "protocol": "3.0.0"
}
KeyTypeValue
pidintThe daemon process.
startedstringUTC, %Y-%m-%dT%H:%M:%SZ.
kindstring"daemon".
protocolstring3.0.0, hmz.rpc.PROTOCOL. A daemon.json without it, or of another major version, is another Humanize's daemon, which nothing here reaches.

A workspace is known by str(Path(workspace or cwd).resolve()): two checkouts of one repository are two workspaces, and two spellings of one directory are one.

The temporary directory is the machine's to clean: a reboot empties it, and so may the system (systemd-tmpfiles, macOS's periodic cleanup) for files left untouched. A running daemon marks its directory and its four files as used every hour; daemon.log left behind by one that has gone is cleaned with the rest.

Socket path length. Where <dir>/daemon.sock is longer than 100 bytes -- a long $TMPDIR -- binding and connecting chdir into the directory and use the relative name.

Discovery ​

FunctionReturnsRule
running(workspace=None)Daemon | NoneThe host of that workspace, where the daemon's daemon.json parses as an object with an int pid of a live process (kill(pid, 0); EPERM counts as alive), its socket accepts a connection within 1 s, its hosts.list names the workspace, and that host's pid is alive. Where the daemon's protocol is not of major version 3: a Daemon for the daemon itself, with its protocol ("" for none). Otherwise None.
daemons()list[Daemon]Every host the daemon lists whose pid is alive, sorted by started (oldest first); the daemon itself where its protocol is of another major version; [] with no daemon.
host(workspace=None, *, seconds=10.0, slot="")DaemonStarts the daemon where none is, then calls hosts.open, which starts the host where none is; waits up to seconds for each. Tried twice, 0.1 s apart: a daemon that went as its host came up is started again.
start(seconds=10.0)NoneStarts the daemon where none is, as the first client that needs one does.
older(daemon)strthe runs in <workspace> are held by an older Humanize (pid <pid>); stop it with that version, or on this machine for a daemon.

host() raises OSError:

ConditionOSError text
another Humanize's daemon (protocol of another major version), or one refusing session.hello with 426[Errno <EADDRINUSE>] + older(daemon) (98 on Linux, 48 on macOS)
the daemon or the new host reported a failurethe reported text, e.g. the run could not be held: <why>
no daemon is listening after the waitthis machine's daemon did not come up
hosts.open refusedits message, e.g. This chat has folded away.
no host came up after both triesthe runs in <workspace> did not come up

Two callers racing to start the daemon: the loser's lock fails (EAGAIN: [Errno 11] Resource temporarily unavailable on Linux, [Errno 35] on macOS), and host() uses the winner. Two calls needing a host of one slot of a workspace at once take on one, which both use.

Process ​

The first client that needs the daemon starts it, and the daemon starts each host process, each a fresh interpreter -- never a fork of a process that may hold threads -- running python -Pm hmz.daemon.detached <pipe> daemon or … <pipe> host <workspace> <slot> <link>. It inherits only the standard three descriptors, the pipe it says it is up on and, for a host, its end of a socket pair, which is its link:

StepProcessAction
1callerCreates a pipe; flushes stdout/stderr; starts the process in a new session (setsid: no controlling terminal), stdin from /dev/null, fds 1, 2 to daemon.log, its environment the caller's. Waits on the pipe (polled every 0.1 s, up to seconds), then reaps it.
2startedForks, while it has no other thread, and exits 0, so that the fork leads no session and can never take a controlling terminal.
3daemon or hostIgnores SIGHUP; unwinds on SIGTERM, whatever the caller made of it.
4daemonTakes the lock, binds the socket, writes daemon.json, writes listening\n to the pipe, takes sessions and opens its listeners.
4hostChanges to the workspace; ignores SIGINT; Hmz().reports(); makes the Host; fds 1, 2 to a pipe a thread appends to the run's host.log (daemon.log before any run); replaces sys.stdout and sys.stderr with Printed; on SIGTERM closes the host from a new thread. Writes listening\n to the pipe and serves its link.
—either, on failureWrites the run could not be held: <why>\n to the pipe, closes it, puts fds 1, 2 back on daemon.log and logs a traceback there, exits 1.

Environment. A host runs in the daemon's environment, and the daemon in that of the client that started it -- except under hmz daemon serve with no controlling terminal, as the service hmz daemon install writes runs it: there it first takes the environment of $SHELL -ilc ($SHELL unset: the account's shell), read between two marks of env -0 and given 5 s, else its own; drops PWD, OLDPWD, SHLVL and _; and appends to PATH whichever of ~/.local/bin, $UV_TOOL_BIN_DIR, /opt/homebrew/bin, /usr/local/bin, /usr/bin and /bin it lacks. A changed profile reaches the hosts once the daemon is started again.

The caller reads the pipe: listening… returns; any other text raises OSError with it, and EOF with none it ended before it came up; daemon.log says why. A timeout returns silently, and host() then raises only if nothing is listed.

Printed. In the host, each complete line written to sys.stdout/sys.stderr (a flow's print, a Python traceback) becomes a printed message to every frontend. Output written directly to descriptors 1 and 2 by child processes goes to the run's host.log.

Shutdown. Host.close() withdraws questions, drops queued lines, stops every run, tells every frontend gone (the host was closed), and waits up to 15 s from the first close for runs to release what they made (containers included). The host process then exits; the daemon ends every subscription still attached to it with gone (the host went away).

Sessions ​

Every session is the same JSON-RPC 2.0 over frames (a big-endian u32 length, then one JSON object, at most 32 MiB), whichever carrier it came over:

CarrierSecurityPaired
daemon.socknone: the operating system admitted the userfrom the start, as the device local
a tcp, ws, relay or easytier listenermutual TLS 1.3, ALPN hmz, each side's self-signed device certificate (hmz.trust)where the client's SPKI fingerprint is a paired device
a webrtc listenerthe DTLS of a data channel whose fingerprints the daemon signs (hmz.rtc)where dtls:<fingerprint> is a paired device
RuleValue
First callsession.hello {protocol, client: {name, kind}}; anything else first is refused -32600. Answered daemon_id, version, protocol, capabilities (webrtc where a webrtc: listener is open and aiortc is installed), machine, wsl, newer, paired, device.
VersionsA client of major version 3 and a minor version no greater than the daemon's is admitted; any other is refused 426 with data.protocol.
UnpairedMay call session.hello, pair.claim and rpc.discover alone; anything else is refused 401, This device is not paired: claim a pairing code first.
OrderEach call on a thread of its own; those naming one sub in the order sent, epic.aside apart.
WritesA call carrying idem is carried out once per device and key; its answer is kept 600 s, the latest 1 024 per device.
OutgoingOne queue per session, written by a thread of its own; past 64 MiB its notifications are dropped and every subscription is ended: gone (too far behind; attach again), or notices.event with gone.
Calls the daemon makesNone.

The methods served here are session.*, rpc.discover, pair.*, devices.*, hosts.*, epic.*, btw.* and aichan.*; every other family (settings, epics written down, flows, …) is a module of hmz.daemon.api naming its own in METHODS, found by pkgutil as the daemon starts. A method protocol/openrpc.json lists that nothing serves is refused -32601.

MethodAnswer
pair.create {routes?, seconds?}code (hmz-pair:…) and expires; routes default to the listeners'. 409 There is no route to pair over: give one, or listen.
pair.claim {token, name}daemon_id, device; pairs the session's device. 403 for a code not held, 409 on a paired session.
devices.listdevices: [{name, fingerprint, added, seen, live}].
devices.revoke {name}dropped; removes the device, answers, then closes every session of it. 400 for local, 404 for no such device.

The daemon closes once it has held no host and no session for 2 s, or 60 s after it started where nothing ever came -- unless it listens beyond its socket or hmz daemon serve started it -- and on SIGTERM: it closes every session and host, unbinds the socket, and removes daemon.json. A host whose link to the daemon closes closes its runs as hosts.stop does: nobody could reach them.

Listeners ​

The setting listen and each hmz daemon serve --listen name listener specs, opened beside the socket; the setting's are opened and closed as it changes.

SpecListens
tcp://<address>:<port>A TCP socket; 0 takes any port.
ws://<address>:<port>WebSocket binary messages; any other request is answered 404.
relay:<ws-url>Registered at that relay under the daemon id, accepting native joins.
webrtc:<ws-url>Registered at that relay, answering WebRTC joins with the STUN and TURN servers of ice_servers.
easytier:<name>The EasyTier entry of that name joined, its virtual address 10.144.144.1 reaching port 41817 of the loopback.

A listener's route -- 0.0.0.0 named by this machine's host name, port 0 by the port taken -- is what pair.create puts in a code. One that cannot be opened is written to daemon.log and tried again after 1 s, doubling to 60 s.

The daemon speaks to each host process with JSON-RPC down a socket pair, of calls of its own no client sees: attach {tag, name, kind, replay, since}, ask {client, said}, detach, status, detach_all, and the notification close; the host sends each frontend's messages up as told {tag, message}.

Lifecycle ​

Slots ​

A workspace's runs are held by more than one host: its own, slot "", which runs its flows one at a time and refuses a second (a flow is already running), and one per chat, slot chat:<hex> (12 hex digits from hmz.daemon.where.chat()), and one per hmz exec, slot exec:<hex>, and one per Ai-chan conversation, slot ai:<hex>, beside it. epic.attach, hosts.open and chat.start with chat: (chat.start only) or exec: alone make a new slot of that kind; one whose host has gone is refused 409 (This chat has folded away., This epic has ended.). A chat started on a slot of its own never waits on a flow, nor a flow on it, and a second chat is a second slot. Every call that reaches a host -- attach, running, host, epic.attach, hosts.* -- takes slot, and without one means the workspace's own. where.slot(said) checks one, raising ValueError (<slot> is not a slot) for anything but "", chat:<hex> and exec:<hex>.

A chat's host folds its chat away once the chat has waited for its next line with no frontend attached for 60 s (hmz.runtime.doing.hosting.FOLD): every role is made away, the question waiting is answered with nothing, and the chat ends as an empty next message ends it, keeping its conversation; the host is then idle, and goes. A folded host refuses chat.say (this chat has folded away; carry it on from its epic): the chat is carried on by chat.start on a new slot with resume its epic, which goes on in that same epic.

Each host process checks every 0.5 s. The host closes itself, and its process exits, when it is idle and either a frontend has ever attached or 60 s have passed since it started. Idle means all of:

  • no frontend attached;
  • no run going, starting or stopping;
  • no kept run: a run that ended while no frontend was attached, and that nobody stopped, is kept until a frontend attaches -- but never a chat folded away.

It also closes on SIGTERM, hosts.stop, epic.quit, and when its link to the daemon closes. hosts.* calls do not count as attaching.

Daemon methodEffect
detach()hosts.detach: every frontend is told gone (let go); runs continue. Returns the count.
stop(*, seconds=20.0)hosts.stop; polls every 0.1 s for the pid to go. Returns whether it went. Where the call is refused or not answered, returns not alive.
kill(*, seconds=20.0)SIGTERM to the host's process; after seconds, SIGKILL and up to 20 s more. The daemon and every other host are left alone. Returns whether it went.

Hosts ​

hosts.* ask about a host without attaching to it; all but hosts.open start none, and a workspace and slot no host holds is refused 404, no runs are held in <workspace>, and for <slot> after it for a slot. Daemon.asked(said) calls hosts.<do> with the daemon's workspace and slot over a session of its own (5 s) and returns {} on any failure.

MethodAnswer
hosts.listheld: [{pid, workspace, started, slot}], in the order taken on.
hosts.runningrunning: every host whose epic is going or stopping, with state, run, kind (the epic's: flow or chat), flow, epic, task, turn (a chat's), workspace, slot, asking (<run>:<question>).
hosts.open {workspace, slot?}Starts the host where none is: pid, workspace, started, kind, protocol, slot.
hosts.status {workspace, slot?}The status keys.
hosts.detach {workspace, slot?}let_go, after telling each frontend gone (let go).
hosts.stop {workspace, slot?}{} at once; the host then closes.

Envs of an epic ​

hosts.env.* work in the envs of the epic a host is going with, through each env's own driver on the run's loop, as the flow would; they attach nobody, start no host and tell the epic nothing. Each takes {workspace, slot?}, and each but hosts.env.list an env: the name of an env role, or workspace for the run's own workspace until a LocalEnv role takes it. A path is relative to the env's workdir.

MethodAnswer
hosts.env.listenvs: [{name, kind, workdir, can}], can among read, write, exec, grep.
hosts.env.read {env, path, offset?, length?}text (at most 1 MiB from offset, as UTF-8, bad bytes as U+FFFD), size, eof.
hosts.env.write {env, path, text}size: the file is written whole, its directories made.
hosts.env.exec {env, argv, seconds?}code (null once killed after seconds, default 120), and the last 1 MiB of stdout and stderr.
hosts.env.grep {env, pattern, path?, limit?}matches: [{path, line, text}], at most limit (default 200), each line cut at 400 characters; more. Run as grep -rnIsE in the env.

Refused 409 no flow is running, so no env is open where no epic is going there (or no host is held), 404 for an unknown env or a missing file, 400 for a path outside the workdir (by .., an absolute path, or a symbolic link on this machine) or an empty argv, and 409 The env <env> cannot <what>. where the env lacks the capability.

Text clipping: every string longer than 262 144 characters in a history record or snapshot is cut to that length plus … (<n> more characters).

Status ​

Daemon.status(), Host.status(), hosts.status and epic.status:

KeyTypeValue
pid, workspace, started, kind, protocol †The host process's (kind host) (hosts.status and fallback only).
attached †intFrontends attached.
clientslist[{client, name, kind}].
slotstringWhich of its workspace's hosts: "" its own, chat:<hex> a chat's, exec:<hex> an hmz exec's.
statestringrunning, stopping or idle.
runintThe run going, else the one stopping, else the last; 0 for none.
epic_kindstringThat epic's kind: flow, chat, or "" for none.
flowstringThat run's flow, or "", as it is for a chat.
epic, taskstringThat run's epic (its directory's name, "" before it has one) and task, or "".
pendinglist[{question, role, text, mode}]: the questions waited on, as the pending snapshot says them.
turnstringOf a chat only: running while its agent answers, done between turns and once it is over. Absent where the host holds no chat.
endedobject | nullHow the last run to end here ended: how (done, stopped, refused, budget, failed or crashed), why, epic, at (Unix seconds), run, flow, task; null before one has.
budget, usageobject | nullAs JSON, for the run going; null while stopping or idle. An infinite cost is the JSON string "Infinity".
flows †list[string]Canonical refs of the flow calls in progress.
calls †list[{ref, name, depth, seconds, id, parent}], oldest-started first across every run in the process; seconds rounded to 0.001; parent the index of the calling entry, or null.

A host that does not answer (starting, wedged) yields only the † keys: the Daemon's own fields with attached: 0, flows: [], calls: [].

Calls to an epic ​

epic.attach {workspace, slot?, replay?, since?, figures?, scratch?} attaches the session to a host as one frontend, starting the workspace's host where none is, and answers sub, client, workspace and slot; the host's messages then arrive as epic.event {sub, message}, none before the answer. since {epoch, seq} sends only the records after seq where epoch is the host's and every one after it is kept; figures also sends figures, at most once a second; scratch attaches to a new directory of its own. Every other call to an epic is epic.<do> {sub, …}, answered with the host's fields, or refused 409 with its why; a sub not open on the session is refused 410. epic.start, say, answer, stop, force, afk, claim, release, board and quit are writes, taking idem.

Any callRefusal
from a frontend no longer attachedthis frontend is not attached
epic.<do>Fields (type, default)AnswerRefusals
attachas abovesub, client, workspace, slotthe frontend went while it was saying hello, this host has closed, This chat has folded away., This epic has ended.
startflow (str, required; a chat is started by chat.start instead), task (str), agents ({role: -a spec}), envs ({role: -e spec}), params (object), budget (Budget JSON), profile_flow, profile_environment (bool; whether the run's flow, and the programs its agents start, are profiled), resume (false, true, or an epic path), backup, remember (bool, false)run (int), slot, workspacea flow to start is named, a chat is started with chat.start (on a chat host), a flow is already running, a flow is already starting, this host has closed, an exec host runs one epic (an exec host that has started one), any Refused message. The daemon checks the epic as flows.check does before the host is asked -- so a refusal starts nothing -- and with remember checks it as flows.setup does, writing it down once the host has taken the start, so that a start refused leaves the set-up there was. A run that is only stopping does not block start.

Routing of say ​

toThe line
""Answers a pending listen question the sender may answer, else goes to the first conversation with a turn open (in opening order).
<agent>That agent's newest conversation with a turn open.
<agent>/<n>That conversation.
outworlder:<role>Answers that role's pending listen question only; never put into a turn.

On a chat host, epic.say and epic.answer are refused, say it to the chat with chat.say: every line of a chat, an answer to what its assistant asks included, goes by chat.say.

Chats ​

A chat is started and talked to by calls of its own, each with workspace and slot. chat.start, chat.say and chat.set are writes, taking idem; a frontend follows a chat's messages by epic.attach on its slot, as any epic's.

MethodFieldsAnswerRefusals
chat.startworkspace, slot (a chat slot, or chat: alone for a new one), agent (an -a spec, required unless resume), task (the first message, required, not empty), resume (an epic directory name, or null), prefer (native, flow or null), remember (bool, false)slot, epic (the chat's epic directory name)400 a chat starts with something said, <slot> is not a chat slot., an agent for the chat is named, or why the agent is refused; 404 <epic> is not a chat of <workspace>.; 409 a chat is already going on <slot>
chat.sayworkspace, slot, text{}400 naming the line, for a $ line naming a flow or a name hmz keeps, which the frontend serves; 404 where no host holds the slot; 409 this chat has folded away; carry it on from its epic
chat.commandsworkspace, slotentries ([{sigil, name, about, how, source}]), prefer (native or flow), prefer_from (chat or settings), listed (whether the catalogue is all the CLI lists: once a turn was taken)as chat.say
chat.setworkspace, slot, prefer (native or flow){}400 for any other prefer; else as chat.say
  • chat.start starts the slot's host as epic.attach does, without attaching, and starts the chat there with agent as its assistant and task as its first message. With resume it carries that chat on, in the same epic, task its next turn, with its own agent unless agent is given. prefer is recorded as the chat's own preference. With remember, agent is written as the workspace's chat agent once the host has taken the start; a refused start leaves it as it was.
  • chat.say serves text as a line in a chat is served, and otherwise says it to the chat: the next turn between turns, into the open turn where the harness takes a line mid-turn, held for the next turn otherwise. An empty text ends the chat. A line delivered, held, refused or dropped is recorded as for epic.say.
  • chat.commands answers the assistant's catalogue for its conversation -- or, before it has opened, what its harness's catalogue holds without one -- each with source native; then each name hmz keeps, source hmz and how ""; then each flow on offer in the workspace, sigil $, source flow and how "".
  • chat.set records prefer as the chat's own preference, in its epic.

A line enters a conversation only while a turn is open, one line per agent at a time; it waits otherwise, and the next turn to start takes the oldest matching line into its prompt. A line that answered a listen question is taken by no turn. Accepted lines are reported with said; a backend's refusal with refused (the line returns to the head of the queue).

Asides ​

An aside is a read-only side session: permission read-only, no goals, no skills, no allowed tools, MCP approval off, watched by nothing. Only the newest 256 conversations of the last run can be forked. An aside about a session an earlier run kept is a fork of it carried on from where that run kept it -- into a directory of the aside's own in this machine's directory, removed as the aside is closed, never where that run keeps its sessions nor the CLI's own home -- and a fresh copy of its agent where its CLI does not fork or the session was not kept. An aside is closed on unaside, when its frontend detaches, when a run starts, and when the host closes. No message announces asides. A harness with no read-only rung (mcode, dsh, ACP) is refused: <harness> cannot answer a side question: it has no read-only rung.

The daemon's btw.* asks each side question of a session through a frontend of its own, of kind btw, on the host holding that session: the workspace's own host for the epic in view there, a chat's own slot for that chat. An epic no host holds any longer is asked on the workspace's own host with runs, recall, kept and cwd; an epic starting there does not end such an aside, whose next question opens its side copy again. The daemon reads the epic replayed to it on attaching as the epic going, not as one starting, and lets go of a host a minute after the last aside on it closed or its last question was asked. An aside whose first question fails is not kept.

Ai-chan ​

Each Ai-chan conversation is a chat whose one agent plays her role, held by a host of its own on the slot ai:<hex>: in the workspace of its scope, or, for the scope daemon, in H/ai/<machine>/. Only the daemon starts it, with the conversation's own scope, preset and network; epic.stop there stops her open turn only. Its harness runs at bypass, confined: / denied, the scope root (/ for daemon, the workspace otherwise) read-only under read-only and writable under danger-full-access, its scratch directory H/ai/<machine>/<id>/ writable, and this machine's directory -- the daemon's socket and every scoped link -- denied beneath all of it. A conversation whose confinement cannot be held is refused rather than run wider. It has no budget.

aichan.* ​

MethodFields (default)AnswerRefusals
aichan.create (write)scope (daemon, workspace, epic; required), workspace (for workspace and epic), epic (an epic name, for epic), nous ("": the ai_chan setting), preset (read-only), network (false), title ("": the task's first line, cut at 80), task (required)id, workspace, slot, once its host has taken the start400 An Ai-chan's scope is daemon, workspace or epic., A <scope> scope names its workspace., A daemon scope names no workspace and no epic., A workspace scope names no epic., An epic scope names its epic., An Ai-chan's preset is read-only or danger-full-access., Name Ai-chan's nous: the ai_chan setting names none., <nous> is not a nous or an agent spec., Tell Ai-chan something to start with.; 404 There is no epic <epic> in <workspace>.; 409 the host's why
aichan.list—conversations, newest first: id, title, scope, workspace, epic, nous, preset, network, slot, state (running, waiting, folded), created—
aichan.forget (write)id (required){}; closes its host, removes its entry and scratch directory, keeps its epic's records404 There is no Ai-chan #<id>.

id counts from 1. Conversations are kept in H/ai/<machine>/conversations.yaml across the daemon's restarts. epic.attach on the ai: slot of a conversation whose host has gone starts that host again, carrying its epic on (resume), and attaches; on an ai: slot of no conversation it is refused 404, There is no Ai-chan conversation <slot>. epic.stop on an Ai-chan host interrupts her open turn and leaves the conversation between turns, and is refused with Ai-chan is not answering, so there is nothing to stop while none is open. A host folds its conversation as it folds a chat, and then goes.

Before it starts a conversation's host, the daemon listens on <mdir>/ai-<hex>.sock (0600), the conversation's scoped link, whose path the host gives the flow as HUMANIZE_AICHAN_LINK; it is removed when the host goes. A session over it is admitted as one over the socket, says session.hello with kind ai-chan, and is named Ai-chan#<id> by every host, whatever it says. A session.hello of another kind over a scoped link is refused 403, This link is Ai-chan's.; one of kind ai-chan over any other carrier, 403 Only Ai-chan says hello as ai-chan.

Reach ​

A session over a scoped link carries its conversation's reach: scope, workspace, epic, preset, network. Every call it makes is held to it before it is carried out, by the x-hmz-reach and x-hmz-writes extensions each method carries in openrpc.json:

x-hmz-reach scopeThe method acts onReached by
anynothing of one workspace, or what its answer listsevery reach; the answer filtered
daemonthe daemon, its machine, every workspacethe scope daemon
workspacethe workspace nameddaemon, or workspace of that workspace
epicthe epic or host nameddaemon; workspace where it ran or stands there; epic where it is that epic, or the host's epic going, stopping or last is
neverpairing, devices, credentials, the network's secrets, aichan.*nobody

A call with no workspace where the method names one is held as daemon, and so is epic.attach with scratch. A call is refused 403, with no effect, by the first that holds:

  1. never: Ai-chan cannot call <method>.
  2. it names a host of an ai: slot: Ai-chan cannot reach an Ai-chan conversation.
  3. out of reach: <method> is out of Ai-chan's scope: <what>., <what> being the daemon, the workspace <workspace>, the epic <epic> or the host <slot> of <workspace>
  4. x-hmz-writes and the preset read-only: Ai-chan is read-only, and <method> changes things.

hosts.list, hosts.running, workspaces.list, runs.list and notices.* answer such a session only with what its reach reaches, counts and totals included, and never an ai: slot. An epic reach's subscription ends gone (out of Ai-chan's scope) once another epic starts on its host.

Envs of an epic ​

Ai-chan reads, writes, searches and runs commands in the envs of an epic going on a host, as its flow would, without attaching and without telling the epic. Each takes workspace, slot and (but hosts.env.list) env, a role of the epic; a path is relative to the env's workdir.

MethodFields (default)Answer
hosts.env.list—envs: name, kind, workdir, can (of read, write, exec, grep)
hosts.env.readpath, offset (0), length (1048576, the most)text (UTF-8, bad bytes as U+FFFD), size, eof
hosts.env.write (write)path, textsize; makes the directories
hosts.env.exec (write)argv (non-empty), seconds (1–3600, 120)code (null where killed at seconds), stdout, stderr (each the last 1 MiB)
hosts.env.greppattern (POSIX ERE), path (.), limit (1–2000, 200)matches (path, line, text cut at 400), more

Refusals: 400 <path> is outside the env <env>. (by .., an absolute path or a symbolic link), 400 hosts.env.exec runs a command: give argv.; 404 The epic has no env <env>., There is no file <path> in <env>.; 409 no flow is running, so no env is open, The env <env> cannot <what>., <what> being read files, write files, run commands or search files.

Messages ​

On epic.attach, atomically:

  1. welcome: client, name, kind, workspace, slot, pid (host process), protocol (3.0.0), epoch (this life of the host).
  2. The history records, oldest first (omitted with replay: false; only those after since where it holds).
  3. Every snapshot, in the order clients, claims, away, run, sessions, calls, waiting, pending, usage, board.
  4. live: seq (the last record's), elided (records dropped from the front).
  5. Every later record and changed snapshot, as it happens.

History records ​

Kept per host from the last start (plus anything before the first). Each carries seq, a host-wide counter never reset. Kept up to 32 MiB of JSON; the oldest whole records are dropped first (counted in elided), the newest always kept. Every record but printed carries run.

typeFields
startedflow, ref, task, by (frontend name), client, roles (declared agent roles the line fills), names ({role: agent name}: what the agent filling each is called, which its conversations are keyed by), outworlders (runtime-filled roles), agents ({role: spec}), envs ({role: spec}), params (object), budget (Budget JSON), profile_flow, profile_environment (bool), resume ("", or str() of what was given: "True", an epic path), began (host monotonic), at (Unix time)
openedrole (the role its agent fills), key (<agent>/<n>), agent (the agent's own name, such as NeiKos496), cli, model, counts (sorted token kinds the backend reports), forks (bool), person (bool), kept (directory of the session's logs; "" for a person or the CLI's own home), env, harness, mono, wall (Unix time)
eventkey, session (key where the event names a conversation, else ""), agent, cli, model, ident (backend's conversation id, "" until named), kind, text, whose, tokens, spent, at, mono. Same fields as hmz exec --json.
askedquestion (q<n>, host-wide), role (default outworlder), text, options (list), mode (ask where there are options or a turn is open, else listen), key (<agent>/<n> of the one conversation with a turn open, else "")
answeredquestion, role, by, client, text (the option chosen, or the text)
withdrawnquestion, why: away (the role went afk) or over (the run ended, stopped, was forced or the host closed)
saidtext, key, by, client: a line a conversation took
refusedagent, text, because (the backend's error text, or the agent refused it)
unheldagent, texts: lines a turn ended without acknowledging; discarded
droppedgiven [{agent, text, by, client}], queued [{text, by, client, to}], because (stopped or ended); only where something was waiting
printedtext: one line printed in the host
noticetext: Humanize's own note about the run, after started and before its first turn: nobody lists a price for <model>[, …], so cost=<n> cannot stop what it spends where the run's cost limit cannot be enforced; <backend>:<a> cannot hold '<role>': <why>; using <backend>:<b> where an environment fell back to another runtime. The interface shows it as hmz: <text>, in yellow.
stoppingby, client
endedhow, why, mono

opened.env: null where the driver reported no placement, else:

KeyValue
roleThe environment role the session works in, "" if unnamed.
kindlocal, ssh, docker, swarm, apple-container or slurm.
targetThe ssh host or container runtime; "" for local.
workdirThe directory there.
anchoredtrue where the agent reaches another machine (ssh and container environments).

opened.harness: where the session's harness went.

ValueWhen
""A person, or an agent working on this machine without an anchor.
localHarness here, work on another machine.
envHarness on the environment's machine (native CLI). self, written by an earlier Humanize, means the same.
<backend>:<name>Harness on the saved runtime of that name, which the harness setting of the runtime the work is on named (docker:gpubox).

ended.how and why:

howwhy
done"". Also for a stopped run whose flow returned normally.
stopped""
budgetThe limit reached.
refusedThe Refused message.
failed<ExceptionType>: <message>
crashedA traceback.

Snapshots ​

The latest of each type is kept and re-sent on attach; a changed one is broadcast. No seq.

typeFieldsInitial
clientsclients: [{client, name, kind}][]
claimsclaims: {role: client}{}
awayall (bool), of ({role: bool})false, {}
runstate (idle, running, stopping), then the started fields of the run going or the last (run: 0 for none), stopping (run number or null), epic (its directory's name, "" before it has one), slotidle
sessionsrun, open (keys still open), working (keys with a turn open)0, [], []
callscalls: [{ref, name, depth, since (host monotonic), id, parent (index or null)}][]
waitingqueued [{text, by, client, to}], given [{agent, text, by, client}][], []
pendingpending: [{question, run, role, text, options, mode, key, owner (client id or null)}][]
usagerun, usage (Usage JSON or null), budget; refreshed at most once a second0, null, null
boarditems: [{key, value, about, whose (both, user, flow), by, at}], or null for a run with no board; reset to null on startnull

gone ​

The last message a frontend receives: {"type": "gone", "why": …}.

whyCause
let goepic.detach, hosts.detach, or an in-process Link.close(); a session closing ends its subscriptions without one
the host was closedhosts.stop, epic.quit, SIGTERM, idle close
too far behind; attach againThe host's queue for this frontend, or the session's queue, exceeded 64 MiB
the host went awayThe host process ended without closing; also synthesised by Link where its session ends

After gone the subscription has ended: a call naming it is refused 410.

Frontends ​

Rule
Namessession.hello's client.name, used verbatim; "" becomes <HUMANIZE_NAME or login or "somebody">@<kind>. A name already attached gets #2, #3, …. The final name is sent in welcome.
Client idsc1, c2, … per host; never reused.
ClaimsA claimed Outworlder role may be answered, spoken to (outworlder:<role>) and set away only by its holder. take: true takes it from another holder, which learns it only from the claims and pending snapshots. Claims are released when the holder detaches; its questions' owner becomes null. Claims are not persisted. Claims do not restrict say to agents.
QuestionsRecorded only while the run is current, the host open, and the role not away; otherwise the flow gets no answer at once. Shown to every frontend with owner. Answerable by the owner, or by anybody where owner is null; the first answer wins. They stay pending with nobody attached.
AwayHeld by the host, per role. afk with role sets that role. Without role: with no claims, sets every role and clears per-role values; with claims, roles held by other frontends keep their value. Outlives the frontend that set it.
RunsAny frontend may start, stop, force or quit.
Late arrivalA frontend attaching mid-run with replay: true reads the run from its started record.

hmz.daemon.Link, exported as hmz.sdk.Link. Signatures are on the SDK page; transport behaviour:

AspectThrough the daemon (reached)In process (linked)
Made byDaemon.link(name="", kind="sdk", *, replay=True), hmz.daemon.reached(at, workspace, name="", kind="sdk", *, replay=True)hmz.daemon.linked(host, name="", kind="tui", *, replay=True)
Attach failureOSError (nothing listening; session.hello or epic.attach refused or not answered within 10 s)RuntimeError("this host has closed")
Requestsepic.<do> with its sub, writes with an idem of their own; seconds honoured: TimeoutError("no answer to '<do>' in <s>s"), the call then cancelledRun synchronously; seconds ignored
RefusalRefused(why)Refused(why)
Host gonePending and later requests are refused with the gone reason; a send error with the host could not be reached: <err>—
close()Closes its session; the daemon lets its frontend go. Idempotent.host.detach(client)

Messages are delivered in order, either through iteration (for said in link, ending after gone or close()) or to one listener set with heard(), on a thread named humanize-link-<client>; listener exceptions are suppressed. Setting a listener twice, or iterating with a listener set, raises RuntimeError. Link has no helpers for unaside, status, detach or quit: send them with asked({"do": …}).

python
from hmz.sdk import Daemons

with Daemons().host().link(name="watcher", replay=False) as link:
    for said in link:
        if said["type"] == "ended":
            print(said["how"], said["why"])
            break

Module hmz.daemon ​

python
@dataclass(frozen=True, slots=True)
class Daemon: ...                                   # see SDK › Daemon
def running(workspace=None, *, slot: str = "") -> Daemon | None: ...
def daemons() -> list[Daemon]: ...                  # every host, chats' included
def host(workspace=None, *, seconds: float = 10.0, slot: str = "") -> Daemon: ...
def start(seconds: float = 10.0) -> None: ...                # the daemon, where none runs
def older(daemon: Daemon) -> str: ...
class Older(RuntimeError): ...                      # the runs are held by an older Humanize
def attach(kind: str, name: str = "", *, workspace=None, slot: str = "") -> Link: ...
def linked(host: Host, name: str = "", kind: str = "tui", *, replay: bool = True) -> Link: ...
def reached(at: Path, workspace: str, name: str = "", kind: str = "sdk", *,
            replay: bool = True, slot: str = "") -> Link: ...
def remote(remotes: Remotes, daemon: str, workspace: str, slot: str = "") -> Link: ...
Hmz, Host, Refused                                  # hmz.runtime's, fetched on access

hmz.daemon.link.remote reaches the runs of a workspace on another machine through that machine's daemon, over the session Remotes.client keeps to it, as /epics @<name> reaches it: epic.attach there, as reached attaches over this machine's socket -- its epic.event notifications are the messages told to the link, and each request is the call epic.<do>, a refusal raised as Refused. OSError where that daemon is not reached or will not attach. close() stops following.

attach is how hmz and hmz web reach runs held apart from them: it starts the daemon where none is and attaches through it (epic.attach starts the host), as kind, tried 3 times 0.5 s apart while linking raises OSError, the last of which it raises. A daemon of another protocol raises Older, saying what older says, and nothing is started beside it.

hmz.daemon.link.dialed(at, name="", kind="sdk", *, serve=None, seconds=10.0) opens a session over the socket and says session.hello, answering the hmz.rpc.Peer and the hello; OSError where nothing answers, EADDRINUSE with the refusal of another protocol.

Released under the Apache-2.0 licence.