OpenCode Session Runtime

OpenCode sessions preserve durable conversational history while assembling the runtime context an agent needs to act correctly in its current environment.

Language

System Context: The structured collection of contextual facts presented to the model as initial instructions and chronological updates. Avoid: System prompt

Session History: The projected chronological conversation selected for a provider turn after applying the active compaction and Context Epoch cutoffs. Avoid: Session Context

Context Source: One independently observed typed value within the System Context, represented by a stable key, JSON codec, infallible loader, pure baseline/update renderers, and an optional removal renderer for dynamic sources. Avoid: Prompt fragment

System Context Registry: The Location-scoped registry of ordered, scoped producers that contribute to the current System Context.

Mid-Conversation System Message: A durable chronological instruction that tells the model the newly effective state of a changed Context Source. Avoid: System update, system notification, raw text diff

Context Epoch: The span during which one initially rendered System Context remains the immutable provider-cache baseline, ending at completed compaction, Session movement, or an incompatible context transition that requires a fresh baseline.

Baseline System Context: The full System Context rendered at the start of a Context Epoch. Avoid: Live system prompt

Context Snapshot: The overwriteable model-hidden JSON state used to compare each Context Source with the value last admitted to a provider turn.

Unavailable Context: An expected temporary inability to observe a Context Source value; the runtime retains its prior effective state and emits no update, or omits it until first successfully loaded.

Safe Provider-Turn Boundary: The point immediately before a provider call, after durable input promotion and any required tool settlement, where context changes may be admitted chronologically.

Admitted Prompt: A durable user input accepted into the Session inbox but not yet included in Session History.

Prompt Promotion: The durable transition that removes an Admitted Prompt from pending input and appends its user message to Session History.

Provider Turn: One request to a model provider and the response projected from that request.

Session Drain: One process-local execution span that promotes eligible input and runs required Provider Turns until no immediate continuation remains. A Session Drain has no durable identity or transcript boundary.

Model Tool Output: The bounded projection of a Core-executed tool result persisted in Session history and replayed to the model. A tool may shape this projection semantically, but the Tool Registry enforces the final size limit.

Managed Tool Output File: A temporary file created under OpenCode's shared tool-output directory to retain complete output that was too large for Session history.

PTY Environment: The host-supplied environment overlay applied by the server when creating a PTY, observed for the request Location and resolved PTY working directory.

Relationships

• A System Context is an opaque carrier composed from zero or more Context Sources.
• Session History contains projected conversational messages and admitted Mid-Conversation System Messages; the active Baseline System Context remains separate provider-request state.
• The System Context Registry uses stable-keyed scoped contributions to assemble the current System Context; contributor removal naturally removes its sources at the next Safe Provider-Turn Boundary.
• A changed Context Source may produce one Mid-Conversation System Message containing its newly effective state.
• A Mid-Conversation System Message persists the exact combined rendered text sent to the model.
• The current Context Snapshot advances atomically with the corresponding durable Mid-Conversation System Message.
• A Context Snapshot stores one codec-encoded JSON value and, for removable dynamic sources, a pre-rendered removal message per stable Context Source key.
• Changes from multiple Context Sources admitted at one safe boundary combine into one Mid-Conversation System Message.
• Context changes are sampled and admitted lazily at a Safe Provider-Turn Boundary, never pushed asynchronously when their source changes.
• At a Safe Provider-Turn Boundary, newly promoted user input or settled tool results precede any combined Mid-Conversation System Message.
• An Admitted Prompt is replayable pending input, not yet model-visible Session History.
• Prompt Promotion atomically consumes the pending inbox entry and appends its model-visible user message.
• Steering prompts promote at the next Safe Provider-Turn Boundary while the current Session Drain still requires continuation. Promoting any newly admitted user input resets the selected agent's provider-turn allowance; multiple prompts promoted at one boundary reset it once.
• A queued prompt does not promote while the current Session Drain requires continuation. The runner promotes one queued prompt when the Session would otherwise become idle, then reevaluates continuation before promoting another.
• A Session Drain is process-local coordination rather than a durable domain entity. Durable recovery must reason from prompts, projected history, provider attempts, and tool state rather than inventing an enclosing execution identity.
• The first provider turn renders the latest complete Baseline System Context and initializes its Context Snapshot without emitting a redundant Mid-Conversation System Message; unavailable initial context blocks the turn instead of persisting an incomplete baseline.
• Initial System Context preparation precedes the first durable input promotion so an unavailable baseline leaves that input pending and retryable; ordinary reconciliation remains after promotion.
• Compaction starts a new Context Epoch with a freshly rendered Baseline System Context and Context Snapshot; prior Mid-Conversation System Messages remain durable audit history but leave projected model history.
• A newly registered core or plugin-defined Context Source absent from the current snapshot emits its baseline rendering once at the next Safe Provider-Turn Boundary.
• Context Source keys are stable and namespaced; duplicate keys fail composition. SystemContext.combine(...) preserves caller order; the System Context Registry evaluates producers concurrently and combines them in stable contribution-key order so rendered context remains deterministic.
• Each Context Source loader returns one coherent typed value. SystemContext.make(...) hides that value type so differently typed sources compose uniformly. Its codec compares and stores that value; its pure renderers produce model-visible baseline, update, and removal text only when needed.
• SystemContext.initialize(...) observes a composed System Context once and produces a fresh Baseline System Context with its Context Snapshot.
• SystemContext.reconcile(...) observes a composed System Context once and returns exactly one next action: unchanged, updated, replacement ready, or replacement blocked.
• SystemContext.replace(...) renders a fresh generation after completed compaction or another baseline-replacing transition; it reports replacement blocked while previously admitted context is unavailable.
• Unavailable Context uses stale-while-revalidate semantics and is distinct from a successfully loaded absence, which may emit removal text.
• Ordinary Context Source loaders return values directly; loaders that intentionally use stale-while-revalidate may explicitly return Unavailable Context.
• Nested project instruction discovery after successful reads remains a follow-up; when implemented, discovered instructions must be admitted durably at the next Safe Provider-Turn Boundary.
• Location-scoped services naturally re-resolve effective context when a moved session next runs in its destination location.
• Moving a Session clears its active Context Epoch, so the destination must initialize a complete baseline before another prompt can promote.
• Instruction discovery, source identity, persistence, and file loading belong to the instruction service; the System Context abstraction only composes effectful producers and renders loaded values.
• The first instruction-service slice observes global and upward project AGENTS.md files as one ordered aggregate Context Source at each Safe Provider-Turn Boundary.
• Built-in and instruction context producers register through the System Context Registry with stable contribution keys. Plugin-defined context registration and hot-reload lifecycle remain a follow-up built on the same scoped registry seam.
• Selected-agent available-skill guidance is a Context Source composed with Location-wide registry sources immediately before Context Epoch admission. It lists only names and descriptions permitted for that agent; skill bodies and locations are exposed only through the permission-checked skill tool.
• The selected agent and model are sampled when a provider turn starts. Changes admitted after that boundary apply to the next provider turn and do not restart the current turn.
• Selected-agent available-skill guidance remains a Context Source. An agent switch that changes that guidance produces a Mid-Conversation System Message while preserving the current baseline.
• Local tool authorization and pending permission requests retain the effective agent of the provider turn that issued the call; a later agent switch cannot change that call's policy.
• Context source changes never wake idle sessions; the next naturally scheduled Safe Provider-Turn Boundary loads and compares current values lazily.
• Once admitted, a Mid-Conversation System Message remains durable even if the following provider attempt fails and is replayed unchanged on retry.
• Mid-Conversation System Messages remain durable Session-message history; normal user-facing transcript surfaces may hide them.
• The date Context Source initially preserves host-local calendar-date behavior; a configured user timezone may replace that default later.
• A Context Epoch begins with one immutable Baseline System Context.
• A Baseline System Context is stored durably and reused verbatim across process restarts within its Context Epoch.
• A Baseline System Context durably preserves the exact joined text used for the active provider-cache prefix.
• Completed compaction starts a new Context Epoch on the next provider attempt, folding the current complete System Context into a fresh baseline and removing earlier Mid-Conversation System Messages from active model history.
• A model/provider switch preserves the current Context Epoch and chronological conversation history; the new selection applies to the next provider turn.
• The PTY Environment is a server concern rather than a Core PTY concern. PTY creation merges caller values, then the host overlay, then Core-forced terminal invariants such as TERM and OPENCODE_TERMINAL.
• A PTY Environment adapter observes plugins in the request Location while passing the resolved PTY working directory to the hook; standalone servers use an empty adapter.
• A Mid-Conversation System Message lowers to the provider's native chronological instruction role when supported and to a wrapped chronological fallback otherwise.
• When the effective aggregate instruction set changes, its Mid-Conversation System Message includes the complete current ordered set and supersedes the prior aggregate value; when no ambient instructions remain, the message states that previously loaded instructions no longer apply.
• Ambient project instruction discovery honors OPENCODE_DISABLE_PROJECT_CONFIG; global instructions remain eligible.
• Oversized textual Model Tool Output retains a bounded preview in Session history while its complete text moves to managed tool-output storage. Arbitrary structured-result size is a separate concern.
• One tool settlement receives one aggregate textual limit, using the configured maximum lines or UTF-8 bytes, whichever is reached first. The limit is provider-independent; token pressure belongs to context assembly and compaction.
• Generic truncation preserves the beginning and end of textual output. Tools may apply a more meaningful strategy before the Tool Registry enforces the final limit.
• A truncated Model Tool Output identifies its complete text both in the bounded model-visible preview and as a typed managed output path. Managed output paths do not modify the tool's validated structured result.
• A Managed Tool Output File is temporary and may expire after its retention period. The bounded Model Tool Output, not the file, is the durable replayable record.
• Failure to retain a Managed Tool Output File does not change a successful tool operation into a failed one. The Session records an explicitly lossy bounded output without a path, while operators receive diagnostics for the storage failure.
• Once a tool operation succeeds, bounding its Model Tool Output and publishing its one durable settlement form an interruption-safe completion region. Raw oversized success is never published before a later correction.
• When a structured-only result would exceed the Model Tool Output limit, its validated structured value remains unchanged for Session consumers while model replay uses a bounded textual JSON preview and optional managed output path.
• Existing tool-managed output paths survive generic bounding. A fallback file retains exactly the complete projected text received by the Tool Registry and never claims to reconstruct output already discarded by tool-specific shaping.
• Managed Tool Output Files use globally unique names in one shared flat directory. Their absolute paths are readable and searchable by ordinary tools; other absolute paths remain outside Location-scoped filesystem authority.
• Provider-executed tool results remain provider-native transcript facts outside generic Tool Registry bounding. Their context control requires provider-aware pruning or compaction because some providers require exact structured round-trip payloads.

Example dialogue

Dev: "The date changed while the session was active. Should the Mid-Conversation System Message say what the old date was?" Domain expert: "No. Emit the newly effective date so the agent can act on the current System Context."

Flagged ambiguities

• Legacy experimental.chat.system.transform can mutate the assembled baseline system prompt arbitrarily, but V2 plugins do not yet expose an equivalent hook. Decide separately whether to port it, replace dynamic uses with plugin-defined Context Sources, or narrow its semantics.