Skip to content
Chapter 4 · How it works 4-9

Ru domain language

Ru is a native Windows coding agent. This glossary owns definitions and authority boundaries; component pages own implementation details, limits and lifecycle ordering.

Distribution and setup: Windows packages. Architecture and ownership: system overview.

Language

Project Memory: An optional, bounded workspace-owned index at .ru/memory/MEMORY.md, re-read as historical runtime context across conversations in the same workspace. It grants no authority and is not current filesystem or verification evidence. Implementation: project memory. Avoid: automatic memory curation, cross-workspace authority

File Preview: Read-only desktop presentation of a workspace file selected by the user. Local renderers or installed Windows document preview handlers own its display; this surface adds no model tool, execution permission or document-upload service. Implementation: GUI file preview. Avoid: document editor, model execution authority, cloud Office viewer

Public Host: The authenticated loopback ASP.NET Core process that owns orchestration, persistence, in-process model generation and composition of the execution authority. Implementation: host. Avoid: Edge, proxy, FastAPI backend

Generation Kernel: The module owning pinned provider selection, request projection, generation and cancellation for a model step. Implementation: providers. Avoid: ModelRunner globals, backend core

Public Contract: The canonical authenticated HTTP/SSE routes declared in backend-dotnet/public-route-contract.json, shared by Desktop, CLI and the stdio bridge. No WebSocket or second chat-generation transport exists. Implementation: host. Avoid: Compatibility routes

Agent Session: A session scope for presets, permissions, grants and skill use. Its preset does not grant workspace trust. Implementation: broker. Avoid: permanent Agent mode permission or preset-implied trust

Conversation Session: The Host-owned conversation and message/source history. A view may detach or switch sessions without cancelling Host work; only a confirmed application-level delete removes its artifacts. Implementation: gui. Avoid: treating an HTTP 200 response as a successful delete

Chat Session Engine: The CLI's single conversation controller for submission admission, bounded prompt history, queueing, turn cancellation and inspection lifetime. Terminal.Gui and line/JSON I/O bind to this same controller. It consumes the Public Contract; model generation, durable conversation storage and execution authority remain Host/Broker responsibilities. Implementation: shared chat controller. Avoid: second model engine, client-side execution authority, separate classic chat loop

TUI Session Tab: A retained presentation/runtime for one Conversation Session in the current terminal workspace. Its draft, queue and run ownership survive view switching; closing an idle tab does not delete the conversation or transfer permissions. Implementation: concurrent session tabs. Avoid: extra execution authority, automatic worktree, inherited grants

Run Provider Intent: The provider identifier and model captured by an explicit run submission and stored atomically with that run. It fixes the initial selection even if shared defaults change before provider snapshot resolution. It contains no credentials and confers no tool permission; the full resolved provider pin remains immutable. Implementation: GUI submission · TUI admission.

Provider Key Status: What the Host last learned about one stored provider key: verified, unchecked or rejected, with when. A checked key save or a run's model step sets it, only for the key and endpoint actually used; it holds nothing derived from the key and grants nothing. It informs the user and never selects, blocks or substitutes a provider. Implementation: key status. Avoid: key validity guarantee, fallback signal

Conversation Branch: A new conversation identity copied from a selected whole-turn prefix. The source conversation remains intact. Branches use current workspace files and do not inherit execution grants, approvals, active runs or workflow authority. Implementation: TUI history. Avoid: file checkpoint, Git branch, restored execution state

Conversation History: Retained, ordered message rows belonging to one Conversation Session. Source receipts preserve delivery idempotency even after a rewind removes visible rows. Bounded model/UI windows do not define retention. A history cursor binds its session and rewind epoch; an append preserves older-page navigation. Implementation: Harness persistence. Avoid: treating the newest display window as complete durable history

Session Work State: A bounded encrypted workflow record for one conversation and canonical workspace identity, linking intent, tasks and receipt-backed observations. It supplies context, never authority or proof of current file state. Explicit imperative constraints retain provenance; model-facing intent follows visible history after rewind. Implementation: harness. Avoid: global memory, cross-session authority, model prose as proof, or work state as permission

Session Run Handoff: A bounded encrypted snapshot of earlier model-visible root-run evidence in the same conversation/workspace, eligible only while its user messages remain visible. Its size is a tenth of the pinned model's published window (16,000 characters when the window is assumed). Historical calls are quoted context, never replayed execution or inherited approval. Applicable checkpoints and separate Host-authored directory hints preserve continuity; quoted model text cannot create those private hints. Implementation: harness. Avoid: complete memory, cross-session history, inherited approvals, automatic re-execution of unfinished calls

Native Continuation: A new root run under the same pinned provider, model, account, tool set and preset reads the session's newest visible terminal root run as native history: its closed calls, receipts and summaries, with an unsettled tail replaced by a Host note. It continues exactly one predecessor, never a chain, and inherits no approval or verification evidence. Implementation: harness; decision: ADR 0049. Avoid: resuming the stopped run, synthesized receipts, cross-model native history

RuAgentBroker: The in-process execution authority class library composed as BrokerExecutionRuntime behind IToolGatewayFactory. It validates policy and executes bounded tools without a public transport. Implementation: broker. Avoid: public API route, unrestricted shell, separate broker process

Context Checkpoint: A bounded, encrypted summary replacing selected model-context history while preserving its covered ranges and original durable evidence. Provider-backed checkpoints use the run's pinned model and consume a model-call budget; they never transfer approvals or turn quoted instructions into execution authority. Implementation: context management. Avoid: complete memory, verified success inferred from model prose, inherited approval

Execution Authority: The single path through IToolGateway to BrokerExecutionRuntime that can perform model-visible file, terminal and network actions. Host orchestration intercepts ask_user and advisor without dispatching them to that authority. Implementation: broker. Avoid: dual execution paths, HarnessToolGateway

Tool Manifest: The versioned, digested declaration of executable Broker bindings. Identity or digest mismatch refuses authority initialization. Implementation: broker. Avoid: dynamically constructed tool ID

Tool Definition: The Protocol-owned model-visible schema and metadata for one tool. Advertisement does not grant execution permission. Implementation: broker. Avoid: treating a Broker manifest or adapter list as the model contract

Tool Descriptor: The one explicit row per model-visible tool in the Protocol descriptor table. Its Protocol definition, Broker manifest, trusted adapter, session scopes and access class all derive from that row (ADR 0038). Implementation: broker. Avoid: hand-maintained tool lists, name-based scope or access defaults

Tool Profile: The run-pinned selection of Protocol tool definitions shown to the model. Supported profiles select simple file/Windows-terminal operations, unified patches or bounded programs. Persisted provider selections require an explicit supported pin; retired surfaces are not executable. This does not select an execution authority or grant permission. See ADR 0029.

Program Invocation: A run-bound run_code invocation in the experimental coding profile. Pure computation selects data; every nested coding tool still uses Broker authority. Its durable intent/receipt journal is keyed by run and invocation, and an intent without a receipt remains uncertain. This is not a child agent or a permission grant. See ADR 0028.

Tool Output Projection: The bounded, paged representation of a durable tool result supplied to model context and clients. Presentation excerpts preserve receipt provenance without claiming to contain the complete result. Implementation: harness. Avoid: treating projected output as a new receipt, complete history, or authority

MCP Server: A Model Context Protocol server the user declares in their own ~/.ru/mcp.json, reached through the single mcp tool. The Broker owns stdio processes or explicit Streamable HTTP connections. Connecting or calling tools retains the ExternalTerminal policy decision; server output is untrusted and grants nothing. Implementation: agent tools, ADR 0025. Avoid: workspace-declared servers, a per-server tool definition, or a second execution authority

Computer Use: The opt-in computer tool through which a run that pinned _ru_computer_use_v1 sees monitors, reads the visible UI elements of granted apps and sends pointer and keyboard input as the current Windows user. Terminal scripts that drive the desktop bypass its checks, so it is the only supported path. One run controls the desktop at a time; Ctrl+Alt+Backspace (or Ctrl+Alt+Pause) stops it. plan denies it, and Ru's own windows, terminal hosts and credential UI are never targets in any preset. Implementation: agent tools, ADR 0031. Avoid: unmasked screenshots in standard, input to Ru's own windows, or treating a grant as confinement

App Grant: The Broker session's record that the user approved computer use for an application, by executable file name, through request_access. It lasts for the Agent session, gates every input target and screenshot pixel in standard, and never covers a protected application. Implementation: ADR 0031. Avoid: a durable grant, a grant by window title, or a grant implied by full_access for protected apps

Provider Web Search: The model provider's own hosted web search, used instead of the Broker's web_search by a root run that pinned _ru_provider_web_search_v1 on first-party Anthropic or OpenAI and whose policy allows web_search without an approval. The provider runs the query and bills it to the user's account; answers that cite results end with a Sources list. Implementation: agent tools, ADR 0033. Avoid: calling it a Broker tool, using it where a rule asks for web_search approval, or routing web_fetch through the provider

Subagent: A delegated internal run owned and controlled by the main agent, with bounded family resources and isolated child-private history. Users can observe/export it; only the main agent sends work, cancels or applies results. Implementation: harness. Avoid: a new execution authority, a user conversation, or an OS sandbox

Evolution Run (proposed, not implemented): An ordinary standard run, off by default, that works in a private worktree of one user-named Ru source checkout and ends in an Evolution Candidate: a local evolve/<id> branch with an evidence report. A deterministic scope guard and a receipt-based fitness gate decide whether the candidate is kept; the owner reviews and merges it. It never merges, pushes, updates an installed product or writes the checkout's working tree. Implementation: ADR 0046. Avoid: a new execution authority, self-updating binaries, a benchmark score as proof of improvement, automatic merge

Advisor: A second provider/model the user selects for one session with /advisor in the TUI or the desktop composer (a new session has none) and the session's new root runs pin as _ru_advisor_v1 (or as unavailable, or as none selected). The user may instead name a model or effort in their request, which the main model relays. The main model calls the Host-intercepted advisor tool when it chooses, and the Host recommends a consultation once before a root run finishes, never making one itself; the Host sends the run's quoted active context, without provider-native blocks or images, to that model in one tool-less request and returns the advice as an ordinary tool result. Advice is untrusted input and grants nothing; children never consult. Implementation: agent tools, ADR 0047. Avoid: a Broker tool, a fallback model, verification evidence, or an approval source

Markdown Skill: A discovered SKILL.md package identified by its canonical directory ID, with metadata advertised separately from its on-demand workflow body. Explicit chat invocation captures a bounded, versioned workflow snapshot for that run; successful skill receipts can restore the same snapshot after compaction or restart. Metadata and referenced files never grant execution authority or run automatically. Built-in skills ship with Ru in skills-builtin next to the Host and have the lowest precedence, below plugin skills. Implementation: harness. Avoid: treating SKILL.md as a permission manifest or executable plugin

User Plugin: A folder with a strict ru-plugin.json in ~/.ru/plugins or %LOCALAPPDATA%\Ru\plugins that bundles skills and an AGENTS.md (and, behind a consent digest, hooks and MCP servers). It is off until the user enables it; enabled plugins have the lowest precedence after the user's own files and apply to new runs. Plugins are user-level only and never grant permission. A plugin draft the agent writes in the workspace becomes a User Plugin only when the user imports it, switched off and unapproved. Implementation: ADR 0044. Avoid: project plugins, a plugin enabling itself, plugin content as execution authority

Session Grant: A Broker-checked set of scopes and skill identities bound to one Agent Session, without arbitrary filesystem, network or credential authority. Implementation: broker. Avoid: global allowlist

Capability Profile: The session-scoped preset projected from the immutable Protocol policy catalog. plan is read-only, standard uses scoped launch/path authority, and full_access allows structured protected paths as ordinary targets; explicit rules and hard-invalid denials still apply. Implementation: broker. Avoid: permission inferred from prompt text, repository cleanliness, or a client-local preset table

Native Tool Batch: An ordered group of native calls from one model step, with optional narration. Retained approval/input work resumes the original batch through re-evaluation, never a replacement model proposal. Implementation: harness. Avoid: one-call-per-step rule, reissuing approved calls

Recovery Note: Durable bounded feedback asking the same pinned model to recover from an eligible failed or incomplete step, or to revisit a final reply held for an outstanding declared check (up to three times), for an unverified source edit, for open checklist items or for a requirements review (the last three once each). It cannot soften an approval decision, reconciliation requirement or execution-policy denial. Implementation: harness. Avoid: fallback answer, substitute model, retry on another backend

Receipt-backed Verification: An advisory projection of original run-local terminal proposals and execution receipts (ADR 0039). It rebuilds declared checks and their latest results after compaction and restart, holds final replies for outstanding checks, and never grants or denies execution. Only structured source edits make a declared check owe a new answer. Terminal commands and computer input do not invalidate checks, and the workspace change journal is not read. Intent metadata grants no authority and does not prove complete correctness. Implementation: harness. Avoid: treating a successful inspection, summary or model claim as a passed check

Declared Check: A terminal purpose=verification required check, or a purpose=expected_failure negative test with its exact expected exit code. Other process failures are diagnostics. The identity is the authority-derived canonical identity when the receipt carries one. Implementation: harness. Avoid: required check for inspection output, passed command as proof

Outstanding Check: A declared check whose latest result is failed or pending, including an expected-exit mismatch. Only the same identity passing later retires it. supersedes retires nothing. Implementation: harness. Avoid: stale check, superseded check, retired obligation

Verification State: The summary label verified, unverified or not_applicable. verified needs a declared check that ran after the last structured source edit and no outstanding check. Otherwise the label is unverified, including a run that completes after its holds are spent. Implementation: harness. Avoid: certified completion, verified success inferred from prose

Repeated Tool Recovery: A bounded repetition guard suppressing duplicate dispatch and asking the same model to change its proposal. It cannot turn a failed receipt into successful verification. Implementation: harness. Avoid: treating suppressed calls as executed or verified

Agent Persona Source: The selected workspace/user instruction sources governing conversational style and workflow. Instructions remain untrusted for execution policy. Implementation: harness. Avoid: embedded fallback persona

Approval Token: A short-lived single-use authorization bound to exact canonical arguments and policy identity. Retained proposals are re-evaluated before execution; a token never transfers to a new request or run. A deny issues no token: it settles only the asked call with an approval_denied receipt, and the run resumes (ADR 0048). Implementation: broker. Avoid: reusable confirmation flag or approval-time reissue

Session Approval Memory: A bounded in-process ledger of approved intent for one Agent Session. It remains subject to Broker evaluation and protected-path policy and expires on session/Host lifetime boundaries. Implementation: broker. Avoid: global approval cache, persisted permission

Remembered Approval: The reusable scope one approval may grant, decided by the Broker from the approved call's own identity: the exact target for the Agent session on an allow, or a project allow rule for allow_always. An outside folder is covered by the session folder grant instead of a session entry. Only allowlisted tool classes qualify, and an identity-less allow never authorizes a process-identity tool. Implementation: broker. Avoid: Host-derived matchers, broad tool-family allows, one-time approvals stored as rules

Run Provider Selection: The durable secret-free provider/model/protocol and request-option pin for one run. Reopening retains that choice; user selection changes apply to a new run. Implementation: providers. Avoid: current settings as restart fallback

Provider Continuation: Encrypted internal provider-native state bound to an exact run, model step and native call batch. It is excluded from visible history, clients, portable handoffs and telemetry. The only reader outside its run is a Native Continuation of that run, under the same provider, model and account, which replays it to the provider that produced it. Implementation: providers. Avoid: hidden reasoning in chat history or reconstructed prose

Responses Assistant Phase: The provider's public per-message distinction between commentary and final_answer, with null retaining ordinary assistant-message semantics. Retained native history preserves this metadata; commentary alone does not complete an Agent Run. Private reasoning remains in Provider Continuation. Implementation: providers. Avoid: treating progress text as a final answer or adding phase to user messages

Runtime Context Snapshot: A bounded, encrypted model-only record of current runtime and workflow context, admitted before a prepared native text model step. Retained snapshots stay durable at their historical position. A superseded snapshot is dropped from a request only when a newer one replaced it after at most one model step; one that stayed current longer keeps its position so the cached request prefix holds. New or cleared state is appended and never grants authority. Implementation: providers. Avoid: mutable context rewritten ahead of retained history or historical observations treated as current permissions

Policy Snapshot: An immutable versioned canonical binding of preset, workspace identity and ordered rules, validated by the execution authority. A new version invalidates stale pending decisions. Implementation: broker. Avoid: mutable rule set

Policy Rule: A scoped allow/ask/deny record with stable identity, canonical matcher and ordering. Sensitive matcher values are encrypted at rest; repository instructions do not create rules. Implementation: broker. Avoid: repository-stored authority

Scratch Workspace: A Ru-owned workspace under the Ru data root for a chat that never chose a project folder. Ownership requires a matching session marker and canonical path to the non-reparse session directory; path shape alone does not establish ownership. It is ordinary workspace territory for trust, policy and tools; the GUI places its chats in Recents unless the user explicitly changes sidebar placement. It is deleted after successful or confirmed-absent session deletion and reclaimed by a startup sweeper. Implementation: host, ADR 0041. Avoid: install directory or drive root as a default workspace, project-derived authority

Workspace Trust: An explicit decision bound to the canonical Windows directory identity, independent of preset or repository cleanliness. Recreated or moved identities require fresh trust. Implementation: broker. Avoid: repository-marker, path-only, or preset-implied trust

Workspace Terminal: A policy-authorized executable or shell launched under the current Windows user, bounded by timeout, output, cancellation and process-tree cleanup. Launch-directory permission is not OS filesystem/network confinement. Implementation: broker. Avoid: treating repository cleanliness as authorization or terminal approvals as OS confinement

Run Event Feed: The shared client subscription and reconnect path for durable SSE events and transient frames. Only durable IDs advance the resume cursor, and consumer failures remain observable. Implementation: host. Avoid: replaying transient frames as durable history or hiding callback errors

Session Side Surface: The GUI session summary and detail surfaces for edit history, processes, subagents and a user-owned terminal. Presentation state never changes workspace identity or execution permission. Implementation: gui. Avoid: treating the background-task list as the agent's todo plan

Turn Change Summary: The read-only card beneath a settled assistant turn, grouping its completed edit activities by recorded file path. Line totals sum recorded edits rather than a net Git diff. The reader preserves each edit's before/after preview; missing evidence remains unavailable. It never modifies files or grants authority. Implementation: GUI turn summary. Avoid: mixing session-wide edits or current filesystem content into an older turn.

Multimodal Image Payload: A validated bounded client image persisted encrypted for authenticated-client and model-context audiences. A vision-capable pinned model receives image content; a text-only model receives an explicit notice that the attached image contents are unavailable, so the conversation can continue without dropping the stored attachment. Implementation: host. Avoid: Unbounded base64 uploads, client-side raw file passthrough

Staged Attachment: A copy of a file the user attached from outside the workspace, made by the client in <workspace>\.ru\attachments so the model opens it by workspace path with the ordinary file tools. It is the user's own action on their workspace and grants the agent nothing: Broker path rules and presets are unchanged. The folder ignores itself in git, a copy is bounded, removed with its pending attachment, and pruned after 14 days. Implementation: GUI, TUI, ADR 0053. Avoid: Widening read access to a folder outside the workspace, inlining binary bytes, editing the user's .gitignore

Tool Image: A workspace PNG, JPEG or WebP image that read returned beside its JSON metadata, persisted encrypted for the model-context audience only and attached to its tool result in later requests of the same run. Only a run whose pinned model accepts image input receives one; otherwise the read fails by name. Implementation: host, ADR 0026. Avoid: Returning image bytes as text, server-side resizing, silently dropping an image from a request

Core TUI: The compact Terminal.Gui coding surface for chat, tool activity, approvals, session/model selection and recovery. Headless CLI/RPC capabilities are independent of its presentation scope. Implementation: tui. Avoid: Requiring GUI feature parity or treating presentation metadata as authority.

Protected User Data: Settings, conversation history, activity, credentials and other active product records. Generated-output cleanup never authorizes removing these records. Implementation: host. Avoid: Cleanup candidates, generated data