Expand description
One session’s runtime, shared by every mode. TypeScript runs every session in a session worker process and so
does the Rust build (crates/daemon worker); this crate is what that worker runs:
lane: the model, its key, the native worker’s system prompt, the provider call, the clock lines and the singlerlmtool (the model’s tool list is exactly[rlm]);compose: the composition root of the host stack behind a lane’s kernels;journal: the format-4 harness operation journal of a run;compaction_opthat of a compaction;naming: automatic and model-made session names;- [
pi_view] /view: the session as Pi entries and Pi’s read views (tree, messages, stats); core: the session actor that owns all of it and reports lane-watch events.
Modules§
- async_
events - Completion events instead of polling: a port of
packages/coding-agent/src/ultron/async-events.ts. - auto_
compaction - Automatic compaction of the root lane: the settings it runs with and when it starts. The session worker’s
harness (packages/agent/src/harness/runtime/drive) compacts at a run’s checkpoints, before the run ends or before
its next request, when the context crosses
contextWindow - reserveTokens(checkpoint.ts,prepareCompactionThreshold), and on a response that overflowed the window, compacting and retrying the request once (response.ts,publishResponse). The session actor runs both (crate::core); this module is the arithmetic and the classification, ported from pi-aiisContextOverflow/isRecoverableLengthand the settings manager’sgetCompactionSettings. - auto_
memory - Automatic memory (Rust-only; in TypeScript, and with it off, memory is recalled and kept only when the model calls
memory.prepare/memory.propose, which it rarely does): the session recalls before each user message and keeps its compaction summaries, and what no summary covered when it closes. - auto_
refine - Automatic instruction refinements (Rust-only): the session learns from its own compaction summaries, with evidence it cannot invent.
- cell_
file_ changes - The diff of what an rlm cell wrote, in its result’s
details.fileChanges(Rust-only; the TypeScript result’s details stay{}):[{path, created, diff}]per file written through the checkedwrite()/edit()(host::cell_writes),diffin the edit tool’s display format (generateDiffString, context 2), or null for a file too large or not text. The interactive mode shows it under the expanded cell. - commands
listCommandsof the session control (session-control-provider.ts), as RPCget_commandsanswers it: the built-in/mcp,/review,/observer, the prompt templates and skills (skill:<name>), each with itsSourceInfoas the resource loader gives it (crate::session_resources): auto-discovered ones{source: "auto", scope, origin: "top-level", baseDir}, settings entrieslocal; the bundled skills the worker passes as paths are{source: "local", scope: "temporary"}with the skill’s directory asbaseDir. Pi extensions are not supported by ultron-rs.- compaction_
op - A manual compaction or a tree navigation as the harness journals its operation (
runtime/lane.tsacceptCompaction/acceptNavigation,runtime/drive/structural.ts): the preparation and the operation insummary.deciding,summary.ready,summary.effect_pending(before the request, with the request, then with its usage row), and the terminal transaction that commits the compaction entry (or the branch summary), moves the tip and records the result. A navigation without a summary is admitted atnavigation.ready_to_commitand committed by its own terminal transaction (commitNavigation). - compose
- The composition root of a session’s host stack. A cell’s host request passes, outermost first:
- context_
reminder - The context-pressure reminder (Rust-only; TypeScript has none): when a lane’s context nears the point where the
harness compacts it, the lane’s next
rlmresult ends with one[context: ...]line telling the model to free space withctxitself. Models given one reminder shortly before the budget edit their context; without one they rarely do (“Context Language Models”, arXiv 2609.37725). - continuation
/continue(Op::ContinueFrom): a new session that continues an old one by searching its log instead of carrying a summary of it. Its first message says which session it continues and how to read it (sessions.search/sessions.readscoped to it); nothing of the old conversation is copied.- core
- The session actor: one session (format-4 journal), its lane (the
rlmkernel over the composition root’s host stack) and the run in progress, owned by one thread. Every client operation is anOpanswered through its reply; the run’s progress is reported as TypeScript lane-watch events (run_start,message_*,tool_*,entry_added,queue_update,compaction_*,config_update,run_end) through the event sink, which the session worker folds into itsultron.transcriptstate. - durable_
store - The session’s Pi Durable storage, kept in the session’s own format-4 journal: the durable conversation runtime
(
harness::chat: generations, REPL cells, the inbox, children) commits through the storageopenreturns, which validates each commit against an in-memoryMemoryStorageand appends it to the session file as oneultron.modulelist element (durable:{seq, writes}) before applying it. Reopening the session replays those elements, so every durable record survives a crash with the transcript it belongs to, in one file. - frame_
models - The models a frame may name (
rlm.infer(model=...),rlm.frameModel,ULTRON_RLM_FRAME_MODEL): TypeScript sets the frame task lane’s model and the lane resolves it from the session’s model registry with the provider’s own key (getModel,getAuth). Here the built-in catalog or models.json gives the model, ready for requests, and the key is the one a lane of that provider would carry. - frames
- Bounded-inference frames in the session (inference.ts
createSessionFrameStore, and theframesexecutor andNativeHostApithe TS host hands itsInferenceRuntime): everyrlm.infer/rlm.mapframe is anrlm-frame@1task of the session’s typed-agent host (journaled, admitted under its caller, cancelled with the calling cell, its requests reserved and settled in the usage ledger), its trace is a session value (ultron.rlm.frames/<id>, with the index atultron.rlm.frames/index), and a frame with depth runs itsrlmcell on the task’s lane. - guard_
log ULTRON_LOKI_LOG(loki.tslokiLog): every file-hook guard outcome appended to a file as a JSON line{"at": <ms since the epoch>, "guard", "phase", "outcome", "ms", "paths", "lane", "detail"?}, and the session’s Loki setup (setupLoki’s record) as{"at", "phase": "setup", "outcome": "on", "mode", "engine", "reports", "projectPython", "ms"}. Unset or blank writes nothing; a relative path is resolved against the process directory; write errors are ignored.- inspect
- The session inspector (
createSessionControl().inspect, session-control-provider.ts): the read-only host requests behind RPCinspect,/agents,/memory why|list,/skills,/experiments,/goals,/progressand the Claude Code watch views. A request outsideINSPECTION_REQUESTSis refused before it reaches the runtime, so inspecting never runs a search, starts work or changes state. Allowed requests go to the session’s host stack as the root lane’s requests (the worker’shost.handle(request, payload)), outside any cell. - journal
- A lane run’s harness operation journal in the format-4 session (crates/session-journal
run): the run is admitted with its prompt, each turn’s stream is journaled as it arrives, assistant messages and tool results commit as entries, and the run finishes with its outcome. Print, JSON and RPC runs write the same records. - kept_
contracts - Contracts for persistent children:
rlm.spawn(brief, name=..., keep=True, role=, contract=, hop=). A kept child answers more than once (its brief, then eachrlm.ask), so each answer is held to its contract as a one-shot child’s end is (delegation::spawn_contract::enforce):returnsagainst its latestrlm.finishverdict, the host’s checks in the session’s working directory under the session’s sandbox, and the hop (a{"retry": N}asks the child again with its failures, a{"review": brief}spawns a reviewer subagent). - lane
- The root lane every prompted mode runs on (print mode,
--mode json,--mode rpc): the model, its key and the native worker’s system prompt (session-worker.ts), the singlerlmtool whose cells run in a persistent kernel (crates/kernel) over the host stack the composition root builds (crate::compose), the provider call, and the clock lines (ultron/clock-context.ts) and REPL result footers a request carries. - local_
resources - The local resources a session and
ultron configresolve (the local half ofcore/package-manager.tsresolve()): the settings’skills/prompts/themesentries (paths, globs and!/+/-patterns, project scope first) and the auto-discovered ones (.pi/skills,.pi/prompts,.pi/themes,.agents/skillsfrom the cwd up to the git root,<agentDir>/skills,<agentDir>/prompts,<agentDir>/themes,~/.agents/skills). A project that is not trusted contributes no settings entries, no project resources and no ancestor.agents/skills. - loki_
notice - Loki’s one-time setup note (session-worker.ts
installLokiNoticeover loki.tssetupLoki’snotice): when the session opens, a Git repository without.loki/gets Loki’s minimal install where that is allowed (loki::auto_setup), and.loki/is committed in the background. The note of what happened (created and committed, or why not) opens the first root turn that follows it, as a displayedlokicustom message; a commit still running is waited for briefly, otherwise the note opens a later turn. - memory_
children - Subagents run as in-memory agent loops (a session without the durable runtime:
ultron mcp, whose root is Claude Code, with--children ultronor noclaudeinstalled). The same loop asdelegation::child::agent_runner(the child’s reply is its last assistant message’s text; cancelling the child aborts the loop), with what a child lane of the session actor gets from its durable conversation: - memory_
guidance - How much the memory section of a reader’s guide says, by the reader’s model tier (the memory guidance of the plan): every reader gets the purpose line (what memory is for); a weaker tier also gets the procedural line (check memory for the topic before answering; test a theory before keeping it). A strong root model does better with the purpose alone, so procedure is spent only where it helps. The runtime guide maps each value to its text; this decides which one a reader gets.
- migration
- Explicit, repeatable migration between Pi and Ultron sessions (
ultron/migration.ts):import_pi_sessioncopies a whole Pi session tree into a new native format-4 session,export_native_session_to_piwrites a native session’s whole tree back as a Pi session (rollback). Nothing here reads Pi’s data directory implicitly: every source path is given by the caller. - model_
refresh ultron update --models(refreshModelCatalogsof package-manager-cli.ts): every provider that refreshes its catalog and has a credential refreshes it from the network, asModelRuntime.refresh({ allowNetwork: true, force: true })does: built-in providers revalidate their pi.dev catalog, Radius providers (the built-in one and models.json"oauth": "radius"ones) load<gateway>/v1/configwith their key (an expired OAuth token is refreshed first). Results land in models-store.json, which every later start restores.- naming
- Session naming by one small model call. The deterministic name from the first prompt
(
session_journal::names::auto_name) is written at once; this asks a cheap model for a better title, which replaces it only while the name is still the automatic one. Settings:sessionNaming.enabled(default true) andsessionNaming.model(provider/id, or an id of the session’s provider). The model defaults to the session provider’s cheapest catalog model, else the session model. - nudge
- The root agent’s research-loop brake and procedural-memory hint (
ultron/tool-round-nudge.ts), as session-worker.ts wires them onmain’sturn_end: afterULTRON_TOOL_ROUNDS_NUDGEconsecutive tool rounds the root is steered to answer (again, more firmly, at twice that); while subagents or tasks it started run, busy rounds are steered to wait instead; afterULTRON_SKILL_NUDGEsuccessful rounds it is told once to save the procedure as a code skill. The steers are queued as steering messages; nothing is ever aborted. - recovery
- Recovery of a session whose worker died: the lane’s open operation (a run whose terminal transaction never committed) is settled from what the journal committed, without another provider call and without replaying any cell, and the queued messages that were waiting in the lane’s inbox are handed back to the queues.
- request_
keys - The key each model request carries, resolved when the request is sent (
ModelRuntime.getAuthper request, so a/login, a changed auth.json or a refreshed OAuth token applies to the next request), and the request stack the session’s side lanes (frames, in-memory subagents, the predict adapter) send through. - request_
layer - A layer over every lane’s host requests, set once by a composition root whose root agent is not the session
actor’s (
ultron mcp, whose root is Claude Code): it may answer a request itself (refuse an API that root cannot serve, such asschedule.*with nothing to fire it) or pass it on and see the answer (which root a spawn’s work is charged to). Without one set, requests pass through unchanged. - request_
settings - Provider request options the settings fill (sdk.ts
buildRequestOptions, session-worker.tsproviderRequestOptions, worker-settings.tstransport, and the Agent’sthinkingBudgets):thinkingBudgets(the token budget each reasoning level asks for),websocketConnectTimeoutMs(the WebSocket transport’s connect timeout), the stream options of every request (timeoutMs:retry.provider.timeoutMs, else the HTTP idle timeout;retry.provider.maxRetriesandmaxRetryDelayMs) and thetransportsetting. A request’s own value wins (options.x ?? settings.x). An invalid timeout fails the request withInvalid <setting> setting: <value>, as TypeScript’sparseTimeoutSettingthrows while building it. - request_
trace - Provider request traces for offline evals (Rust-only feature; the idea is reflection-oss/mirror’s
*.model-calls.jsonl,mirror-agent/src/http/traced_model.rs): withULTRON_REQUEST_TRACE=<file>every conversation request (the root lane’s and each subagent conversation’s) appends one JSON line to<file>once its response arrived, holding only the DELTA from the previous request of the same lane: - review_
command /review(packages/coding-agent/src/ultron/review.ts): the typed command becomes a short prompt that asks the model to run Ultron’s built-in review in one REPL cell and relay its report. The review itself is Python (review_api); nothing about it is in the system prompt of ordinary turns.- session_
diagrams diagram.mermaidfor a session (diagram): node from the session environment’sPATH, Pele unpacked under<agent dir>/cache, diagrams saved to<agent dir>/rlm-output/<session id>/diagrams, the theme from thethemesetting (read at each call), the terminal appearance the attached TUI reported (OSC 11) and the session’sCOLORFGBG, and shown diagrams handed to the lane’s cell images (crate::view_images::ViewImages): attached for the model withto_model, else kept for the tool result’s display only.- session_
flags - The resource flags a session worker is started with (
SessionWorkerOptionsof experimental/session-worker.ts, from the command line through native-command.ts and the server’s model options): - session_
resources - The resources a session loads, as resource-loader.ts
reloadassembles them for the session worker: - session_
stats - The session’s runtime counters (
ultron/session-stats.ts): what the runtime sees while a session runs and no other session value keeps, for the session report (/usage,ultron usage). They are the session valueultron.module/stats, written as the TypeScript recorder writes it, so either implementation reads the other’s. - situational_
skills - Situational skills (Rust-only, engineering mode): the skill that fits what a cell just did is put in front of the model, instead of trusting the model to read it.
- startup_
trace traceStartup(experimental/startup-trace.ts), the writer of the CLI, session-worker and client milestones: append one startup milestone to the file named byULTRON_STARTUP_TRACE(every process of a start shares it), as a JSON line{at, origin, pid, label}:atthe wall-clock time in milliseconds,originthe process’s start (performance.timeOrigin). Off unless the variable is set; a failed write is ignored (tracing never affects startup).- stored_
auth - The auth.json credential a request uses (
resolveProviderAuthover the composed provider auth ofprovider-composer.ts): a stored credential owns its provider. Anapi_keycredential’s key (its$VARtemplate resolved against the credential’senv, then the environment) wins over the models.jsonapiKeyand the environment; a credential without a usable key falls back to the built-in provider’s environment key (a custom provider has none). Anoauthcredential gives its access token, refreshed under the store’s lock when it expires within five minutes, for the providers with an OAuth handler; any other credential type leaves the provider unconfigured (no environment fallback). - subagents
- Subagents on the durable task journal. An
rlm.spawnchild runs as a child conversation of the session’s durable runtime (harness::chat::children: anultron.childtask owning its conversation), so its model calls and cells are as durable as the root’s: a worker that dies leaves it to the next one, which resumes it (a pinned request is resent, a running cell reportsinterrupted) and reattaches the delegation host’s task to it. - swarm_
ops - The session’s shared world for the REPL (
swarm_api.py):swarm.*(who holds what, durable peer messages),board.*(the task board),notes.*(shared notes), and persistent children (rlm.spawn(..., keep=True),rlm.ask). They are served byharness::chat::host_opsover the session’s durable runtime, as the calling lane’s conversation:mainis the root conversation, a subagent lane its child conversation, another root conversation its own. Ordinary subagents stay with the delegation host;rlm.collect,rlm.results,rlm.cancelandrlm.delete_subagentcome here only when every child they name is a persistent one. - turn_
checkpoints - Working-tree checkpoints of a root’s turns (Rust-only feature; see docs/rust-rewrite/features.md): each root turn
records the working tree as an unreferenced commit (crates/delegation
checkpoints) under its key (crates/session-journalcheckpoints), before the turn runs: the native root under its prompt entry (crate::core), an external root (ultron claude) under its turn id. - turns
- The bridge between the session actor (
crate::core) and the durable conversation runtime (harness::chat) that runs every root turn. - view
experimental/pi-session-view.ts: Pi’s read-side views (tree, context messages, last assistant text, stats) over a format-4 session converted to Pi entries ([super::pi_view]), with the shapes and numbers Pi reports.- view_
images view_imagein the session (ultron/rlm/view-image.tsas session-worker.ts wires it): a cell’srlm.view_imagerequests are answered by the cell’s own image collector (host::view_image::CellImages, normalized for the lane’s current model and Pi’simages.autoResizesetting), and therlmtool result carries the images as image blocks after its text. The image budget (ultron/image-budget.ts,ULTRON_CONTEXT_IMAGES) keeps the oldest tool-result images of a request out of it as a note.- wake
- Which lanes the host wakes when their work ends, and what follows from it. One rule for every mode: the root lane
(
main) is woken only when its composer says so (the native session’s event dispatcher with completion events on,ultron claude’s wait-events hook); every other lane (subagents, other root conversations) and every root nothing wakes (ULTRON_ASYNC_EVENTS=off, anultron mcproot without--wake, a Claude child) waits in its cell.
Structs§
- Model
Flags - The model flags a session starts with (
--provider,--model,--api-key,--thinking,--models). - RunEnv
- The process environment and locations a session sees.
Constants§
- RUNTIME_
PY - The REPL’s runtime script, relative to the package directory.
Functions§
- flag_
off - A session switch’s “off”:
off,0orfalse, in any case and with surrounding space (the TypeScript["off", "0", "false"].includes(value.trim().toLowerCase())).