Distillation

Date: Sep 16, 2026

• 🟡 (15:57) Generated schema in packages/core/src/database/schema.gen.ts defines recovery wake-selection index session_recovery_wake_pending_error_attempts_created_execution_idx on (wake_pending, recovery_error, wake_attempts, time_created, execution_id).
• 🟡 (15:58) packages/core/src/session.ts:422-433 implements wait by validating the session with result.get(sessionID) and returning OperationUnavailableError({ operation: "wait" }); resume validates then calls execution.resume(sessionID); interrupt invokes execution.interrupt(sessionID) inside Effect.uninterruptible.
• 🟡 (15:58) packages/core/src/session.ts:434-453 exposes revert operations: stage calls SessionRevert.stage({ session, messageID: input.messageID, files: input.files }) with Database.Service, EventV2.Service, and the session location provided; clear calls SessionRevert.clear(session) with events and location; commit calls SessionRevert.commit(session) with events.
• 🟡 (15:58) resolvePrompt in packages/core/src/session.ts:461-473 preserves text, agents, and mapped files; file MIME is inferred first from a data: URI, otherwise from FSUtil.mimeType(target), with targets ending in / assigned application/x-directory.
• 🟡 (15:58) The global node in packages/core/src/session.ts:475-487 uses service: Service, layer: layer.pipe(Layer.orDie), and dependencies Database.node, EventV2.node, ProjectV2.node, SessionExecution.node, SessionStore.node, LocationServiceMap.node, and SessionProjector.node.
• 🟡 (15:58) packages/core/src/session/compaction.ts uses compaction defaults DEFAULT_BUFFER = 20_000, DEFAULT_KEEP_TOKENS = 8_000, TOOL_OUTPUT_MAX_CHARS = 2_000, and SUMMARY_OUTPUT_TOKENS = 4_096; document configuration can override compaction.auto, compaction.buffer, and compaction.keep.tokens.
• 🟡 (15:58) The compaction summary template requires sections in exact order: ## Objective, ## Important Details, ## Work State with ### Completed, ### Active, and ### Blocked, ## Next Move with numbered items 1 and 2, then ## Relevant Files; rules require every section, terse bullets, preservation of exact paths/symbols/commands/errors/URLs/identifiers, and no mention of compaction or the summary process.
• 🟡 (15:58) Summary-update instructions in packages/core/src/session/compaction.ts require combining <prior-summary> and newer <conversation>, carrying forward unfinished objectives, constraints, directives, decisions, and parallel workstreams; newer conversation wins conflicts, completed work moves from Active to Completed, resolved blockers are updated, and Objective/Next Move reflect current state.
• 🟡 (15:58) serializeToolContent in packages/core/src/session/compaction.ts joins tool content with newlines, emitting text directly and non-text attachments as [Attached ${item.mime}] or [Attached ${item.mime}: ${item.name}]; truncate limits serialized tool and shell output to 2_000 characters and appends \n[truncated].
• 🟡 (15:58) Compaction serialization labels messages as [User], [Assistant], [Assistant reasoning], [Assistant tool call], [Tool result], [Tool error], [System update], [Synthetic context], and [Shell]; user files serialize as [Attached ${file.mime}: ${file.name ?? file.uri}], completed tools include truncated output, errored tools include part.state.error.message, and other tool states include only the call.
• 🟡 (15:58) Compaction selection in packages/core/src/session/compaction.ts:143-164 excludes messages of type "compaction", serializes nonempty entries, and walks backward to retain recent conversation within the configured token count, returning older content as head and retained content as recent.
• 🟡 (15:58) buildPrompt creates either a new anchored summary from <conversation> or an updated summary combining <conversation> with <prior-summary>; in both cases it appends SUMMARY_TEMPLATE.
• 🟡 (15:58) compactIfNeeded skips compaction when automatic compaction is disabled, context is absent/nonpositive, or estimated { system, messages, tools } usage is at most context - Math.max(output, config.buffer); otherwise it calls compactAfterOverflow.
• 🟡 (15:58) compactAfterOverflow calculates provider output from input.request.generation?.maxTokens ?? input.model.route.defaults.limits?.output ?? 0, caps summary output at 4_096, and refuses compaction when no eligible selection exists, there is neither older head nor prior compaction, or the prompt estimate exceeds context - summaryOutput.
• 🟡 (15:58) Successful automatic compaction publishes SessionEvent.Compaction.Started with a new SessionMessage.ID, timestamp, and reason: "auto"; streams an LLM request with the same model and HTTP settings, one Message.user(summaryPrompt), no tools, and generation.maxTokens = summaryOutput; then publishes SessionEvent.Compaction.Ended with the accumulated summary text and selected.recent.
• 🟡 (15:58) Automatic compaction returns false if streaming throws LLM.Error, emits any provider-error event, or produces blank summary text; text-delta events are accumulated into the summary. beforeStream runs before the provider stream, eventCommit may commit the Started event, and input.commit may commit the Ended event.
• 🟡 (15:58) SessionContextEpoch.initialize and SessionContextEpoch.prepare in packages/core/src/session/context-epoch.ts require a SessionExecutionClaim.Claim; prepare concurrently loads current SystemContext, the stored epoch, and SessionHistory.latestCompaction(...) with concurrency: "unbounded".
• 🟡 (15:58) When no context epoch exists, prepareOnce calls SystemContext.initialize(value), inserts baseline, snapshot, and the current EventV2.latestSequence(db, sessionID) as baseline_seq through SessionExecutionClaim.transaction, and returns { baseline, baselineSeq }.
• 🟡 (15:58) Existing context epoch snapshots are decoded with Schema.decodeUnknownEffect(SystemContext.Snapshot); failures map to ContextSnapshotDecodeError({ sessionID, details: String(error) }).
• 🟡 (15:58) Context preparation chooses SystemContext.replace(value, snapshot) only when the latest compaction sequence is greater than stored baseline_seq; otherwise it uses SystemContext.reconcile(value, snapshot). Results "Unchanged" and "ReplacementBlocked" retain the stored baseline and sequence, while "ReplacementReady" replaces the persisted generation using the compaction sequence or current latest event sequence.
• 🟡 (15:58) A reconciled context update publishes SessionEvent.ContextUpdated with a fresh SessionMessage.ID, timestamp, and result.text; its commit callback advances only the stored snapshot via a claim-guarded transaction. Missing rows during replace or advance die with exact error Context Epoch not found.
• 🟡 (15:58) SessionContextEpoch.reset deletes the row for session_id; initializeOnce is a no-op if one already exists, otherwise initializes and inserts the epoch.
• 🟡 (15:59) packages/core/src/session/run-coordinator.ts defines a per-key SessionRunCoordinator that serializes execution for each key while allowing different keys concurrently. Its interface exposes active, run(key), wake(key), and interrupt(key, cleanup?); each entry tracks done, optional owner, optional exit, pendingWake, and stopping.
• 🟡 (15:59) Coordinator run(key) starts options.drain(key, true) when idle, joins the active execution when already running, and if execution is stopping waits for its completion before recursively retrying run(key).
• 🟡 (15:59) Coordinator wake(key) coalesces newly recorded work by setting pendingWake = true on an active entry; when idle it starts options.drain(key, false). A successful run with a pending wake reuses the entry and starts one yielded successor drain; otherwise settlement either removes the key or creates a successor entry.
• 🟡 (15:59) Coordinator interrupt(key, cleanup = Effect.void) marks an active entry as stopping, clears its current pendingWake, interrupts the owner fiber, runs cleanup, requires the interrupted execution to have settled or throws exact error Interrupted Session execution did not settle, then removes the entry or starts a successor for work that arrived while stopping. Cleanup failure is propagated with Effect.failCause(cleanupExit.cause), and the stop sequence is uninterruptible.
• 🟡 (15:59) packages/core/src/session/runner/index.ts defines SessionRunner.RunError as LLMError | SessionRunnerModel.Error | MessageDecodeError | ContextSnapshotDecodeError | SystemContext.InitializationBlocked | ToolOutputStore.Error.
• 🟡 (15:59) SessionRunner.Interface.run performs one local continuation from already-recorded session history and accepts exact fields sessionID, force, executionID, ownerID, and optional recoveryInputID?: SessionMessage.ID; explicit runs perform one provider attempt even when no durable work is eligible.
• 🟡 (15:59) The runner service is declared as Context.Service<Service, Interface>()("@opencode/v2/SessionRunner").