Skip to main content

Crate session_core

Crate session_core 

Source
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 single rlm tool (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_op that 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-ai isContextOverflow / isRecoverableLength and the settings manager’s getCompactionSettings.
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 checked write()/edit() (host::cell_writes), diff in 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
listCommands of the session control (session-control-provider.ts), as RPC get_commands answers it: the built-in /mcp, /review, /observer, the prompt templates and skills (skill:<name>), each with its SourceInfo as the resource loader gives it (crate::session_resources): auto-discovered ones {source: "auto", scope, origin: "top-level", baseDir}, settings entries local; the bundled skills the worker passes as paths are {source: "local", scope: "temporary"} with the skill’s directory as baseDir. 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.ts acceptCompaction / acceptNavigation, runtime/drive/structural.ts): the preparation and the operation in summary.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 at navigation.ready_to_commit and 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 rlm result ends with one [context: ...] line telling the model to free space with ctx itself. 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.read scoped to it); nothing of the old conversation is copied.
core
The session actor: one session (format-4 journal), its lane (the rlm kernel over the composition root’s host stack) and the run in progress, owned by one thread. Every client operation is an Op answered 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 its ultron.transcript state.
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 storage open returns, which validates each commit against an in-memory MemoryStorage and appends it to the session file as one ultron.module list 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 the frames executor and NativeHostApi the TS host hands its InferenceRuntime): every rlm.infer / rlm.map frame is an rlm-frame@1 task 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 at ultron.rlm.frames/index), and a frame with depth runs its rlm cell on the task’s lane.
guard_log
ULTRON_LOKI_LOG (loki.ts lokiLog): 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 RPC inspect, /agents, /memory why|list, /skills, /experiments, /goals, /progress and the Claude Code watch views. A request outside INSPECTION_REQUESTS is 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’s host.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 each rlm.ask), so each answer is held to its contract as a one-shot child’s end is (delegation::spawn_contract::enforce): returns against its latest rlm.finish verdict, 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 single rlm tool 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 config resolve (the local half of core/package-manager.ts resolve()): the settings’ skills/prompts/themes entries (paths, globs and !/+/- patterns, project scope first) and the auto-discovered ones (.pi/skills, .pi/prompts, .pi/themes, .agents/skills from 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 installLokiNotice over loki.ts setupLoki’s notice): 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 displayed loki custom 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 ultron or no claude installed). The same loop as delegation::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_session copies a whole Pi session tree into a new native format-4 session, export_native_session_to_pi writes 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 (refreshModelCatalogs of package-manager-cli.ts): every provider that refreshes its catalog and has a credential refreshes it from the network, as ModelRuntime.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/config with 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) and sessionNaming.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 on main’s turn_end: after ULTRON_TOOL_ROUNDS_NUDGE consecutive 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; after ULTRON_SKILL_NUDGE successful 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.getAuth per 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 as schedule.* 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.ts providerRequestOptions, worker-settings.ts transport, and the Agent’s thinkingBudgets): 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.maxRetries and maxRetryDelayMs) and the transport setting. A request’s own value wins (options.x ?? settings.x). An invalid timeout fails the request with Invalid <setting> setting: <value>, as TypeScript’s parseTimeoutSetting throws 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): with ULTRON_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.mermaid for a session (diagram): node from the session environment’s PATH, Pele unpacked under <agent dir>/cache, diagrams saved to <agent dir>/rlm-output/<session id>/diagrams, the theme from the theme setting (read at each call), the terminal appearance the attached TUI reported (OSC 11) and the session’s COLORFGBG, and shown diagrams handed to the lane’s cell images (crate::view_images::ViewImages): attached for the model with to_model, else kept for the tool result’s display only.
session_flags
The resource flags a session worker is started with (SessionWorkerOptions of 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 reload assembles 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 value ultron.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 by ULTRON_STARTUP_TRACE (every process of a start shares it), as a JSON line {at, origin, pid, label}: at the wall-clock time in milliseconds, origin the 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 (resolveProviderAuth over the composed provider auth of provider-composer.ts): a stored credential owns its provider. An api_key credential’s key (its $VAR template resolved against the credential’s env, then the environment) wins over the models.json apiKey and the environment; a credential without a usable key falls back to the built-in provider’s environment key (a custom provider has none). An oauth credential 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.spawn child runs as a child conversation of the session’s durable runtime (harness::chat::children: an ultron.child task 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 reports interrupted) 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 by harness::chat::host_ops over the session’s durable runtime, as the calling lane’s conversation: main is 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.cancel and rlm.delete_subagent come 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-journal checkpoints), 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_image in the session (ultron/rlm/view-image.ts as session-worker.ts wires it): a cell’s rlm.view_image requests are answered by the cell’s own image collector (host::view_image::CellImages, normalized for the lane’s current model and Pi’s images.autoResize setting), and the rlm tool 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, an ultron mcp root without --wake, a Claude child) waits in its cell.

Structs§

ModelFlags
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, 0 or false, in any case and with surrounding space (the TypeScript ["off", "0", "false"].includes(value.trim().toLowerCase())).

Type Aliases§

VarLookup