Skip to content

Commit 0c9cfe9

Browse files
authored
refactor(instance): remove legacy runtime fallback (anomalyco#27757)
1 parent 9975c1e commit 0c9cfe9

47 files changed

Lines changed: 939 additions & 1256 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎packages/opencode/AGENTS.md‎

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -128,17 +128,8 @@ See `specs/effect/migration.md` for the compact pattern reference and examples.
128128

129129
Use `Effect.cached` when multiple concurrent callers should share a single in-flight computation rather than storing `Fiber | undefined` or `Promise | undefined` manually. See `specs/effect/migration.md` for the full pattern.
130130

131-
## Instance.bind — ALS for native callbacks
131+
## Callback boundaries
132132

133-
`Instance.bind(fn)` captures the current Instance AsyncLocalStorage context and restores it synchronously when called.
133+
Use `EffectBridge` for native or external callbacks (`@parcel/watcher`, `node-pty`, native `fs.watch`, plugin callbacks, etc.) that need to re-enter Effect services with instance/workspace context.
134134

135-
Use it for native addon callbacks (`@parcel/watcher`, `node-pty`, native `fs.watch`, etc.) that need to call `Bus.publish` or anything that reads `Instance.directory`.
136-
137-
You do not need it for `setTimeout`, `Promise.then`, `EventEmitter.on`, or Effect fibers.
138-
139-
```typescript
140-
const cb = Instance.bind((err, evts) => {
141-
Bus.publish(MyEvent, { ... })
142-
})
143-
nativeAddon.subscribe(dir, cb)
144-
```
135+
Plain async code should pass explicit context or stay inside an Effect fiber; do not add ambient instance context shims.

‎packages/opencode/specs/effect/facades.md‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ Current status on this branch:
66

77
- `src/` has 5 `makeRuntime(...)` call sites total.
88
- 2 are intentionally excluded from this checklist: `src/bus/index.ts` and `src/effect/cross-spawn-spawner.ts`.
9-
- 1 is tracked primarily by the instance-context migration rather than facade removal: `src/project/instance.ts`.
109
- That leaves 2 live runtime-backed service facades still worth tracking here: `src/npm/index.ts` and `src/cli/cmd/tui/config/tui.ts`.
1110

1211
Recent progress:
@@ -18,7 +17,6 @@ Recent progress:
1817

1918
- `src/cli/cmd/tui/config/tui.ts` still exports `makeRuntime(...)` plus async facade helpers for `get()` and `waitForDependencies()`.
2019
- `src/npm/index.ts` still exports `makeRuntime(...)` plus async facade helpers for `install()`, `add()`, `outdated()`, and `which()`.
21-
- `src/project/instance.ts` still uses a dedicated runtime for project boot, but that file is really part of the broader legacy instance-context transition tracked in `instance-context.md`.
2220

2321
## Completed Batches
2422

@@ -192,7 +190,6 @@ Most of the original facade-removal backlog is already done. The practical remai
192190

193191
1. remove the `Npm` runtime-backed facade from `src/npm/index.ts`
194192
2. remove the `TuiConfig` runtime-backed facade from `src/cli/cmd/tui/config/tui.ts`
195-
3. keep `src/project/instance.ts` in the separate instance-context migration, not this checklist
196193

197194
## Checklist
198195

‎packages/opencode/specs/effect/guide.md‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -197,13 +197,9 @@ For background loops, use `Effect.repeat` or `Effect.schedule` with
197197

198198
[`EffectBridge`](../../src/effect/bridge.ts) is the sanctioned helper for
199199
Promise/callback interop that needs to preserve instance/workspace context.
200-
Keep it, but reduce its dependency on legacy `Instance.current` /
201-
`Instance.restore` over time.
202-
203-
`Instance.bind` / `Instance.restore` are transitional legacy tools. Use
204-
them only for native callbacks that still require legacy ALS context. Do
205-
not use them for `setTimeout`, `Promise.then`, `EventEmitter.on`, or
206-
Effect fibers.
200+
It preserves explicit `InstanceRef` / `WorkspaceRef` context for effects run
201+
through the bridge. Plain JS callbacks that need instance data should receive
202+
that data explicitly.
207203

208204
## Testing
209205

Lines changed: 9 additions & 305 deletions
Original file line numberDiff line numberDiff line change
@@ -1,309 +1,13 @@
1-
# Instance context migration
1+
# Instance Context
22

3-
Practical plan for retiring the promise-backed / ALS-backed `Instance` helper in `src/project/instance.ts` and moving instance selection fully into Effect-provided scope.
3+
Instance selection is now Effect-provided context.
44

5-
## Goal
5+
Use these APIs:
66

7-
End state:
7+
- `InstanceRef` for the current project context.
8+
- `WorkspaceRef` for the current workspace id.
9+
- `InstanceState.context` / `InstanceState.directory` inside Effect services that require an instance.
10+
- `InstanceStore` at entry boundaries that need to load, reload, or dispose project contexts.
11+
- `EffectBridge` for native, plugin, or plain JavaScript callback boundaries that need to re-enter Effect with captured refs.
812

9-
- request, CLI, TUI, and tool entrypoints shift into an instance through Effect, not `Instance.provide(...)`
10-
- Effect code reads the current instance from `InstanceRef` or its eventual replacement, not from ALS-backed sync getters
11-
- per-directory boot, caching, and disposal are scoped Effect resources, not a module-level `Map<string, Promise<InstanceContext>>`
12-
- ALS remains only as a temporary bridge for native callback APIs that fire outside the Effect fiber tree
13-
14-
## Current split
15-
16-
Today `src/project/instance.ts` still owns two separate concerns:
17-
18-
- ambient current-instance context through `LocalContext` / `AsyncLocalStorage`
19-
- per-directory boot and deduplication through `cache: Map<string, Promise<InstanceContext>>`
20-
21-
At the same time, the Effect side already exists:
22-
23-
- `src/effect/instance-ref.ts` provides `InstanceRef` and `WorkspaceRef`
24-
- `src/effect/run-service.ts` already attaches those refs when a runtime starts inside an active instance ALS context
25-
- `src/effect/instance-state.ts` already prefers `InstanceRef` and only falls back to ALS when needed
26-
27-
That means the migration is not "invent instance context in Effect". The migration is "stop relying on the legacy helper as the primary source of truth".
28-
29-
## End state shape
30-
31-
Near-term target shape:
32-
33-
```ts
34-
InstanceScope.with({ directory, workspaceID }, effect)
35-
```
36-
37-
Responsibilities of `InstanceScope.with(...)`:
38-
39-
- resolve `directory`, `project`, and `worktree`
40-
- acquire or reuse the scoped per-directory instance environment
41-
- provide `InstanceRef` and `WorkspaceRef`
42-
- run the caller's Effect inside that environment
43-
44-
Code inside the boundary should then do one of these:
45-
46-
```ts
47-
const ctx = yield * InstanceState.context
48-
const dir = yield * InstanceState.directory
49-
```
50-
51-
Long-term, once `InstanceState` itself is replaced by keyed layers / `LayerMap`, those reads can move to an `InstanceContext` service without changing the outer migration order.
52-
53-
## Migration phases
54-
55-
### Phase 1: stop expanding the legacy surface
56-
57-
Rules for all new code:
58-
59-
- do not add new `Instance.directory`, `Instance.worktree`, `Instance.project`, or `Instance.current` reads inside Effect code
60-
- do not add new `Instance.provide(...)` boundaries unless there is no Effect-native seam yet
61-
- use `InstanceState.context`, `InstanceState.directory`, or an explicit `ctx` parameter inside Effect code
62-
63-
Success condition:
64-
65-
- the file inventory below only shrinks from here
66-
67-
### Phase 2: remove direct sync getter reads from Effect services
68-
69-
Convert Effect services first, before replacing the top-level boundary. These modules already run inside Effect and mostly need `yield* InstanceState.context` or a yielded `ctx` instead of ambient sync access.
70-
71-
Primary batch, highest payoff:
72-
73-
- `src/file/index.ts`
74-
- `src/lsp/server.ts`
75-
- `src/worktree/index.ts`
76-
- `src/file/watcher.ts`
77-
- `src/format/formatter.ts`
78-
- `src/session/index.ts`
79-
- `src/project/vcs.ts`
80-
81-
Mechanical replacement rule:
82-
83-
- `Instance.directory` -> `ctx.directory` or `yield* InstanceState.directory`
84-
- `Instance.worktree` -> `ctx.worktree`
85-
- `Instance.project` -> `ctx.project`
86-
87-
Do not thread strings manually through every public method if the service already has access to Effect context.
88-
89-
### Phase 3: convert entry boundaries to provide instance refs directly
90-
91-
After the service bodies stop assuming ALS, move the top-level boundaries to shift into Effect explicitly.
92-
93-
Main boundaries:
94-
95-
- HTTP server middleware and experimental `HttpApi` entrypoints
96-
- CLI commands
97-
- TUI worker / attach / thread entrypoints
98-
- tool execution entrypoints
99-
100-
These boundaries should become Effect-native wrappers that:
101-
102-
- decode directory / workspace inputs
103-
- resolve the instance context once
104-
- provide `InstanceRef` and `WorkspaceRef`
105-
- run the requested Effect
106-
107-
At that point `Instance.provide(...)` becomes a legacy adapter instead of the normal code path.
108-
109-
### Phase 4: replace promise boot cache with scoped instance runtime
110-
111-
Once boundaries and services both rely on Effect context, replace the module-level promise cache in `src/project/instance.ts`.
112-
113-
Target replacement:
114-
115-
- keyed scoped runtime or keyed layer acquisition for each directory
116-
- reuse via `ScopedCache`, `LayerMap`, or another keyed Effect resource manager
117-
- cleanup performed by scope finalizers instead of `disposeAll()` iterating a Promise map
118-
119-
This phase should absorb the current responsibilities of:
120-
121-
- `cache` in `src/project/instance.ts`
122-
- `boot(...)`
123-
- most of `disposeInstance(...)`
124-
- manual `reload(...)` / `disposeAll()` fan-out logic
125-
126-
### Phase 5: shrink ALS to callback bridges only
127-
128-
Keep ALS only where a library invokes callbacks outside the Effect fiber tree and we still need to call code that reads instance context synchronously.
129-
130-
Known bridge cases today:
131-
132-
- `src/file/watcher.ts`
133-
- `src/session/llm.ts`
134-
- some LSP and plugin callback paths
135-
136-
If those libraries become fully wrapped in Effect services, the remaining `Instance.bind(...)` uses can disappear too.
137-
138-
### Phase 6: delete the legacy sync API
139-
140-
Only after earlier phases land:
141-
142-
- remove broad use of `Instance.current`, `Instance.directory`, `Instance.worktree`, `Instance.project`
143-
- reduce `src/project/instance.ts` to a thin compatibility shim or delete it entirely
144-
- remove the ALS fallback from `InstanceState.context`
145-
146-
## Inventory of direct legacy usage
147-
148-
Direct legacy usage means any source file that still calls one of:
149-
150-
- `Instance.current`
151-
- `Instance.directory`
152-
- `Instance.worktree`
153-
- `Instance.project`
154-
- `Instance.provide(...)`
155-
- `Instance.bind(...)`
156-
- `Instance.restore(...)`
157-
- `Instance.reload(...)`
158-
- `Instance.dispose()` / `Instance.disposeAll()`
159-
160-
Current total: `56` files in `packages/opencode/src`.
161-
162-
### Core bridge and plumbing
163-
164-
These files define or adapt the current bridge. They should change last, after callers have moved.
165-
166-
- `src/project/instance.ts`
167-
- `src/effect/run-service.ts`
168-
- `src/effect/instance-state.ts`
169-
- `src/project/bootstrap.ts`
170-
- `src/config/config.ts`
171-
172-
Migration rule:
173-
174-
- keep these as compatibility glue until the outer boundaries and inner services stop depending on ALS
175-
176-
### HTTP and server boundaries
177-
178-
These are the current request-entry seams that still create or consume instance context through the legacy helper.
179-
180-
- `src/server/routes/instance/middleware.ts`
181-
- `src/server/routes/instance/index.ts`
182-
- `src/server/routes/instance/project.ts`
183-
- `src/server/routes/control/workspace.ts`
184-
- `src/server/routes/instance/file.ts`
185-
- `src/server/routes/instance/experimental.ts`
186-
- `src/server/routes/global.ts`
187-
188-
Migration rule:
189-
190-
- move these to explicit Effect entrypoints that provide `InstanceRef` / `WorkspaceRef`
191-
- do not move these first; first reduce the number of downstream handlers and services that still expect ambient ALS
192-
193-
### CLI and TUI boundaries
194-
195-
These commands still enter an instance through `Instance.provide(...)` or read sync getters directly.
196-
197-
- `src/cli/bootstrap.ts`
198-
- `src/cli/cmd/agent.ts`
199-
- `src/cli/cmd/debug/agent.ts`
200-
- `src/cli/cmd/debug/ripgrep.ts`
201-
- `src/cli/cmd/github.ts`
202-
- `src/cli/cmd/import.ts`
203-
- `src/cli/cmd/mcp.ts`
204-
- `src/cli/cmd/models.ts`
205-
- `src/cli/cmd/plug.ts`
206-
- `src/cli/cmd/pr.ts`
207-
- `src/cli/cmd/providers.ts`
208-
- `src/cli/cmd/stats.ts`
209-
- `src/cli/cmd/tui/attach.ts`
210-
- `src/cli/cmd/tui/plugin/runtime.ts`
211-
- `src/cli/cmd/tui/thread.ts`
212-
- `src/cli/cmd/tui/worker.ts`
213-
214-
Migration rule:
215-
216-
- converge these on one shared `withInstance(...)` Effect entry helper instead of open-coded `Instance.provide(...)`
217-
- after that helper is proven, inline the legacy implementation behind an Effect-native scope provider
218-
219-
### Tool boundary code
220-
221-
These tools mostly use direct getters for path resolution and repo-relative display logic.
222-
223-
- `src/tool/apply_patch.ts`
224-
- `src/tool/bash.ts`
225-
- `src/tool/edit.ts`
226-
- `src/tool/lsp.ts`
227-
- `src/tool/plan.ts`
228-
- `src/tool/read.ts`
229-
- `src/tool/write.ts`
230-
231-
Migration rule:
232-
233-
- expose the current instance as an explicit Effect dependency for tool execution
234-
- keep path logic local; avoid introducing another global singleton for tool state
235-
236-
### Effect services still reading ambient instance state
237-
238-
These modules are already the best near-term migration targets because they are in Effect code but still read sync getters from the legacy helper.
239-
240-
- `src/agent/agent.ts`
241-
- `src/cli/cmd/tui/config/tui-migrate.ts`
242-
- `src/file/index.ts`
243-
- `src/file/watcher.ts`
244-
- `src/format/formatter.ts`
245-
- `src/lsp/client.ts`
246-
- `src/lsp/index.ts`
247-
- `src/lsp/server.ts`
248-
- `src/mcp/index.ts`
249-
- `src/project/vcs.ts`
250-
- `src/provider/provider.ts`
251-
- `src/pty/index.ts`
252-
- `src/session/session.ts`
253-
- `src/session/instruction.ts`
254-
- `src/session/llm.ts`
255-
- `src/session/system.ts`
256-
- `src/sync/index.ts`
257-
- `src/worktree/index.ts`
258-
259-
Migration rule:
260-
261-
- replace direct getter reads with `yield* InstanceState.context` or a yielded `ctx`
262-
- isolate `Instance.bind(...)` callers and convert only the truly callback-driven edges to bridge mode
263-
264-
### Highest-churn hotspots
265-
266-
Current highest direct-usage counts by file:
267-
268-
- `src/file/index.ts` - `18`
269-
- `src/lsp/server.ts` - `14`
270-
- `src/worktree/index.ts` - `12`
271-
- `src/file/watcher.ts` - `9`
272-
- `src/cli/cmd/mcp.ts` - `8`
273-
- `src/format/formatter.ts` - `8`
274-
- `src/tool/apply_patch.ts` - `8`
275-
- `src/cli/cmd/github.ts` - `7`
276-
277-
These files should drive the first measurable burn-down.
278-
279-
## Recommended implementation order
280-
281-
1. Migrate direct getter reads inside Effect services, starting with `file`, `lsp`, `worktree`, `format`, and `session`.
282-
2. Add one shared Effect-native boundary helper for CLI / tool / HTTP entrypoints so we stop open-coding `Instance.provide(...)`.
283-
3. Move experimental `HttpApi` entrypoints to that helper so the new server stack proves the pattern.
284-
4. Convert remaining CLI and tool boundaries.
285-
5. Replace the promise cache with a keyed scoped runtime or keyed layer map.
286-
6. Delete ALS fallback paths once only callback bridges still depend on them.
287-
288-
## Definition of done
289-
290-
This migration is done when all of the following are true:
291-
292-
- new requests and commands enter an instance by providing Effect context, not ALS
293-
- Effect services no longer read `Instance.directory`, `Instance.worktree`, `Instance.project`, or `Instance.current`
294-
- `Instance.provide(...)` is gone from normal request / CLI / tool execution
295-
- per-directory boot and disposal are handled by scoped Effect resources
296-
- `Instance.bind(...)` is either gone or confined to a tiny set of native callback adapters
297-
298-
## Tracker and worktree
299-
300-
Active tracker items:
301-
302-
- `lh7l73` - overall `HttpApi` migration
303-
- `yobwlk` - remove direct `Instance.*` reads inside Effect services
304-
- `7irl1e` - replace `InstanceState` / legacy instance caching with keyed Effect layers
305-
306-
Dedicated worktree for this transition:
307-
308-
- path: `/Users/kit/code/open-source/opencode-worktrees/instance-effect-shift`
309-
- branch: `kit/instance-effect-shift`
13+
Do not add new ambient instance globals. Promise and callback boundaries should either stay in Effect, use `EffectBridge`, or pass the required context explicitly.

‎packages/opencode/specs/effect/loose-ends.md‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,6 @@ Small follow-ups that do not fit neatly into the main facade, route, tool, or sc
2424
- [ ] `cli/cmd/tui/config/tui.ts` - switch TUI config loading from async `ConfigPaths.*` wrappers to the `ConfigPaths.Service` once that service exists.
2525
- [ ] `cli/cmd/tui/config/tui-migrate.ts` - decide whether to leave this as a plain async module using wrapper functions or effectify it fully after `ConfigPaths.Service` lands.
2626

27-
## Instance cleanup
28-
29-
- [ ] `project/instance.ts` - keep shrinking the legacy ALS / Promise cache after the remaining `Instance.*` callers move over.
30-
3127
## Notes
3228

3329
- Prefer small, semantics-preserving config migrations. Config precedence, legacy key migration, and plugin origin tracking are easy to break accidentally.

0 commit comments

Comments
 (0)