Distillation

Date: Sep 14, 2026

• 🟡 (09:08) /home/byk/Code/opencode/packages/sdk-next/src/opencode.ts defines create as Effect.fn("OpenCode.create"); it obtains Scope.Scope, creates a Layer.makeMemoMap, and builds AppNodeBuilder.build(LayerNode.group([ApplicationTools.node, PermissionSaved.node])) with Layer.buildWithMemoMap(...).
• 🟡 (09:08) create extracts ApplicationTools.Service and PermissionSaved.Service, then acquires an embedded web handler via HttpRouter.toWebHandler(createEmbeddedRoutes().pipe(HttpRouter.provideRequest(Layer.succeed(PermissionSaved.Service, permissions)), Layer.provide(HttpServer.layerServices)), { disableLogger: true, memoMap }); release calls Effect.promise(web.dispose).
• 🟡 (09:08) /home/byk/Code/opencode/packages/sdk-next/src/opencode.ts implements a custom fetch by passing new Request(input, init) to web.handler, adds preconnect: () => undefined, and creates the client with OpenCode.make({ baseUrl: "http://opencode.local" }), FetchHttpClient.layer, and FetchHttpClient.Fetch.
• 🟡 (09:08) The SDK create result spreads the OpenCode client and exposes tools: { register: tools.register }; Interface is Effect.Success<ReturnType<typeof create>>, Service uses identifier "@opencode-ai/sdk-next/OpenCode", and layer is Layer.effect(Service, create()).
• 🟡 (09:08) /home/byk/Code/opencode/specs/v2/session.md specifies sessions.create({ id?, location, ... }) and sessions.prompt({ id?, sessionID, prompt, delivery?, resume? }); session interruption affects active execution on the current process.
• 🟡 (09:08) The v2 Session design makes SessionExecution and read-side SessionStore process-global, while SessionRunner, catalog, model resolver, tool registry, permission state, and filesystem are cached per Location; no layer takes a Session ID. Omitted Location.workspaceID means implicit-local placement, while explicit workspace identity is reserved for future placement semantics.
• 🔴 (09:08) User stated abandoned side effects are “never silently replayed.” The local runner must durably fail local tools still projected as running from a previous process with Tool execution interrupted before assembling the next provider request.
• 🟡 (09:08) The local runner design issues one explicit llm.stream(request) per provider turn, durably projects each complete local tool call before eagerly starting its structured child execution, awaits every started tool fiber after provider-stream closure, and reloads projected history once before continuation.
• 🟡 (09:08) Promoting any new user input resets the selected agent’s configured provider-turn allowance; multiple steers promoted at one boundary reset it once. Tool settlement events include the owning assistant message ID because provider-local call IDs may repeat across turns.
• 🟡 (09:08) Context Epoch initialization requires the first complete observation before pending prompts become model-visible. If initial context is temporarily unavailable, execution stops while the prompt remains pending and retryable. On later provider turns, eligible input is promoted before current context sources are reconciled at the safe boundary; changed context becomes one durable chronological System message, whose event commit atomically advances the epoch snapshot.
• 🟡 (09:08) Agent and model selection are provider-turn scoped: a switch admitted after the current safe provider-turn boundary applies to the next provider turn without restarting the current turn or replacing the baseline. Agent-specific skill guidance remains a Context Source and changed guidance is admitted as a chronological System message.
• 🟡 (09:08) A completed compaction causes the next provider attempt to render a fresh baseline directly from current complete context. A Session move clears the epoch so the destination Location initializes a complete baseline on its next run.
• 🟡 (09:08) The v2 Session spec says watcher-backed per-file caching should be considered only if measurements show direct safe-boundary observation is too expensive.
• 🔴 (09:08) User stated provider-native assistant, reasoning, and tool messages “never survive across the boundary.” Compaction retains the full durable transcript but replaces its active model representation with one hidden checkpoint containing a structured rolling summary and token-bounded serialized recent context, preventing signature and encrypted-reasoning failures when the earlier prefix changes.
• 🟡 (09:08) Overflow handling permits one overflow-triggered compaction when a provider rejects a request for context overflow before durable assistant output or tool execution, even if the local estimate did not predict pressure. A completed checkpoint rebuilds the same logical provider turn with one remaining physical attempt; a second overflow, unavailable compaction, or overflow after durable output becomes the ordinary terminal failure. Deterministic old tool-result pruning remains a separate follow-up.
• 🔴 (09:08) User stated recovery “never loops or replays partial side effects.”
• 🟡 (09:08) The coordinator’s active registry backs sessions.active() and includes only foreground Session drains owned by the current process; background subagents and tasks do not add parent Sessions. This snapshot is runtime-only and is empty after process restart.
• 🟡 (09:08) Durable event-tail wakeups are advisory and edge-triggered. Each active tail has one sliding-capacity-1 dirty signal for its aggregate and re-queries SQLite after a wake; repeated commits coalesce while busy because durable rows preserve every event and sequence. The dirty signal must be subscribed and registered before historical replay and removed when the tail closes, preventing missed commits during replay handoff and avoiding wake state for inactive aggregates.
• 🟡 (09:08) The finite history API deliberately reads one authorized Session aggregate and does not alter global Event publication; any global multi-Session event stream must be designed separately.
• 🟡 (09:08) Search of /home/byk/Code/opencode/packages/core/src/session/runner/llm.ts found provider-turn continuation support marked complete for durable user steering during an active provider turn, while continuation for compaction or another required continuation condition remained unchecked in the file comment.
• 🟡 (09:08) /home/byk/Code/opencode/packages/core/src/session/runner/llm.ts defines TurnTransitionError variants { _tag: "ContinueAfterCompaction"; step: number } and { _tag: "ContinueAfterOverflowCompaction"; step: number }, helper constructors continueAfterCompaction(step) and an overflow counterpart, plus handling for "ContinueAfterOverflowCompaction" around lines 367 and 382.
• 🟡 (09:08) Synthetic-message search found SessionEvent.Synthetic projected in /home/byk/Code/opencode/packages/core/src/session/projector.ts; "session.next.synthetic" handled by /home/byk/Code/opencode/packages/core/src/session/message-updater.ts; "synthetic" converted in /home/byk/Code/opencode/packages/core/src/session/runner/to-llm-message.ts; and compaction serialization in /home/byk/Code/opencode/packages/core/src/session/compaction.ts as [Synthetic context]: ${message.text}.
• 🟡 (09:09) A 12-match search found the durable event type "session.next.synthetic" in /home/byk/Code/opencode/packages/schema/src/session-event.ts, generated client types in /home/byk/Code/opencode/packages/client/src/generated/types.ts and /home/byk/Code/opencode/packages/sdk/js/src/v2/gen/types.gen.ts, publishing tests in /home/byk/Code/opencode/packages/core/test/session-projector.test.ts and /home/byk/Code/opencode/packages/core/test/session-prompt.test.ts, and runtime handling in session/projector.ts and session/message-updater.ts.
• 🟡 (09:09) /home/byk/Code/opencode/packages/core/test/session-projector.test.ts test "updates only the newest incomplete assistant projection" inserts msg_assistant_1 at sequence 0 and msg_assistant_2 at sequence 1, publishes SessionEvent.Step.Ended for msg_assistant_2 with timestamp DateTime.makeUnsafe(1), finish: "stop", cost: 0, and all token counts 0, then verifies the first message remains incomplete while the second receives finish: "stop" and time.completed: DateTime.makeUnsafe(1).
• 🟡 (09:09) /home/byk/Code/opencode/packages/core/test/session-projector.test.ts test "does not revive a stale incomplete assistant projection" inserts incomplete msg_assistant_stale at sequence 0 and completed msg_assistant_completed at sequence 1 with creation time 1 and completion time 2; publishing SessionEvent.Text.Started for the completed message at time 3 with textID: "text-stale" adds an empty assistant-text part only to msg_assistant_completed, while msg_assistant_stale remains incomplete with empty content.
• 🟡 (09:09) The v2 Session spec states projected hosted tools preserve call-side and settlement-side provider metadata separately so settlement and interruption recovery cannot erase continuation identifiers. Provider-native reasoning and metadata replay only when the historical assistant model matches the selected continuation model; after a model switch, visible reasoning remains ordinary assistant text and provider-native metadata is omitted.
• 🟡 (09:09) Compaction lifecycle design uses session.next.compaction.started.1 to durably identify an attempt; compaction deltas are live-only progress; and session.next.compaction.ended.1 durably stores the final summary and serialized recent context. Only the completed event projects a model-visible compaction message, so failed or interrupted attempts leave the prior history boundary active.
• 🟡 (09:09) Post-crash continuation recovery is explicitly deferred in /home/byk/Code/opencode/specs/v2/session.md: a wake does not infer that ambiguous provider work is safe to retry after input promotion, while explicit run may deliberately continue from durable projected history. A future recovery slice must jointly model provider-dispatch ambiguity, required continuation, queued-input promotion, retry policy, and visible recovery status without assuming an enclosing durable execution identity.
• 🟡 (09:09) /home/byk/Code/opencode/specs/v2/schema-changelog.md requires preserving full durable history while compaction changes only the active model representation, and says background bash should be reintroduced only with durable status observation, completion delivery, and explicit cancellation semantics.