Current runtime behavior¶
Status: operating contract for the current development branch, updated 2026-10-17.
This document keeps current runtime decisions separate from implementation history. Where automated and live evidence differ, the narrower claim wins.
Conversation and generation¶
Model requests have a 120-second deadline through response headers. Expiry is
retryable provider_timeout; caller cancellation is preserved. After headers,
the existing 120-second SSE idle watchdog bounds silence, while active streams
can continue beyond the request deadline. Model transport does not follow HTTP
redirects: redirect_rejected is a non-retryable failure on the selected endpoint,
with no credential/prompt forwarding or automatic provider substitution.
The cloud-first desktop default is OpenAI. Hosted OpenAI and Anthropic
providers are the supported cloud adapters, alongside any models.dev:<provider-id>
generic provider; OpenAI-compatible custom
adapters remain available for explicitly configured external services. Ru no
longer ships or starts an in-process conversational model. Switching providers
must preserve bounded context, cancellation, streamed visible-text
normalization, and public error mapping by ASP.NET Core. Stale llama.cpp or
GGUF settings migrate to models.dev:opencode and retired opencode/kilo
choices migrate to their models.dev: equivalents (keys must be re-entered).
Cloud generation requests omit provider-specific Temperature, Top-K, and
Max New Tokens controls; legacy stored values are ignored and stripped rather
than forwarded to a provider.
Provider models and verified reasoning options come from the Host-owned
catalog, refreshed by the GUI while Chat is active. The Chat picker renders
all non-empty provider catalogs in one stable grouped list with global
provider/model search; one selection saves a strict two-field payload through
the existing atomic /settings transition. Failed catalog groups stay
isolated, stale same-identity data is labeled, and a selected model that is no
longer available is never replaced. Provider default omits reasoning
overrides; invalid explicit choices or unsupported model protocols stop new
model requests without an API/model/effort fallback. See
provider catalogs for refresh and capability boundaries.
Ru mirrors Vietnamese, English, and mixed-language turns. In Vietnamese Ru
calls the user anh and itself em. Agent replies contain no Unicode emoji or ASCII
emoticons. Search commands, model controls, segment
identifiers, and transport timings are private metadata and must be removed
before display, history, logs, or reviewed examples.
Each Agent turn carries a bounded correlation_id and a durable run/session
identity. The composer keeps one active run; reconnecting to the Agent SSE
stream replays only durable events and never duplicates a committed history
entry. Stale or malformed events are ignored by the presenter, so a late reply
cannot update a newer bubble. A disconnect marks the active run as a bounded
retryable connection error. Run creation makes at most two attempts on the
same endpoint, each with a 15-second deadline, using the identical serialized
request and idempotency key. Cancellation before dispatch prevents creation;
after dispatch the bounded acknowledgement path still observes a late run so
the client can cancel it. Exhaustion reports agent_create_outcome_unknown.
WinUI retains the request identity, blocks overlapping creation and offers
Stop to replay that same request before cancelling the acknowledged run.
A failed Stop reconciliation retains the identity for another attempt.
An unusable success response, a server error, or an HTTP error after a lost
acknowledgement also retains that identity, while preserving its original
error code. A definitive first-attempt client error does not trigger this
unknown-outcome state.
Opening a session adopts its newest non-terminal run, so a run that outlived
the host is not invisible: WinUI re-arms Stop for it (AdoptRunAsync; a running
run is subscribed from its durable LastSequence), the TUI adopts it when
chat --session reopens the session (typed Continue reopens a running,
approval-waiting or question-waiting run in that chat, or ru agent attach <run-id>
attaches from another terminal), and switching sessions detaches a waiting run
instead of cancelling it. In-chat reopening rejects foreign-session runs.
There is no Continue gate (ADR 0048). A run only waits on the user for an approval,
an ask_user answer or workspace trust; every other stop ends the run with its named
code, and a new message starts a fresh run that carries the session's handoff
(ADR 0023), or the previous run's native history when the model is unchanged
(ADR 0049). Startup recovery fails a run an older build parked for Continue with the
code it parked on (continue_removed when none was recorded).
Startup recovery compares the durable event stream with dispatch boundaries: a
crash before any dispatch fails the run as recovery_pre_dispatch, an incomplete
read-only execution as recovery_read_only_incomplete, an ambiguous
side-effecting execution parks it for reconciliation, and a model step that
started but never completed — the host stopped while the provider was
generating — fails as recovery_model_step_incomplete. That last reply was
never committed, so resuming it would silently open a second step on every
restart and keep the session's active-run ownership; failing it by name releases
the session for a fresh prompt.
The runtime polls the conversation outbox and registered runs independently of
long model/tool work. A new registration, a successful client POST to a run
(trust, approval, answer, cancel) and a drive pass that changed the run
wake the loop at once; polling (250 ms while a run can progress, one second when
none is registered or every run waits for a client) is the fallback. A run parked
on an approval is not rebuilt while it waits; only expiry is checked until its
version changes. Every registered run gets its own worker at once; model calls are
unbounded unless RU_MAX_CONCURRENT_MODEL_STEPS sets a cap. Session deletion cancels its owned worker, and host
shutdown waits for workers to unwind.
A live SSE stream re-reads the run every 100 ms while it can progress and every
second while it waits for a client; the client POST that answers it signals the
stream directly. A mid-stream server failure closes the response cleanly and is
logged with the run id.
When an SSE poll finds that the durable run row was deleted, the response closes
cleanly and releases its live subscription. It emits no fabricated terminal
snapshot; subsequent run reads/reconnects receive the existing not-found response.
Token usage accounting¶
Opening Ru does not call a model, so startup alone has no provider token usage.
For an actual model step, adapters preserve provider-reported input, output,
total, cache-read, and cache-write counts through the typed model step
result. The Host persists those counts as a ModelUsage payload with a
model.usage_recorded event for every model step, final reply and tool turn alike
(tool turns also keep the copy inside their AssistantStep), so live context meters
and run billing see each request rather than only the last one. The payload is a
sidecar record for authenticated telemetry consumers; the current chat bubble
fetches it from the durable model.usage_recorded event and renders the
reported counts below the assistant text. A missing usage
object means the provider did not report counts; it is not converted to zero.
Numeric zero remains an exact provider value. estimated_input_tokens is kept
for backward compatibility and remains an estimate, not a billing record.
New usage records also identify whether input includes cache reads/writes through
optional input_tokens_include_cache: Chat Completions/Responses are inclusive;
Messages reports disjoint buckets. DeepSeek Chat hit/miss fields are recognized
alongside OpenAI-style cached-token details; contradictory counts are rejected.
Legacy records remain readable without inventing an accounting mode. Cached
legacy reports with unknown accounting are not assigned a guessed price.
The session usage panel covers the newest eight runs and says so. It sums distinct durable usage reports within each covered run, including paid steps of running or parked runs, while the context peak remains the largest individual step. At most 4,096 usage payload references per run and four concurrent payload reads are used; a failed read makes that run unavailable rather than a cheaper partial total. The chat context meter still uses the latest step, not the run's token sum. Cache hit is cache-read input divided by total prompt input, weighted by tokens and excluding output; coverage names the runs with identified accounting and reported cache counts. Missing counts remain unknown and a partial hit is never rounded up to a claimed 100%.
Agent generation runs inside the Public Host process through the typed
ModelStepService behind IModelStepRunner; the device v1
runtime/voice/STT/VTS/observation protocol was removed with the media surfaces,
and the managed C# worker process, its loopback port, and its wire protocol
were retired (ADR-0012). No model step crosses a process boundary, and no
per-step credential handoff is written to disk. The credential store keeps
its existing protected-at-rest ownership.
Managed startup starts no child process: tool execution runs in process
through BrokerExecutionRuntime behind IToolGatewayFactory (ADR-0014), and
the retired Broker child, its loopback lease and RuAgentBroker.exe are gone.
Each Agent
step resolves the run's cached in-memory provider snapshot from a secret-free
durable Run Provider Selection. Restart rebuilds the snapshot from that same
selection and credential account; legacy runs without it fail closed. The
bounded protocol
(chat_completions/openai_responses/anthropic_messages), verified native
reasoning options, and for Anthropic the bounded max_tokens; changes to
settings apply to the next run, not a continuation of the active run.
The step dispatches exactly the pinned protocol through one of three focused
adapters; unknown or mismatched protocols fail closed before HTTP. Managed startup is unconditional.
Agent system-prompt composition¶
Every accepted Agent model step—typed text, coding, native tool selection, and
continuation—rebuilds a fresh prompt context before the model step. The
private Generation Kernel emits exactly one system message with composer
2.0.0 from seven ordered blocks: neutral Ru Agent runtime contract, Agent
execution contract, environment, profile plus canonical effective policy,
root-selected instruction blocks, validated host capabilities, and bounded
runtime context. The model then receives ordered typed user/assistant/tool
messages; clock, mood, and references are not appended as separate system
messages.
Host capabilities are the runtime projection of the Protocol-owned tool
definitions selected by the run-pinned coding_v3 or coding_v2
profile. File tools use explicit identities such as write_file/edit_file;
terminal tools are powershell, run_process, terminal_read, terminal_stop.
See the tool inventory.
ask_user is Host-intercepted. ask_user never dispatches to the Broker: it parks the run in
WaitingUser with a durable input.requested event until the client posts the
answer, which arrives as that call's durable tool result. The execution contract
also states that the run's current permission mode is described only by the
profile block: documentation, workspace files, and skills describe the product
and never the run's own mode, so a model cannot mistake a mode described in
CONTEXT.md for the mode it is in. On provider-native
paths, one generation may return optional narration and one or more ordered
calls. The Host persists the assistant batch and matching durable tool results;
it does not flatten native calls into prose. Responses assistant message phases survive native replay: commentary is
progress rather than a completed answer. A commentary-only response continues
with bounded recovery, and final_answer can finish normally. A call written out
as text is salvaged into a native call when it names an advertised tool. The model makes no success claim before durable
results. If a batch asks, no call executes; after approval the runtime
re-evaluates the retained durable proposals without a new model proposal.
Read-only calls may overlap up to eight at a time while mutation/terminal
barriers and receipt order remain intact. Oversized outputs are clamped while
untrusted references retain the bounded high-fidelity context. Unknown,
duplicate, malformed, or digest-mismatched contracts fail before provider
execution; wire and invariant violations remain terminal.
The Host reads the fixed AGENTS.md, CONTEXT.md, .ru/AGENTS.md, and
.ru/CONTEXT.md candidates below the selected run root. AGENTS.md is loaded
as workflow guidance; each CONTEXT.md body is represented by a short relative
path and normalized content hash, with relevant sections read on demand.
The optional user-wide ~/.ru/AGENTS.md comes first, so workspace instructions
take precedence. Skill directories follow the shared RuAgent.Protocol.SkillRoots
order: <workspace-root>/skills, <workspace-root>/.ru/skills,
<workspace-root>/.agents/skills, RU_SKILLS_ROOT when set, ~/.ru/skills, ~/.agents/skills, and
%LOCALAPPDATA%\Ru\skills. A directory is a skill
only when it contains a case-insensitive SKILL.md. For example:
---
name: pdf-analyzer
description: Analyze and summarize PDF files
allowed-tools: read, bash
---
# PDF Analyzer
Describe the review workflow here.
The loader applies final-path containment, strict UTF-8 decoding,
NFC/newline normalization, a 64 KiB per-file limit, and a 256 KiB combined
instruction limit. It re-reads those roots for every newly built prompt
context, so copying or changing SKILL.md is picked up on a new run or after
restart without a downloader or package manager. Ancillary references/,
assets/, and scripts/ files are ignored by discovery and are not
automatically read or executed. Context values remain bounded (128 KiB per
reference and 8 MiB serialized context). Successful structured file operations
also discover bounded nested AGENTS.md guidance, refreshed in runtime context
with an explicit scope and precedence. Receipt-derived private scope hints survive
compaction and restart independently of native text caching, including image
requests. Existing files nearest to touched paths receive priority
under the instruction-count bound. Root-selected
instructions and skills are followed only as guidance; they cannot
grant tools, permissions, approvals, paths, network access, or preset changes.
The allowed-tools field is descriptive only; the optional requires: field is enforced on every body load — the model's skill tool and the Host's /skill command (only python is recognized: absent Python fails closed with python_unavailable). Runtime
references and tool/search results remain explicitly untrusted.
The Host's /skills run command lists workspace skill name + description and /skill <name>
loads one SKILL.md body as untrusted guidance; neither executes tools or grants
anything. The in-process execution authority remains the sole owner of path
canonicalization, capability policy, approvals, and tool execution.
Terminal chat omits these two slash commands; ordinary prompts can still request
skills under the existing model invocation policy.
The model step returns a typed AssistantStep(text, tool_calls, finish_reason)
together with a schema-validated, versioned prompt receipt. Core validates the
receipt against the exact context before committing model completion or
dispatching tools, then stores the receipt as an InternalOnly payload. Public
Agent SSE suppresses model.prompt_composed and its payload while advancing the
durable cursor. Invalid context or receipt metadata fails closed with
prompt_contract_invalid; there is no static-prompt fallback or
reduced-context retry. Managed runtime wiring enables the standalone
web_search/web_fetch tools by default; no settings field controls their
exposure.
Prompt composition is not a security boundary: execution-authority policy, workspace trust, approvals, protected paths, external-directory grants, and cancellation remain authoritative. Subagent orchestration, LSP, project-level plugin discovery, workspace-declared MCP servers, arbitrary system overrides, Chat compatibility, UI redesign, and OS filesystem/network confinement are outside this implementation (ADR-0015).
When Ru needs product knowledge about its own features, tools, configuration,
providers, or operating boundaries, it selects the help tool (help@1.0.0). It
searches only five explicitly embedded Markdown resources and returns bounded,
stable document IDs and excerpts. It is offline, read-only, workspace-
independent, and approval-free. Runtime context and advertised terminal tools
remain the source for live machine, process, device, and current workspace
state; bundled help is untrusted reference data and cannot change instruction
precedence.
WinUI responsive shell¶
The WinUI shell has three presentation tiers based on client width: Wide at 1280 px and above, Compact from 900 through 1279 px, and Narrow below 900 px. Every tier keeps a full sidebar resizable from 220 to 360 px; Narrow stacks page controls without switching to an icon rail. The title-bar workspace-sidebar button hides the sidebar completely and restores its last expanded width. Dragging, Ctrl+Left/Right, and the splitter's arrows/Home/End share those bounds; double-click resets it to 250 px. These transitions are presentation-only and do not call the backend, restart polling, or recreate list sources.
Automated tests cover policy boundaries, XAML state markers, vertical-only list surfaces, and build correctness. Visual resizing at representative window sizes remains a user-run acceptance check.
The current Agent composer uses the same tiers. The shell and conversation view use the
Editorial reading room presentation: the approved light mineral palette as the
baseline, a sidebar with WORKSPACES above RECENTS, collapsible folder
groups and relative timestamps, and a centered document-style reading column.
Section headings have separate container styling; their spacing sits outside
the hit area and does not inherit session-row hover or selection fills.
Sessions whose working directory is the app's default root, or has not yet
been assigned, appear under Recents rather than a folder named after the app
root. Pinned root directories do not create a duplicate workspace group.
Sessions can be dragged into Recents or a workspace, or before/after a sibling;
the More actions → Move to menu provides the same grouping and up/down ordering
without dragging. These moves change sidebar organization only: the session's
working directory, history, run metadata and permissions stay unchanged. The row
tooltip shows its actual working directory. Local placement/order preferences
are stored atomically in %LOCALAPPDATA%\Ru\sidebar-organization.json and survive
polling and app restarts; a failed save leaves the existing order intact.
Native drag previews, destination outlines, an insertion marker and short row
transitions provide feedback. Hovering a collapsed group opens it after 450 ms;
dragging near the list's top/bottom scrolls it. Cancellation clears the preview
state, and custom motion follows Windows' animation setting. Keyboard navigation,
visual drag feedback and smoothness remain native UI acceptance checks.
Workspace + and New Chat create and open a session immediately. The sidebar
shows New Session in the chosen workspace even before any messages exist;
session polling preserves this temporary row. The first accepted chat uses the
same ID and replaces the placeholder with its first prompt, then adopts the
durable server title. Switching sessions or leaving Chat before sending hides
the empty draft, as does restarting the app. This is a UI visibility rule:
empty Host records are retained, and unrelated empty sessions stay hidden.
Log, Diagnostics, and Settings retain their existing layout
in this phase while inheriting the active shared Light or Dark token set.
The application keeps Light as its fallback and MainWindow can request the
active theme on the shell root so default controls follow the same contrast.
The appearance action in the sidebar footer switches Light and Dark
synchronously. The selected appearance is UI-only state stored at
%LOCALAPPDATA%\Ru\ui-preferences.json; it is not an ASP.NET setting or model
configuration. Background media, color overrides, fonts, sidebar side and corner
style from Settings > Appearance live beside it in appearance.json, with copied
background files under %LOCALAPPDATA%\Ru\backgrounds; "Reset appearance" in the
command palette restores the stock look (see docs/architecture/gui.md, Appearance
customization). Switching remains presentation-only for application behavior:
it does not recreate message or session sources, call the backend during
layout, or alter event-stream ordering. Automated source/XAML contracts and the WinUI build cover
structural correctness. Visual resizing remains a
manual acceptance check.
The current Ru signature layer is also presentation-only: a quiet title-bar
wordmark, an editorial welcome eyebrow, message edge rules, and a GPU-accelerated
Composition visual field in the empty conversation state. The background features
gentle twinkling starlight points and periodic shooting star streaks rendered directly
via Microsoft.UI.Composition (SpriteVisual, CompositionLinearGradientBrush with
soft halo glow and core beam), runs only while Messages.Count == 0, and stops and
clears every visual element as soon as the first message exists. The composer keeps the
native TextBox caret/focus behavior and exposes one bounded preset selector
(Plan / Standard / Full Access); there is no Chat mode switch or workspace editor
in the composer.
The UI uses the known project root as the initial Agent workspace and does not
expose a workspace editor, while the authenticated API still validates the
canonical path. All submissions use the authenticated /agent/v1/* API/SSE
path. Workspace trust is explicit once per canonical identity: the GUI shows a
guarded confirmation, while CLI run/chat use --trust-workspace. A moved or
recreated identity requires trust again. Windows identity resolution requires
native final-path, volume and directory file-ID evidence; an unavailable lookup
fails instead of substituting a hash of the path. Full Access requires the GUI gate or
CLI --confirm-full-access. Workspace trust, approval, Stop and
bounded Agent status remain inline above the input. Replaying a run an older build
parked, the terminal client shows ▲ run paused · <reason> with one notice
to send a new message. The reason comes from one shared
catalog (AgentParkReasonCopy): a provider transport failure reads as a network
connection failure, a timeout as an unresponsive provider, and a spent budget as
a spent window, instead of showing only the raw code. The desktop activity row
and status line resolve the same copy, so both surfaces explain a pause the same
way. While a run is active, the transcript
may also show a separate transient activity feed above the assistant content,
driven by typed agent.activity SSE frames. It renders only safe state,
basename/line-range, symbol/count,
edit-count, duration, and safe-code fields; it is cleared on terminal,
cancellation, failure, disconnect, session replacement, or reset. Activity
frames do not enter durable history or audit. The projector covers fourteen kinds
(see agent tools), including compaction (bounded covered-entry count and elapsed time) and
retry (bounded tool transport retry attempt, any access kind, at most once
per call), plus a generic
status fallback (status rows can carry a bounded plain-text detail). Agent payloads and raw tool output
never enter transport metadata or automation names.
Assistant text is delivered separately as a typed assistant.delta transient
frame. The client validates the outer kind, bounded UTF-8 text, model-step id,
optional execution id, and positive transient sequence before dispatching it;
unknown fields, malformed JSON, raw tool output, and replayed sequence keys are
dropped without changing the durable cursor.
The measured request size for a model step about to run rides a typed
agent.usage_estimate transient frame (estimated input tokens, the step's prompt
budget, model-step id, optional numeric context_tokens breakdown and optional
compaction_trigger_tokens, the preflight compaction point in the estimate's units), published before the step's first token and on the
same hub channel as activity rows so a delta burst cannot evict it. Provider usage
only arrives when a step ends, so this frame is what lets a client's context meter
move while the model is still working; the reported usage supersedes it.
A model step the host suppresses for recovery (model.step_completed with an
*_advised safe code) is audit-only, but its deltas already streamed: the
Terminal.Gui transcript drops the rows that step painted and the turn-end gap check
stands down for such a turn, so the model's re-answer cannot read as the same answer
printed twice and suppressed prose is never reprinted by the recovery.
Once the SSE feed emits final_snapshot, WinUI treats that terminal status as
authoritative if a follow-up GET races host shutdown or restart. A late
history/outbox failure after visible assistant deltas does not append a generic
failure sentence to the answer or replace it with a duplicate failure banner;
the durable run/event status remains available for diagnostics.
Stream callbacks and completion/error settlement carry the run's ownership
generation. A detached subscription cannot clear a newer run's busy state or
overwrite its terminal status, assistant deltas or tool output. History reloads
recheck session generation, run and assistant identity when the UI update executes;
turn cleanup also checks that identity after awaiting the reload. The Files tab
serializes root reads, keeps the newest requested workspace and discards superseded
results/errors, including pending folder expansions.
If the terminal snapshot races conversation-outbox delivery, a session-history
reload that still contains only the user turn preserves the already-rendered
assistant bubble. A later history refresh can reconcile it once the persisted
assistant entry is available.
Agent final replies are normalized through the metadata policy before the
authenticated payload and conversation outbox are committed; private
markers therefore never enter history or model context.
The safe assistant activity projection runs after that
commit, so a non-critical effect failure cannot roll back a completed Agent run.
Agent user/assistant activity records use the agent activity type and remain
preview-sanitized at the activity-store boundary.
When no session has been opened yet, the first Agent prompt creates a fresh
session before creating the run.
The desktop captures the submitted session ID after that creation, so an accepted
first turn clears its own composer draft. A refused submission retains the prompt
and attachments; its composer error remains visible across run-state refreshes,
even when no run exists yet.
Acceptance remains valid when the event stream finishes before the queued UI
transition runs. Session-switch teardown or a newer controller owner invalidates
that queued transition, so an older run cannot clear another session's draft.
If an Agent API call reports session_not_found or invalid_session_id, the
desktop creates one replacement session and retries once only before a run is
created. A second recovery failure is shown as a bounded error and is never
looped or filled with an earlier response.
Desktop runtime lifecycle and reconnection¶
The WinUI 3 desktop client connects to the shared local Public Host via loopback IPC.
ManagedRuBackendSessionProvider tracks the Host process lifecycle and coordinates runtime liveness:
- Liveness detection: HealthStatusService probes loopback status with a bounded 3-second timeout via CheckHealthDetailedAsync, distinguishing genuine Host offline state (HttpRequestException or connection refused) from backend startup or readiness. Stale or disconnected sessions accurately mark .NET Backend: Error.
- Exit detection: ManagedRuBackendSessionProvider hooks the Host process Exited event, clearing the active session and firing BackendExited.
- Backoff & auto-reconnect: When the backend process exits, high-frequency polling timers (catalog, sessions) are stopped to prevent UI thread socket storms. ShellViewModel then probes for backend recovery every 3 seconds, one bounded (6-second) attempt at a time, and the same retry starts when a health poll finds the Host unreachable. Once the Host is back it re-attaches or restarts the backend and reinitializes active views and controllers without requiring a GUI restart; a harness run or a closed window never reconnects.
- Single-instance activation: Multiple instances detect existing instances via process enumeration and native WinUI class queries, bringing the existing window to the foreground cleanly.
- Shutdown: Window close coordinates timer cancellation and Host shutdown without orphan processes.
Session and history lifecycle¶
Conversation history is retained as indexed message rows; GUI and CLI read bounded pages with absolute indices. Rewind invalidates older history cursors, while append preserves older-page navigation. The initial display window is not a retention policy. See database maintenance for full-history export, backup/restore and opt-in pruning.
ASP.NET Core is authoritative for persisted conversation sessions, history, and
the Harness records owned by a session. DELETE /sessions/{sessionId} keeps a
stable HTTP 200 response envelope: status: "ok" is returned only after the
deletion coordinator removes the session and its owned Harness artifacts;
missing or failed deletes return status: "error" with bounded copy.
Clients must inspect the application status instead of treating HTTP success as
proof of deletion. WinUI asks for confirmation, refreshes the sidebar only
after status: "ok", and shows a bounded error without silently replacing the
conversation when deletion fails. If the last session was deleted
successfully, the UI creates one fresh session.
Action execution kernel¶
The typed model-step settings advertise the run's supported pinned tool profile, with explicit file creation, editing, deletion/restoration and Windows terminal operations. The tool contract owns inventories, arguments and availability; old or unversioned pins cannot resume execution. The canonical permission matrix owns preset behavior, explicit-rule precedence and approval reasons. The Host projects that contract; documentation never grants the run additional authority.
Standard structured-file access outside the trusted root may create a
session-scoped canonical folder grant; it is not shared with a new
session and is lost on restart. Remembering the folder with allow_always
saves a durable project-scope path pattern instead, which survives restarts
and is reused within the same workspace identity. Neither authorizes
terminal. Full Access uses an
ephemeral structured root per external call. Terminal children in standard
and full_access run as the current Windows user without OS filesystem or
network confinement, including outside the workspace (ADR-0015). Standard
uses launch-directory permission under ADR-0017, with explicit ask/deny rules;
Full Access also permits external launch directories. The
terminal tool schemas have no sandbox selector and rejects obsolete sandbox arguments.
Hard timeout, output cap, cancellation, redaction, and process-tree cleanup
remain. Structured file tools retain their independent path protections: the
protected-path denial holds in plan and standard, and full_access is
literally full. API
keys remain in credential storage and diagnostics redact secrets.
Web is automatic in all canonical presets; web_approval_required remains only
as an explicit-rule compatibility reason.
The model selection channel is active for every Agent run: one budget window
allows up to 128 model steps and 256 model-initiated tool calls through the
Broker pipeline. Native batches may contain multiple calls; the scheduler caps
read-only concurrency at eight using a rolling pool: a completed read frees a
slot without waiting for its slowest peer. Mutations/terminal remain sequential
barriers. Receipts retain model order. An observed unknown outcome stops new
starts; every already-started read drains, including reads admitted before that
outcome was known. Cancellation or failure also drains owned work before return.
See phase timing and Host benchmarks.
A root run does not stop at a full window. It opens the next window
automatically and keeps working, and there is no window cap: a root run ends
when the model finishes, the user stops it, or a failure does — not because its
own counters ran out. The per-window counters, not a wall-clock timer, bound the
loop, and no wall-clock or cost cap exists. Internal subagent runs never take an
automatic window: their own limits fail them. A batch larger than a whole window
(tool_call_budget_exhausted) is first answered with a bounded
model_tool_batch_too_large repair note asking the model to split it. Native calls,
calls written out as text, arguments, and outputs never enter the visible transcript
as execution markup, mood state, or public diagnostics.
A dead-end model step does not end the run by default. Ordinary prose after a
failed or unverified tool receipt is suppressed and answered with a durable
[HARNESS RECOVERY] note (up to 3 notes, shared with verification holds); empty final text gets up to 3 notes,
and a runner-rejected malformed or unavailable tool call, or an unreadable call
written out as text (invalid_selection), gets up to 4.
Incomplete Length finishes get up to 3 truncation notes in a row (a later truncation after progress starts a new count). These kinds share a
cap of 24 notes within the recovery window (the last 512 durable events, about fifty steps). System recovery notes remain visible through
compaction. Feedback keeps the same model/provider; spent bounds fail with the
original code. Exact repeated calls and short failed cycles receive at most two
[REPETITION GUARD] notes, then fail as repeated_tool_call. The suppressed assistant step
is audit-only; its calls never enter native history without matching receipts.
Trailing advice does not hide the earlier receipt from repetition detection. After its
holds, a failed verification completes the run as unverified; it is never labelled verified.
A provider that is still failing after the runner's bounded retries (about twelve
minutes for provider_rate_limited, provider_timeout, provider_server_error
and provider_transport_error; never retried for provider_quota_exhausted) fails
the run with the provider's code. The same holds for context_limit_reached after
compaction and for a required checkpoint that cannot be made: the run ends with its
named code instead of waiting for a Continue.
Replaying a run an older build parked, the CLI still reads the park reason from the
committed continue.requested event (one finite live=0 replay of at most four frames
within two seconds) so its history shows why it stopped.
A provider stream that goes silent is the case behind provider_timeout: the
SSE reader resets a 120-second idle watchdog on every received chunk and
cancels a stream that sends nothing, so a provider that accepts the connection
and stalls becomes the same retryable timeout instead of holding the step until
the user cancels. The watchdog applies to all three protocols; the HTTP request
timeout itself stays infinite because a whole-request bound would cut a healthy
long generation.
A user's deny settles the asked call, not the run: the approval route commits an
approval_denied receipt for that call (never dispatched, no side effects), the run
resumes with the rest of its batch, and the model reads the denial and may change
course, ask, or simply finish. A deny is not a tool fault, so it never draws
unverified_after_tool_failure notes; Stop is how the user ends a run. An allow
decision is remembered for the session: the exact approved intent is
materialized as a run-scope allow rule into the session's later policy
snapshots, so an identical call — including later in the same run — evaluates
as allowed without another prompt. The memory is in-process, expires and is
capped per session, and dies with the session or a host restart; protected-path
denials (where the preset carries them) and Broker evaluation still decide
every call. A
repeated policy_denied tool receipt followed by prose is not an approval
decision: it may still take the bounded unverified_after_tool_failure notes,
with the denial code as the terminal code.
External-folder requests and terminal deletion or unknown-executable requests use bounded approval cards. The Public Host opens one profile-scoped execution session per turn loop, and the in-process authority executes and verifies adapters. Tool-class successes require an invoked adapter. Python does not own desktop side effects.
The Host serializes one active execution grant: a matching valid session is reused; a replacement Agent session closes the old grant before open. Failure is fail-closed and never reaches the native adapter.
Non-success tool outcomes are represented as bounded Agent activity and durable run state. Raw tool receipts never cross into the visible transcript, history, reviewed examples, or public payload metadata.
The tools above are the model surface. read, list, grep,
glob, and help are separate definitions. Modern file and terminal operations
have their own schemas, alongside todo_write, skill, web_search,
web_fetch, and the Host-intercepted ask_user. Managed startup constructs an enabled WebOptions instance with
Google HTML as the primary search engine https://www.google.com/search, raced
against the fixed free fallbacks (DuckDuckGo HTML, Bing, Mojeek); the bounded
responses carry an explicit untrusted marker and
never become instructions. grep
searches the workspace, web_search searches the public web, and help
searches only bundled Ru documentation. Unbound connectors and app.open
remain outside the model-visible catalog.
Git commands are ordinary terminal requests governed by Broker policy. The
GUI renders the actual agent.session grant received from the Host. Managed
startup enables the bounded WebOptions instance with Google HTML as its primary
search engine, so standalone web_search and web_fetch are advertised as
read-only managed capabilities without a settings flag or separate deployment
switch; Broker
policy remains authoritative for each call. MCP servers declared in the user's
~/.ru/mcp.json are reached through the mcp tool, advertised only while one is
declared (see Agent tools); the mail/calendar/task
connector libraries are not production-composed or advertised as Agent tools.
Typed commands¶
The authenticated POST /agent/v1/runs/{runId}/commands route handles
/compact normal|aggressive, /help, /skills, and
/skill <name>. AgentActionRouter is shared by Public Host and
CLI, bounds input, rejects unknown or malformed slash commands with stable
codes, and prevents command text from entering prompts, history, or the
conversation outbox. /compact uses the durable context-compaction contract;
the other commands return bounded static or session-scoped data.
Auto-compaction is tuned by two settings (compaction_trigger_ratio
default 0.80, compaction_target_ratio default 0.62); values must
satisfy 0 < target < trigger < 1 and anything else fails closed to the
defaults.
Provider-backed compaction now generates a structured checkpoint using the same
pinned provider/model, with one budgeted auxiliary call, a 60-second deadline
and at most 4,096 output tokens. A malformed, truncated or failed checkpoint
returns a named checkpoint_* error and keeps original history; tools proposed
by the summarizer never execute. Automatic compaction keeps a recent complete
exchange tail. See context management
for retention, usage accounting, native request estimates and tool excerpts.
Web access¶
The managed Agent constructs an enabled WebOptions object with Google HTML as
the primary search engine https://www.google.com/search, raced against fixed
free fallbacks (DuckDuckGo HTML, Bing, Mojeek); the first engine with usable
results answers and the rest are cancelled, and a total failure surfaces the
earliest engine's bounded error instead of an empty result. It
maps standalone web_search to network.search and standalone
web_fetch to network.fetch;
the canonical Broker policy remains authoritative for each read-only call:
plan, standard, and full_access all allow Web. An explicit ordered ask
rule may still return web_approval_required.
Redirects are disabled or validated at every hop, private/reserved targets are
rejected, and response bytes, content types, UTF-8, sanitizer output, and
citation count are capped. Web payloads are data only and cannot grant tools,
permissions, paths, approvals, or preset changes; embedded URL credentials
are rejected as well. Fetched text is wrapped with
[untrusted_web_reference]. Web policy applies to each request separately
from terminal execution; neither path uses OS network confinement.
Workspace SKILL.md bodies are untrusted prompt guidance. LSP and extensions are
not loaded or discoverable. User plugins (ADR 0044) load
only from ~/.ru/plugins and %LOCALAPPDATA%\Ru\plugins, only once the user enables
them; their hooks and MCP servers run only for the exact commands the user approved, and a
repository cannot supply one. MCP servers come from the user's own ~/.ru/mcp.json and from
those approved plugins, never from the workspace.
Selecting a preset while idle does not add a composer status row, so the empty
conversation welcome content keeps its position. The Agent inline status appears only
after a request or another activity that needs user interaction; a typed
request starts with Đang chuẩn bị thao tác…. Subsequent status and event
summaries are bounded safe copy, while verified completion and failure remain
fixed or safe-reason states. Malformed or stale-session activity is ignored.
Disconnect and session replacement clear the visible state
and pending approval.
The populated conversation transcript keeps its reading column centered and capped at 820 px, while the scroll host spans the full conversation viewport so its native vertical scrollbar sits at the far-right edge. Horizontal scrolling remains disabled and does not alter message width or composer alignment.
Transcript follow uses a consistent viewport snapshot: an offset beyond the measured
extent cannot trigger a scroll, including in follow mode. Wheel, pointer and navigation
key input pause following; reaching the bottom or explicitly jumping to latest resumes
it. Layout changes alone preserve this intent. Session opens realize the latest item;
bulk reloads preserve a parked reader's first visible item and its position within the
viewport, with a bounded pixel-offset fallback if the container is unavailable.
These bulk actions flush layout once, rather than on every streaming delta. Deferred
scroll actions are discarded after reader input, session replacement or another
transcript reset. The virtualized panel uses KeepScrollOffset; completed view
changes schedule another follow attempt when row realization changes the extent
while follow mode remains active. A reader parked in history does not receive
these follow attempts.
Persistence and privacy¶
ASP.NET Core owns settings, credentials, sessions (including message history), activity,
and reviewed-example policy. Business records share agent_harness.db under the canonical
%LOCALAPPDATA%\Ru location (see
docs/adr/0004-canonical-ru-data-location.md). Windows Credential
Manager remains the secret store.
Logs, telemetry, manifests, and automated evidence may contain fixed event types, counts, durations, hashes, and statuses only. They must not contain credentials, bearer values, request bodies, user/session identifiers, transcripts, or private marker metadata.
Technical diagnostics are structured JSONL under RU_LOG_ROOT (defaulting to
%LOCALAPPDATA%\Ru\logs) with bounded ASP.NET, test-fixture, and WinUI
writers. The HTTP boundary records fixed route categories and durations; the
diagnostics API rejects invalid/oversized queries and caps exports at 2 MB.
Activity Timeline records are sanitized before SQLite insertion and on read.
Agent projections still follow the durable conversation outbox. The retired
file activity-outbox poller is replaced by one-time legacy import (ADR-0013).
Acceptance boundary¶
Automated tests can establish routing, protocol ordering, bounds, cancellation, privacy filtering, persistence semantics, and process lifecycle. They cannot establish the effect of an arbitrary terminal command on a live external application or device, provider quality, or natural bilingual dialogue. Those remain explicit user-run checks and must be reported as pending until performed.
Provider payment failures¶
Generation providers classify HTTP 402 as provider_payment_required, non-retryable.
Responses stream errors with code 402 or payment_required use the same outcome.
Client copy directs the user to billing/credit; it does not claim that every 402
means an empty balance or promise that another model cannot work. No automatic
provider/model switch is introduced. Diagnostic category inference no longer
maps any category containing runtime to worker.unavailable; explicit event
codes retain precedence and genuinely worker-named categories keep compatibility.