# Glossary Source: https://docs.ideharmony.com/reference/glossary 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](/docs/a2a/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](/docs/concepts/persistent-agents-and-memory) and [feature status](/docs/reference/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|return` only routes to Desktop | | **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](/docs/concepts/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 | ## Related - [Feature status](/docs/reference/feature-status) - [Known limitations](/docs/reference/known-limitations) - [Concepts](/docs/concepts/architecture) - [Persistent agents and memory](/docs/concepts/persistent-agents-and-memory) - [Harmony browser agent](/docs/concepts/harmony-browser-agent)