Glossary
One-line definitions for every term Harn uses to describe a conversation, its parts, and its containers. Where two terms in Harn mean the same thing, the preferred one is marked; the others are alias-only.
For SOTA cross-references (what LangGraph or OpenAI or ACP calls the same idea), see Coming from elsewhere.
Conversation units
LLM call. One request to a language model. Smallest unit. Produced by
llm_call.
Tool call. The model's request to invoke a named tool, with arguments. Lives
inside an iteration; an iteration can contain several. Executed by
agent_dispatch_tool_call or by agent_loop automatically.
Iteration. One model round-trip inside an agent loop: prompt-out,
response-in, optional tool dispatch. Counted in result.llm.iterations.
Preferred name.
Round-trip. Alias for iteration. Used in prose; prefer "iteration" in field names and code.
Turn. Overloaded — historically used for both inner (iteration) and outer
(agent_turn wrapper) units. Prefer iteration for the inner unit and
prompt turn for the outer unit. See SOTA comparison
for the ACP alignment that motivates this.
Prompt turn. The outer cycle: one user message → final agent response,
terminated by a stop_reason. Maps directly to ACP's prompt_turn and to one
invocation of agent_turn.
Agent loop. A function that runs iterations until completion. The body of
the agent_loop builtin. Status outcomes: done, stuck, suspended,
budget_exhausted, provider_error, idle, watchdog, failed.
Agent turn (agent_turn). A wrapper around agent_loop that adds a
completion judge and runs one prompt-turn-shaped invocation. Despite the name,
it can contain many iterations.
Daemon loop. An agent loop that idles waiting for wake sources (triggers, timers) instead of returning when no work is pending. Same primitive, different terminal conditions.
Containers and graphs
VM (virtual machine). The Harn interpreter state for one running script or child task. Most user-facing docs say "interpreter instance" or "child task"; runtime and ADR pages often use VM because they describe implementation boundaries.
Child VM. The isolated interpreter instance created for a spawn or
parallel child task. Captured values are copied into it. Explicit shared
handles such as channels, shared cells/maps, mailboxes, and sync permits are
the way child tasks coordinate with siblings or the parent.
Stage. One node in a workflow graph. Kinds: stage, verify, join,
condition, fork, map, reduce, subagent, escalation.
Workflow. A typed, inspectable, replayable graph of stages with edges and
per-node policies. Executed by workflow_execute. Lives above agent_loop when
orchestration structure matters.
Pipeline. The top-level .harn program with fn main(harness) and
lifecycle callbacks. The container in which agents, workers, and workflows run.
Not itself agentic.
Workflow session. The durable execution record of one workflow_execute
run. Holds artifacts, per-stage results, and the replay trace.
Durable state
Session. The first-class VM resource that owns a transcript, subscribers,
parent/child lineage, a pinned system prompt, and a pinned model. Created by
agent_session_open. Outlives any single agent loop.
Transcript. The structured {messages, events, assets} document that hangs
off a session. messages are durable conversational turns; events are an
audit trail; assets are large or non-text payloads.
Transcript event. One entry in the events log. Includes iteration_start,
iteration_end, tool dispatch events, reminder events, and lifecycle events.
Snapshot. A frozen, serializable copy of a session or worker state, used for resume-after-suspend and for replay.
System reminder. A typed, turn-boundary injection into the transcript.
Carries a mode (interrupt_immediate, finish_step, audit_only),
a role_hint, optional dedupe_key, and optional TTL. See System
reminders.
Delegation
Worker. An agent running in its own execution context with its own
transcript and loop. Spawned by spawn_agent; can be suspended, snapshotted,
and resumed. The unit of parallelism and of multi-agent orchestration.
Subagent. A worker in a workflow context. The subagent node kind delegates
a stage to a child agent.
Persona. A typed multi-stage agent identity with handoff policies, profile bulletins, and per-stage tool scoping. Built on top of agent loops and sessions.
Skill. A bundle of metadata, system-prompt fragment, scoped tools, and
lifecycle hooks. Passed to agent_loop via the skills: option to match,
activate, scope, and deactivate across iterations.
Steering and lifecycle
Suspend. Cooperatively pause a worker at the next iteration boundary. Persists a resumable snapshot. Not a sleep — the runtime honors the boundary and emits a lifecycle event.
Resume. Wake a suspended worker, optionally with new input.
Self-park. A worker pausing itself from inside the loop via
agent_await_resumption(reason, conditions, resume_by). The model decides to
wait for something.
Steering. Any out-of-band influence on a running agent: injecting a system reminder, queuing a user message, revoking a pending injection, cancelling an in-flight tool call. See Steering seams.
Inject mode. The bridge-injection variant for system reminders. Three
values: interrupt_immediate (drain at the next safe seam, including
pre_tool_dispatch — the model's pending tool batch is skipped when one
arrives there), finish_step (drain at the next iteration boundary),
audit_only (drain at loop exit and append to the transcript; the model
never sees these — use finish_step if the model must react before the
agent terminates). The full seam catalog lives in
Steering seams.
Checkpoint. A safe point in the loop body where the runtime checks for
pending steering injections. Every drain in the agent loop and the daemon
idle path routes through __agent_loop_checkpoint(kind); observers
subscribe via register_checkpoint_hook(kinds, handler). See
Steering seams for the canonical catalog.
Things Harn doesn't use as nouns
Thread. Not a Harn term. The role thread plays in Mastra and LangGraph is
filled by session here. If you arrive from those systems, read thread as
session.
Step. Used informally in prose; the formal noun for the same concept is
stage in workflows and iteration in agent loops. The Inngest-style
step.run memoization barrier exists as a stdlib namespace for durable replay
of completed handler results.
Run. Used colloquially for "one invocation of a pipeline or workflow." Not a first-class noun in the language.
Phase. Appears around pipeline lifecycle callbacks but is not a conversational-unit noun.
Where each concept's authoritative reference lives
| Concept | Reference page |
|---|---|
llm_call, llm_call_structured, llm_completion | LLM calls |
agent_loop, agent_turn, profiles, done_judge | Agent loops |
| Tools, Tool Vault, MCP server tools | LLM tools |
| Sessions, fork, reset, compact, snapshot | Sessions |
| Transcripts, events, assets | Transcript architecture |
| Workers, suspend, resume, self-park | Agent lifecycle |
| Workflows, graphs, stages | Workflow runtime |
| Pipelines, harness, lifecycle callbacks | Pipeline lifecycle |
| System reminders, inject modes | System reminders |
| Skills | Skills |
| Personas | Personas |
| Daemon loops | Daemon stdlib |