Canonical terms used across the neenee documentation. Each entry links to its primary explanation or decision record. Where a term names a code symbol, the symbol is backticked and never abbreviated.
neenee names its two execution layers after ADR-0047: a round is the user-perceived exchange (one submitted message and one final reply), and a turn is one iteration of the ReAct loop inside it. This is the inverse of the pre-ADR-0047 convention, which older documents may still use. See Rounds and turns.
| Term | Definition |
|---|---|
| round | The unit the user perceives: one admitted message and one final reply. Opens after UserPromptSubmit admits the prompt, closes when the agent emits a final assistant message carrying no tool call. Driven by execute_round. Rounds and turns |
| turn | One pass through the ReAct loop inside a round: one model request plus the tool work that follows. The in-round iteration count resets every round. Rounds and turns |
| provider attempt | One concrete network attempt inside a turn. A safe retry increments the attempt while retaining the same round and turn. State model |
| round lifecycle | The at-most-one-active-round protocol per session, owned by RoundLifecycle: a new round supersedes its predecessor (generation bump + fresh cancellation token); interrupt cancels without superseding, so the unwinding round still emits its own cleanup. ADR-0078 |
round_counter |
Monotonic counter bumped once per round and persisted across resume; stamps todo staleness. Legacy snapshots/config events using turn_counter remain readable. Rounds and turns |
| ReAct loop | The model-request → tool-call → result loop iterated once per turn inside a round. Rounds and turns |
| harness | The control plane around provider calls; keeps model output inside explicit state, execution, and safety boundaries. Owns steering, retry, and the round loop. Harness architecture |
| transcript | The append-mostly message history resent in full on every request — the model's only memory between requests. Never edited to change meaning. Rounds and turns |
| catalog (tool catalog) | The list of tool schemas published to the provider on every request; ephemeral to the runtime, republished each turn. Rounds and turns |
| gating stack | The ordered checks every tool call crosses before running: lookup → write-scope gate → permission broker. Rounds and turns |
| native tool-call path | The runtime carries tool calls in its own structured field; nothing executes until the response terminates. Rounds and turns |
| fallback tool-call path | For providers without native function calling: the model emits a call as ordinary text, the agent extracts it and promotes it onto the assistant message. Rounds and turns |
| repeated-call guard | The only in-loop guardrail: three identical tool calls in a row are stuck, so the fourth is rejected as an error. Harness architecture |
| uncapped agentic loop | Distinct tool calls and autonomous iterations are uncapped; context compaction is the backstop. ADR-0009 |
| hidden user message | A message that steers the model but is not rendered in the visible transcript (implicit skill body, hook-injected context). |
The runtime has one execution engine (Agent) that runs in one of two roles.
agent is the umbrella term; principal and envoy name the concrete roles.
| Term | Definition |
|---|---|
| agent | Umbrella term for the execution engine (Agent, crate neenee-agent) and the engine-level protocol (AgentRequest / AgentResponse / AgentEvent / AgentOp). Every running role is an agent; use principal or envoy when the role matters. Harness architecture |
| principal | The top-level, human-facing agent a frontend drives. Owns the visible conversation and the user-tunable [principal] config table (hard_stop_turns, allow_model_stdin, and the advanced nudge guard). Configuration |
| envoy | An isolated child agent the principal spawns via the envoy tool to serve a bounded sub-question; fresh history, profile-filtered tools, shares only the provider. See the Envoys section. Envoys |
| Term | Definition |
|---|---|
/schedule scheduler |
Clock-driven scheduler: schedules a prompt on a cron expression (recurring) or a countdown / absolute-time (one-shot), stores jobs durably as session-scoped ScheduledJob state, fires a fresh round per tick, drops once-jobs after firing, and auto-expires recurring jobs after 30 days. |
/repeat |
Cron-only alias for /schedule, retained for the recurring-cron use case. |
| Term | Definition |
|---|---|
| todo list | The single source of truth for remaining work, shared with todo/todo_update, shown in the Activity modal, and persisted across restarts. The model populates it directly; there is no longer a plan tool that seeds it. ADR-0020 |
| stop-gate | The round-exit forcing function: any Stop hooks. It is the only gate that can refuse a round ending and force one more turn. Harness architecture |
| Term | Definition |
|---|---|
| envoy | An isolated child agent spawned by the envoy tool to investigate a sub-question; shares only the provider with the parent, runs with a fresh history and profile-filtered tools. Envoys |
| profile | A declarative bundle (name, system-prompt fragment, and a ToolPolicy) that scopes an envoy's behavior; bound by reference by dispatch tools. Envoys |
EXPLORE profile |
Research role: Read ceiling, no write grant; pure read tools. Bound by the envoy tool. Envoys |
CODE profile |
Coding role: write-capable (admits bash/edit_file/write_file). Runs autopilot like every built-in envoy — the delegation via envoy_code is the authorization. Bound by the envoy_code tool. ADR-0087 |
REVIEW profile |
Read-only transcript auditor role used by the session-review diagnostic. ADR-0016 |
TITLE profile |
Read-only role used to generate a session title in a single model call. ADR-0022 |
| full-duplex | An envoy is not fire-and-forget: requests travel up to the parent, replies travel down to the exact child. ADR-0029 |
| Term | Definition |
|---|---|
ToolAccess |
An ordered enum (Read < Execute < Write); variant order is load-bearing. Each consumer expresses its rule as a threshold. Tool access |
Read tier |
Inspects state, no side effects. Admitted by every envoy profile; bypasses the permission broker. Tool access |
Execute tier |
Runs commands; may have external side effects but is not a file-mutation primitive. Broker-prompted. Tool access |
Write tier |
The tool's purpose is to mutate the workspace. Broker-prompted unless covered by a write_paths grant. Default when a tool does not override access(). Tool access |
| capability axes | Beyond access(), the Tool trait exposes requires_user() and spawns_envoy(), consulted for envoy admission. Tool access |
ToolPolicy |
An envoy profile's policy: an access ceiling, an allow_user_interaction flag, and a write_paths grant. Tool access |
| ceiling | The ordered ToolAccess threshold a profile admits tools at or below. Envoys |
write_paths grant |
A declarative relative-dir spec on ToolPolicy; admits a Write tool below the ceiling, then scoped at runtime. ADR-0028 |
WriteScope |
A runtime, per-agent filesystem-write boundary (None / Scoped / Unrestricted); enforced softly — out-of-scope calls go to the user, not a hard block. ADR-0028 |
| write-scope gate | The gating-stack step (after lookup, before the broker) that routes out-of-scope write tools to the broker for the user to decide; hard-blocks only under autopilot, where no human can answer. Rounds and turns |
| permission broker | The interactive authorization surface: Write/Execute tools pass through it before execution; offers once/always/reject. Harness architecture |
| autopilot | When on, the agent runs without human intervention: tool permissions auto-approve, the question tool is reclaimed, and interactive stdin is closed — it decides and acts on its own authority. Affects the live process only. Slash commands |
tool_call_id pairing |
The wire requirement that every result message references a preceding call id; preserved across pruning and fallback. Rounds and turns |
| Term | Definition |
|---|---|
| skill | On-demand domain expertise: a Markdown document with a small YAML header whose body is injected into the conversation when needed. Not a tool — carries no executable code. Skills |
SKILL.md |
The skill file inside its own directory (so it can carry auxiliary files); YAML frontmatter declares identity/behavior. Skills |
| skill discovery | On-demand skill metadata returned by the list_skills tool; the system prompt carries no skills catalog. Skills |
| skill body | The full Markdown expertise document, delivered on demand through use_skill or an explicit implicit-invocation marker. Skills |
| skill scope | The ordered source priority cascade (lowest→highest): Remote, User, Extra, Repo. Higher scope overrides a same-named lower scope. Skills |
| implicit invocation | Explicit mention detection: the harness recognizes @skill-name, the disambiguated @skill:name / @skills:name, or skill://… and loads allowed skills as a hidden user message. Plain name occurrences do not trigger loading. Skills |
The user input box recognizes @-prefixed mention syntax in the latest
visible user message. Each mention form injects context or switches state
before the round runs.
| Term | Definition |
|---|---|
@file: mention |
Implicit file-content injection: @file:src/main.rs (or @files:…) reads that file and appends its contents as a hidden user message, so the model sees the source without an explicit read_file call. Sandboxed to the workspace root (symlink-hardened: absolute paths and .. are rejected), capped at 50 KB per file and 10 files per round. Rejections surface as a hidden error note so the model learns why and can recover. |
@skill: mention |
Disambiguated skill mention: @skill:name / @skills:name (plural mirrors @files:) load the named skill as a hidden user message, alongside the bare @name and skill://… forms. See Skills |
@principal: mention |
Runtime role switch: @principal:architect (code / architect / reviewer / security) switches the active principal role for the round — same effect as /principal <role>. Slash commands |
@path mention |
TUI completion trigger only: typing @ opens path completion; the @ is dropped on accept. Not an injection form. Input box |
| Term | Definition |
|---|---|
| model context | The provider-facing view for one request: rebuilt system prompt, current model window, and current tool catalog serialized for the selected provider. Model context |
| model-context projection | The durable archive-and-replace operation that records original context in the session store and produces the model-visible window sent on later provider requests. Session persistence |
| model window | The current model-visible message window restored on resume and sent to the provider after prompt assembly and provider-specific filtering. Model context |
| archived transcript | Original messages moved out of the model window by pruning or compaction but retained in the durable session for full recovery. Session persistence |
| context pruning | The cheap first projection layer: clears stale tool-result bodies while preserving the tool_call_id chain. Context pruning |
| context compaction | The heavier second projection layer: summarizes older complete rounds into a durable checkpoint with a visible Compacted notice. Context compaction |
| overflow recovery | The reactive backstop: if a provider reports context overflow before any tool event, the runner may compact and retry once. Harness architecture |
| pressure | Context size estimated in tokens (~4 chars/token), compared against thresholds derived from the active model's context window. Configuration |
| current context | Replaceable token projection of the next provider input for one session. It is a state value, not an accumulated usage total. Token accounting |
| request attempt | One concrete provider request, identified within a session by actor, round, turn, and attempt number. Retries are separate attempts because each may be billable. ADR-0055 |
| request usage | Additive input/output/cache accounting for provider request attempts, recorded as reported, estimated, or pending. Distinct from current context. Token accounting |
| Term | Definition |
|---|---|
| provider | An LLM backend implementing the Provider trait; selected at startup and on /models switch. Providers |
ModelRequest |
The immutable core contract carrying provider-visible messages and admitted tool declarations together for one call. ADR-0061 |
Channel |
The fully resolved materialization of a provider id: credentials, model id, transport, and optional provider-scoped remote metadata; one per [[providers.channels]] entry. Model Metadata |
| transport | The wire protocol a channel uses (OpenAi, Anthropic, Google). Configuration |
| model catalog | Centralized provider-construction factory; every provider id materializes into a Channel, so startup and runtime switching share one resolution source. ADR-0005 |
RetryableError |
The marker type wrapping transient provider errors; prefixed [NEENEE_RETRYABLE]. Providers |
| provider retry | Round-level retry loop: transient HTTP 408/429/5xx failures retried with bounded exponential backoff; retryable errors become terminal once any tool has run. Harness architecture |
| fitted model | A model id the static registry does not know, materialized from a trusted provider's live /models capability fields (context window, reasoning, vision, effort tiers); persisted per instance and overlaid onto model::resolve behind the static registry. ADR-0065 |
| model discovery | Live GET /models fetch for template-sourced provider instances (ModelSource::Api); the result is intersected with the client registry, or fitted wholesale for trusted templates. ADR-0065 |
| remote model metadata | A trusted provider's persisted capability and endpoint snapshot for one channel. Explicit remote fields override the static baseline only for that provider route. Model Metadata |
| Term | Definition |
|---|---|
| durable session | The local recoverable scene for one coding session: durable transcript, model window, archived transcript, title, task list, and projection metadata. Session persistence |
| admission | Writes the visible or hidden user message before provider work; each round records its admission session id. Harness architecture |
| XDG layout | Files classified by nature and routed to Config, Data, State, Cache, or Runtime categories with different operational lifetimes. Persistence |
| override precedence | Who decides a path, highest→lowest: CLI flag → app env (NEENEE_*_DIR) → standard XDG env → native per-OS default → $HOME fallback → current directory. Persistence |
| per-project bucket | Under Data; keeps each working directory's history isolated. The hash is short (16 hex chars / 64 bits). Persistence |
| advisory lock | Process-level single-instance-per-project lock; falls back to State when no runtime dir is available. ADR-0018 |
| Term | Definition |
|---|---|
| lifecycle hook | A user-configured shell command that runs automatically at a specific point in the agent's lifecycle. Lifecycle hooks |
| lifecycle event | The events hooks fire on: SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, Turn, TurnStart, PermissionRequest, UserQuestion, PreCompact, PostCompact. Lifecycle hooks |
| implicit capability | What a hook may do is implied by its event, not a knob: PreToolUse/Stop may deny; PostToolUse/UserPromptSubmit/PreCompact/Turn/TurnStart may inject context; PermissionRequest/UserQuestion are observe-only (fire-and-forget notifications). Lifecycle hooks |
| matcher | A tool-name filter on the tool events: a ` |
| Term | Definition |
|---|---|
| model-request assembly | The pure pre-provider projection that clones the current window, removes non-driving command echoes and legacy system messages, composes one fresh system message, and snapshots admitted tools into ModelRequest. ADR-0061 |
SystemPromptSection |
An agent-owned declarative system-prompt fragment with a stable id, rank, activation predicate, and renderer. ADR-0056 |
| system-prompt registry | Agent policy that sorts active SystemPromptSections by rank and folds them into the singleton head system message of an ephemeral request. It does not construct user-role context or mutate the durable model window. ADR-0061 |
SystemPromptContext |
The agent-owned, read-only snapshot of live identity, admitted tool names, model/provider guidance, and autopilot state used by system-prompt sections. ADR-0056 |
| harness context message | A model-visible user-role message inserted by the harness rather than authored by the user. Common constructors enforce role, visibility, and provenance; lifecycle owners decide payload and insertion time. Prompt and message assembly |
| Term | Definition |
|---|---|
neenee-core |
Zero-I/O contract crate: shared provider/tool traits, ModelRequest, messages and events, role profiles, scopes, serialized schemas, and value types. Pure agent policy is excluded unless another independent layer shares the contract. ADR-0057 |
neenee-persistence |
The local coding-agent persistence layer: event-sourced session, blob store, config, paths, embedding index, advisory locks, telemetry. ADR-0005, ADR-0076 |
neenee-transport |
The transport layer between orchestration and frontends: SessionDriver request loop, chat/permission/provider/session/slash handlers, the /serve hot-attach WebSocket bridge, /btw side sessions, MCP runtime ownership, hooks. Application-neutral. ADR-0037, ADR-0076 |
neenee-llm-client |
The multi-protocol HTTP client: pooled transport (Client, Endpoint, SSE, retry/error) plus one module per wire protocol (OpenAI chat-completions + Responses, Anthropic Messages, Google native). Crate layering |
neenee-providers |
The channel registry and build_provider_for_channel factory, plus model-list discovery, the mock provider, and the oauth module (OAuth2 credential acquisition: PKCE S256, the RFC 8628 device-code grant, the ChatGPT JSON device variant, browser loopback OAuth, single-flight refresh, and the on-disk auth.toml token store); selects which backend, with neenee-llm-client knowing how. API-key auth is not here — it is config resolution in neenee-persistence. Crate layering, ADR-0052 |
neenee-skills |
Skill metadata, discovery, remote caching, registry, refresh, and skill tool adapters. Agent consumes it for optional model-context injection. ADR-0060 |
neenee-agent |
The orchestration layer; primary export is the Agent struct. Owns turn behavior and agent-specific policy, consumes built-in tools and optional skills through downward dependencies, and accepts connector tools through DynamicToolSink. Also owns the MCP runtime (mcp module): stdio JSON-RPC transport, server processes, tool adapters, live runtime, and refresh catalog — Session holds runtime instances; Agent sees only dynamically published tools. ADR-0060 |
SessionDriver |
The server-side owner of one live session's request receiver, runtime state, and dispatch loop; external clients interact through a SessionHandle. Crate layering |
neenee-cli |
The package producing the neenee command; contains the TUI and the CLI verbs (serve / attach / status). Every invocation is a client of the unified session daemon — there is no in-process standalone session (ADR-0096). The coding application's interactive frontend. ADR-0075, ADR-0080, ADR-0096 |
neenee-server |
The unified session-daemon binary: owns every session across every project and serves them over the control plane (UDS by default, TCP + bearer token when exposed). Run by neenee serve / --detach. ADR-0096 |
| attach mode | neenee attach [session-id]: the TUI driving a daemon-held session as a control-plane client; the default mode for every interactive session (ADR-0096). ADR-0081, ADR-0096 |
| session daemon | The single user-level process (neenee-server) that owns all sessions across all projects, started on demand or via neenee serve. ADR-0096 |
| control plane | The daemon's read/write session-management API: the Monitor observability stream plus the control verbs (create_session / send_prompt / interrupt / resolve_permission / kill_session), served over UDS by default and TCP + token when exposed. ADR-0096, Server WebSocket API |
/dashboard |
The TUI session dashboard: a first-class, full-screen live view over every daemon session — a console region (the selected session's live monitor read-out) over a sessions dock; Enter previews, a attaches via detach + attach (never killing running work), and i / p / n interrupt / prompt / create. /host is a hidden alias. ADR-0096, ADR-0097 |
Agent |
The central type in neenee-agent; owns the round/turn loop, gates, permission broker, and operation scope. ADR-0005 |
| strict layering | An acyclic dependency rule: shared contracts point toward core, concrete implementations point only downward, orchestration may consume implementations, and session/application layers never acquire reverse edges. Crate layering |
| MCP server | A local stdio MCP server exposing dynamically discovered tools; surfaces as mcp__<server>__<tool>. MCP servers |
Terms superseded by the decisions above, retained for reading older documentation and ADRs.
| Term | Superseded by | Reference |
|---|---|---|
neenee-app |
neenee-persistence |
ADR-0005, ADR-0076 |
neenee-cli (pre-ADR-0035 cli crate) |
neenee-code, then neenee; the name is current again since ADR-0080 |
ADR-0035, ADR-0075, ADR-0080 |
neenee-code |
neenee, then neenee-cli |
ADR-0075, ADR-0080 |
neenee-server (ADR-0037 server library) |
neenee-session, then neenee-transport; the name now denotes the ADR-0081 headless binary |
ADR-0037, ADR-0076, ADR-0081 |
neenee-session |
neenee-transport |
ADR-0076 |
neenee-store |
neenee-persistence |
ADR-0076 |
neenee-auth |
neenee-oauth, then merged into neenee-providers (oauth module) |
ADR-0077 |
neenee-oauth |
neenee-providers (oauth module) |
Crate layering |
session mirroring (Mirror / MirrorUpdate, SessionHosting::Mirrored) |
removed — unified daemon ownership (ADR-0096) makes standalone sessions obsolete | ADR-0095, ADR-0096 |
neenee-harness |
neenee-agent |
ADR-0005 |
neenee-tui-view |
merged into neenee-cli (crate::tui modules) |
ADR-0079 |
/goal + /loop |
removed (/pursue removed in ADR-0082; /repeat kept) |
ADR-0082 |
[NEENEE_GOAL_COMPLETE] |
removed (marker gone with the pursuit stop-gate) | ADR-0082 |
| Plan mode | plan-as-an-envoy | ADR-0027 |
| per-plan progress panel | unified todo list | ADR-0020 |
plan / verify_plan_execution tools |
removed (planning is prompt-level) | ADR-0033 |
PLAN / VERIFY profiles |
removed | ADR-0033 |
| verify-nudge / todo-continuation nudge | Stop hooks |
ADR-0033 |
| stall detector | session-review diagnostic | ADR-0009 |
PromptChannel / PromptSection / PromptRegistry / PromptContext |
specialized SystemPrompt* vocabulary plus model-context message constructors |
ADR-0056 |
- Rounds and turns — the two-layer execution model
- Harness architecture — the control plane
- ADR-0005 — the crate topology and naming