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.
Portable kernel. The authority-free Harn compiler and deterministic execution state machine shared by native and browser hosts. It accepts a versioned program artifact and returns completed, suspended, or failed.
Program artifact. An immutable, versioned encoding of checked Harn bytecode plus the metadata needed by the portable kernel. It is data, not a serialized Rust object or a grant of host authority.
Linked program. The closed native execution artifact inside a schema-v3
.harnpack. It contains the entry bytecode and only the reachable module
symbols needed by that exact source graph. It is separate from the
authority-free portable-kernel program artifact.
Capability request. A typed request emitted when portable execution needs host-owned authority. The host may deny it or resume the authenticated snapshot with a matching typed result.
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. See the
workflow runtime.
Pipeline. The pipeline language keyword: a named, callable, function-like
composition serving as the top-level entrypoint of a .harn program, with
lifecycle callbacks. The container in which agents, workers, and workflows run.
Not itself agentic — and not the stage-graph runtime, which is a workflow
(above). See the pipeline lifecycle.
Workflow session. The durable execution record of one workflow_execute
run. Holds artifacts, per-stage results, and the replay trace.
Durable state
Model job. One finite, asynchronous model request with a closed lifecycle:
queued, running, succeeded, failed, or canceled. Harn owns its events,
receipt, output storage, and replay; a backend owns provider translation. See
Why Harn has model jobs.
Media asset. Model output bytes stored under their SHA-256 digest. A media
asset has a portable asset://sha256/... identity, a verified MIME type, and a
current local path. See the model-job reference.
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. Its session_id
identifies the transcript owner; a run_id identifies one exact invocation
within that history.
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.
Run report. The versioned JSON view produced by
harn runs report or the harn.run.report MCP tool. It correlates a root run
with delegated child runs, timelines, trace spans, and verified transcript
pointers, then reports structural checks without changing the source data.
Run review. The versioned model assessment produced by harn runs review
or harn.run.review from one validated run report. Harn can build that report
in memory from a root run record. The review binds its verdict and evidence-addressed
findings to the report, rubric, and resolved model route. It does not replace
the run report's deterministic checks or read source artifacts itself.
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. Persisted runtime records still use a
run_id as the stable identity of one exact invocation; do not substitute a
session ID for it.
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 |
| Portable artifacts, capability requests, execute/resume | Portable kernel contract |
| System reminders, inject modes | System reminders |
| Skills | Skills |
| Model jobs, receipts, media assets | Model-job reference |
| Personas | Personas |
| Daemon loops | Daemon stdlib |