Glossary
PreviewAvailable on: WindowsmacOSLinuxShips in the preview channel only. Not a stable release.
Canonical definitions, with the distinctions that matter kept sharp.
Terms are grouped by what they belong to. Where two terms are commonly conflated, the difference is stated rather than implied.
Four distinctions to get right first
IMPORTANT
A terminal is not an agent. A pane can run a plain shell forever with no model involved.
Installed is not authenticated. Harmony can detect a provider binary and still be unable to run a turn.
Queued is not delivered. A message can reach a harness and never start a turn.
Process alive is not working. An agent can hold a session open and advance nothing.
Product
| Term | Definition |
|---|---|
| Harmony | The product as a whole: desktop, TUI, CLI, daemon, and MCP server |
| Harmony Desktop | The Electron application — the full-surface client |
| Harmony TUI | The terminal-native agent surface, started with nala; its real model turns do not imply browser act authority |
| Harmony CLI | Scriptable, non-interactive commands against the same daemon |
| Harmony Agent | The first-party agent identity, as distinct from third-party providers. Its provider id is still nala-agent, and the Harmony TUI that hosts it still launches with nala, the product's original name |
| Pi | The extensibility runtime bundled with the product |
Runtime
| Term | Definition |
|---|---|
| Daemon | The local process that owns durable state: sessions, orchestration, tasks, artifacts, A2A, channels. Survives app close |
| Session host | Owns provider processes and PTYs, plus launch reservations and principal registration |
| Client | Anything presenting the daemon's state — desktop, TUI, CLI. Closing a client does not stop work |
| Native Capability Bus | The capability layer clients use to reach daemon functionality |
| Principal | A registered identity a session runs as |
| Writer lease | The mechanism deciding which participant may write a shared record |
Workspace model
| Term | Definition |
|---|---|
| Workspace | A named context with its own pane tree, working directory, and status |
| Surface | A tab within a workspace: terminal, browser, editor, diff, file tree, or a Harmony panel |
| Pane | A leaf in the split tree. Max 20 per workspace |
| Terminal session | A durable shell owned by the daemon, rendered in a pane |
Agents and routes
| Term | Definition |
|---|---|
| Agent | A model-driven participant that can take work |
| Agent session | A durable conversation with an agent |
| Provider | The vendor behind an agent CLI (Claude, Codex, Cursor, …) |
| Account profile | Which of your identities with a provider is in use |
| Model | The specific model requested |
| Effort | Reasoning depth, where the provider exposes it |
| Execution route | The full path: harness, provider, account, model, effort, tool set, platform, billing class |
| Billing class | Whose money is spent, under which plan |
| Harness | The agent program being driven |
Work
| Term | Definition |
|---|---|
| Task | A durable unit of work with an identity and a state. Outlives panes and reboots |
| Plan | A proposed sequence of steps toward a goal |
| Plan revision | A numbered version of a plan; revisions are kept |
| Orchestration run | One execution attempt of a plan |
| Artifact | A durable Markdown output attached to the work |
| Worktree | A separate git checkout so parallel agents do not collide. File isolation, not a security boundary |
| Delegation | An edge assigning a task to another agent |
Messaging
| Term | Definition |
|---|---|
| A2A | Agent-to-agent messaging: send, ask, reply, inbox |
| Channel | A durable, Slack-like room for agents and humans |
| Attention | The signal that something needs a human |
| Approval | An explicit consent gate before a consequential action |
Delivery states
The real states Harmony reports, not a generic lifecycle:
| State | Means |
|---|---|
received_and_started | The agent is working on a turn. The only state where started is true |
queued_behind | Accepted into the harness queue, with N ahead |
received_not_started | Text delivered, no work signal yet |
idle | At the prompt, queue empty |
needs_enter | Staged in the composer, needs another Enter |
unknown | Could not be determined from available evidence |
See delivery lifecycle.
Persistence and memory
These terms describe an agent outliving its session. Each mechanism is independent — identity, provider session, checkpoint, and memory are four things, not one — and the labels match persistent agents and memory and feature status exactly.
| Term | Definition |
|---|---|
| Persistent agent | A durable Harmony identity — identity plus a frozen checkpoint — that can be reactivated later. The persistentAgents.enabled gate is off in current builds (the surface refuses with NALA_CAPABILITY_UNSUPPORTED). Not a provider login, not "this exact AI is preserved" |
| Checkpoint | A frozen, integrity-checked snapshot of workspace and session state taken at save time. Not the live process, and not its scrollback |
| Incarnation | One recorded run of the same persistent agent. Opening a validated Harmony session or starting a newly rehydrated worker appends a local incarnation; a verified Cloud return appends another, never a copy or a duplicate and never an overwrite. A Cloud import receipt alone is not proof of a running provider |
| Prepared activation | The activate API's bounded, checkpoint-bound plan, not by itself a running worker or a new incarnation. Desktop/TUI Open now consumes this plan through a daemon-owned supervised launch; a fallback offer starts no worker until the user explicitly chooses rehydration |
| Rehydrate | With an explicit user choice, start a new supervised Harmony worker from the latest checkpoint and admitted, same-agent memories as bounded labeled loader data, never a fake user message. A prepared/declined offer starts none. Distinct from exact resume and provider /resume |
| Exact resume | Continue the same Harmony Agent Pi transcript only after Harmony validates a sealed file/path/hash/SDK-session/journal watermark and the real spawned worker opens it and returns a matching ready proof. Desktop/TUI Open uses it when proven; a failure offers, never silently switches to, rehydration. Third-party adapters remain rehydrate-only; a separate TUI worker is not same-pane attachment |
| Host-derived trust | Whether a caller may store or recall is decided by the daemon from its own agent and session registry — never from a flag in a request, a hint on the wire, or the model's own say-so. Content an agent reads is data, not permission |
| Connection-bound agent | A pipe socket bound to one agent after a daemon-verified first-party launch handshake (nonce, intent/session and live-process checks). A shared token alone leaves it unbound; a wire caller hint is not proof. Stock Node does not attest the socket's OS process |
| Agent-driven embedded browser | Requires default-off browser.embeddedBackend.enabled, explicit embedded selection and an authenticated host invoker; distinct from the ordinary browser pane. Real Electron 44 offscreen/sandbox-on local fixture exercised act/upload/download, guest-death notice over the authenticated daemon pipe and tiled full-page pixels (38/38); no packaged or independent visual/OCR release proof |
| Provider-native context fragment | Default-off root AGENTS.md/CLAUDE.md opt-in, bounded/hashed untrusted-user-authored loader data only for rehydration. The daemon derives a verified launch-intent workspace root or refuses ambiguity; no provider-native session/memory import, credential read or model obedience guarantee |
| Persistent-agent entitlement state | Read-only local-client projection of local_core, entitled, lapsed or unknown. No site grant reader is wired here; this status never gates local Core save/activate or erases on lapse |
| TUI persistent-agent commands | /save and scoped /agents picker/review are default-off; /agents open now launches an exact resumed separate worker or explicitly asks before rehydration, never silently rebinds the active pane. /fleet, /agents fleet and Alt+A keep the live fleet; /browser operator RPC is live only when bound and enabled, and Resume still needs host verification |
| Persistent-agent Cloud identity block | Optional, default-OFF v2 stable agentId, filtered portable checkpoint and incarnation lineage. MAIN owner review, idempotent site-side incarnation import and site-HMAC-verified return can append a new local incarnation; memory defaults none and selected admitted-scoped only. A stored identity is not exact provider resume or an active Cloud worker |
| Cloud handoff continuity | Same agent ID/checkpoint/lineage crosses only after Desktop owner review and independent Cloud+identity gates. No provider sessions/credentials, secret/local-only/sensitive/global/pending memory, job packets or full transcript cross; return appends after HMAC verification, never overwrites. Terminal `/cloud handoff |
| Cloud activity and identity card | Owner-scoped, read-only recent site workspace events and optional imported-incarnation receipt behind default-off Cloud/identity gates; unknown/absent is not a completed task or a resumed provider. The event cursor and DB index still need deployed-site qualification |
Memory states
The states a save receipt reports for memory work, rendered verbatim. A staged candidate is not admitted memory:
| State | Means |
|---|---|
not_started | Extraction has not started; on an extract-mode save, independent job enqueue was not confirmed and can be retried/reconciled |
deferred | No completed memory result on this receipt: defer mode schedules no job now, while a successful extract enqueue has a separate durable job for later work |
not_applicable | The checkpoint-only path; no memory work by design |
unknown | An unrecognized state. Rendered as-is, never presented as success |
There is deliberately no "queued" or "complete" memory state on a save
receipt. Owner-scoped inspect reports job states (queued, leased,
retry_wait, complete, abandoned) and redacted disposition counts
separately. A completed job can admit zero memories. The extractor is
structural, deterministic and uses no model call; retained external
candidates remain review-required, while host-verified explicit user evidence
may be admitted after policy checks.
Privacy and retention
| Term | Definition |
|---|---|
| Forget memory | nala.memory.forget tombstones one owned persistent-agent memory, excludes it from future daemon recall and advances a durable cache epoch. It cannot retract context already delivered to a model or erase backups |
| Archive agent | Hides an agent from active selectors while preserving its identity, checkpoints, incarnations and memory |
| Delete agent | A separate workspace-bound confirmation token is required (not independent proof of a human click); confirmed deletion scrubs Harmony-owned checkpoints/incarnations and denies/scrubs the agent memory bank, leaving a minimal audit marker. A lapse does not delete, and provider-native session files are not removed |
| Export agent | A bounded, redacted bundle of Harmony-owned identity, checkpoints and eligible memory with integrity hashes. Forgotten memory, credentials and provider-native session files are excluded; import/restore is not implemented |
Browser-agent and job evidence
The Harmony browser agent page separates landed, default-off browser actions, packet/quarantine and ledger code from a real end-to-end application workflow, which is not available. A capability approval is not external confirmation.
| Term | Definition |
|---|---|
| Agent browser | Verified-session, approval-checked browser tools, default mode off; distinct from an ordinary browser surface. Standalone needs explicit selection; embedded also needs a separate default-off latch and qualified host invoker |
| Browser surface lease | Daemon-owned, time-limited receipt tying the actual target to a launch/session/principal/workspace/task (and verified embedded pane), not a page-chosen tab. Transitions are durably journaled; physical closure says confirmed only after backend ACK and otherwise awaits repair |
| Untrusted page observation | Bounded DOM and element refs framed as untrusted-page data with provenance/hash, never an instruction or grant to act. Standalone and real-Electron fixture embedded CDP screenshots pair to a DOM hash; visual-text agreement is still unassessed. Harness quotes/hashes page/download/clipboard fragments in an inspector projection, not yet Pi's provider-wire constructor |
| Observation generation token | Short-lived token tied to one lease/surface/DOM observation; each act/upload needs its latest opaque element ref, fresh DOM, paired screenshot and separate approval. A stale token, changed page, forged ref or missing evidence refuses; a token alone is not authority |
| User fact packet | Host-verified scope/origin-bound allowlist for type/select valueId; the model sends no raw field/selector/JS. A gated daemon resolver reads only the active approved JobPacket: ordinary text facts and answered revisions after approval, not arbitrary or model-invented facts. Missing values still refuse NALA_RUNTIME_TOOL_MISSING_FACT, do no browser effect and require a human answer/new packet approval; backend selection alone is not permission |
| FactRequest | A restart-durable, owner/application/field/origin-bound missing-fact question with A2A notice; queued is not delivered. Human TUI/Desktop answers create a draft JobPacket revision with who/when provenance; MAIN-reviewed approval, not the answer alone, permits fresh-observation retry. Unanswered stays blocked |
| Human browser takeover | Positive login/credential/passkey/MFA/CAPTCHA heuristics block agent browser calls and hand the live lease to a human; negative detection proves nothing and never justifies bypass. /browser handoff uses a bound operator RPC; Resume requires independent host-verified local-user proof, not a typed command. Without a runtime pause callback only browser tools pause |
| Submit gate | browser_submit refuses with default submitArmed: false. Desktop has a redacted pre-submit review of a pending gate request, but production still lacks the trusted current-form/intent reader and armed gate, so a flag edit or modal alone cannot submit. An armed local fixture still needs host intent, fresh diff/approval and deny/kill policy; a ticket/click is not an external receipt |
| Approved job packet | Content-addressed facts/provenance and reviewed PDF. Desktop/MAIN/daemon can approve/revoke and bind an active packet; executor refuses unapproved/revoked/foreign files. Release hold: worker's browser_upload catalogue is static at initialization before the packet becomes active, so per-turn advertisement/revocation is not solved. Page text cannot approve or invent a fact |
| Download quarantine | Per-session host-controlled allowlist for PDF/text/CSV downloads; size/MIME/hash checked, bytes never executed or promoted to memory. The model sees only untrusted-download hash refs, not paths or trusted content |
| Application ledger | Implemented under jobs.applicationLedger.enabled: false (schema v9, nala.jobs.*, read-only harmony jobs): canonical HTTPS job identity, dedup, state/evidence and restart receipts, not a browser submit engine or general memory |
| Verified submission | submitted_verified requires host-matched owner-scoped confirmation observation after an authorized attempt. Production jobs RPC lacks the host approval/confirmation artifact verifier, so it cannot normally mint this verdict; observed page confirmation is not independent employer acceptance |
| Outcome unknown | A durable ambiguous attempt (outcome_unknown), not a successful application and never automatically retried; human reconciliation or fresh verified confirmation is required |
| Browser lifecycle span | Closed redacted navigate/settle/act/upload/download/handoff/deny event in the existing activity ledger, with bounded scoped read projection. Not an external success receipt; live UI reader still unwired |
Extensibility
| Term | Definition |
|---|---|
| Skill | A packaged capability an agent can invoke |
| Command | A slash command in the TUI or desktop composer |
| Prompt | Reusable instruction text |
| Extension | Code extending the application |
| Plugin | A packaged extension |
| Hook | A handler fired on a lifecycle event |
| MCP | Model Context Protocol — Harmony publishes tools to MCP hosts |
| ACP | Agent Client Protocol — Harmony can drive external ACP harnesses |
SECURITY
Extensions, skills, and plugins are not sandboxed by default. Treat third-party extension code as code you are choosing to run.
Modes
| Term | Definition |
|---|---|
| Safe / YOLO / Ask | Execution modes governing how much an agent may do unprompted |
| A2A mode | Off, Connect, or Orchestrate — how much agents may coordinate |
| Crew Mode | Ownership-scale delegation, separate from the YOLO authority setting. Experimental; see feature status |