openAgent

1# Effect TODO
2 
3Short roadmap for Effect cleanup in `packages/opencode`.
4 
5Current patterns and examples live in [`guide.md`](./guide.md). Error
6boundary migration details live in
7[`error-boundaries-plan.md`](./error-boundaries-plan.md). Test migration rules live in
8[`test/EFFECT_TEST_MIGRATION.md`](../../test/EFFECT_TEST_MIGRATION.md).
9Older deep-dive notes in this directory may still be useful, but treat
10this roadmap and the guide as the current entry points.
11 
12This is a planning map, not a verified inventory. Before starting a task,
13re-run a targeted `git grep` from current `dev` and update this file if
14the inventory changed.
15 
16## Priorities
17 
18```text
19P0  ERR + RENDER + HTTP
20    Make expected failures typed, render them well, and stop relying on
21    generic HTTP error guesswork.
22 
23P1  TEST
24    Convert touched tests to the ideal Effect test patterns from the guide.
25 
26P2  RF
27    Move mutable runtime flags into typed runtime/config services.
28 
29P3  GLOBAL
30    Make global paths explicit and remove import-time side effects.
31 
32P4  INST + BRIDGE
33    Remove ambient Instance coupling while keeping Promise/callback interop.
34 
35P5  PROC + FS
36    Replace raw process/filesystem edges with typed Effect services.
37 
38P6  OA
39    Shrink OpenAPI compatibility shims as source schemas improve.
40```
41 
42## Work Paths
43 
44- `ERR` Typed errors — replace legacy `NamedError.create(...)` and
45  `Effect.die(...)` for expected service failures with
46  `Schema.TaggedErrorClass` errors on the Effect error channel.
47  Shrinks: [`NamedError`](../../../core/src/util/error.ts) usage.
48- `RENDER` User-visible error rendering — preserve structured typed-error
49  details at CLI, HTTP, and tool boundaries.
50  Shrinks: opaque `Error: Name` rendering.
51- `HTTP` HTTP route cleanup — make route errors explicit instead of
52  relying on generic middleware to guess status/body from error names.
53  Shrinks: [`middleware/error.ts`](../../src/server/routes/instance/httpapi/middleware/error.ts)
54  and route-level compatibility shims.
55- `TEST` Effect test migration — use `testEffect`, `it.live`, and
56  `it.instance` with explicit layers.
57  Shrinks: Promise-style tests, sleeps, mutable global test flags.
58- `RF` RuntimeFlags / Flag deletion — move mutable
59  [`Flag`](../../../core/src/flag/flag.ts) reads into typed runtime/config
60  services.
61  Shrinks: [`flag.ts`](../../../core/src/flag/flag.ts),
62  [`test/fixture/flag.ts`](../../test/fixture/flag.ts).
63- `GLOBAL` Global paths / import side effects — make global path state
64  explicit and testable instead of mutable module state.
65  Shrinks: [`global.ts`](../../../core/src/global.ts) import-time side
66  effects, mutable `Global.Path` overrides, and its `Flag` dependency.
67- `INST` Instance context — keep project context explicit through Effect refs
68  and bridge boundaries.
69- `BRIDGE` Promise/callback interop — keep bridge helpers, but reduce
70  legacy ALS coupling.
71  Shrinks: ad hoc Promise/callback re-entry code.
72- `PROC` AppProcess migration — prefer `AppProcess.Service` over raw
73  process wrappers.
74  Shrinks: direct spawn callsites and legacy process helpers.
75- `FS` FSUtil migration — prefer `FSUtil.Service` over raw
76  filesystem APIs.
77  Shrinks: direct `fs` / `Bun.file` service callsites where inappropriate.
78- `RT` Runtime/facade cleanup — remove service-local `makeRuntime`
79  facades when not intentional.
80  Shrinks: async facade exports around services and
81  [`run-service.ts`](../../src/effect/run-service.ts) usage.
82- `OA` OpenAPI compatibility — tighten source schemas instead of
83  post-processing generated OpenAPI.
84  Shrinks: schema workaround blocks in
85  [`public.ts`](../../src/server/routes/instance/httpapi/public.ts).
86 
87## P0: Errors, Rendering, And HTTP
88 
89This should be the next big cleanup theme. The codebase is moving toward
90typed Effect failures, but the user-facing boundaries still leak old
91shapes and sometimes collapse rich errors into opaque strings.
92 
93### Problems
94 
95- Some expected service failures still use `NamedError.create(...)` or
96  collapse to `Effect.die(...)`. The storage/worktree/provider-auth
97  conversions are done; an inventory sweep is needed for the rest.
98- HTTP error middleware still guesses status codes from error names —
99  some entries (e.g. storage `NotFound`, provider auth) can now be
100  removed, but the middleware overall has not shrunk.
101- Route handlers and route groups do not consistently declare the public
102  error body they intend to expose.
103- Repeated route error translations do not yet have a clear home: some
104  should stay inline, some deserve tiny shared mapper helpers.
105 
106### Target Shape
107 
108- Services define expected failures with `Schema.TaggedErrorClass`.
109- Services export an `Error` union and include it in method return types.
110- Expected failures stay on the Effect error channel.
111- `Effect.die(...)` is reserved for defects: bugs, impossible states,
112  violated invariants, or final unknown-boundary fallbacks.
113- Inside `Effect.gen` / `Effect.fn`, use `yield* new MyError(...)` for
114  direct expected failures.
115- Domain services do not import HTTP status codes, `HttpApiError`, or
116  route-specific error schemas.
117- HTTP route groups make their public error contracts obvious.
118- Handlers map service errors to declared HTTP errors at the boundary.
119- Shared mapper helpers are only for repeated translations, not a giant
120  central registry of every domain error.
121- Generic HTTP middleware should shrink; it should not accumulate more
122  name-based domain knowledge.
123 
124### Recently completed
125 
126- [x] `RENDER-1` CLI tagged config error rendering (#27256, tests #27257).
127- [x] `ERR-1` [`storage/storage.ts`](../../src/storage/storage.ts) typed
128      `NotFoundError` (#27265) and removal of the server defect fallback
129      (#27287).
130- [x] `ERR-2` [`worktree/index.ts`](../../src/worktree/index.ts) typed
131      errors (#27296).
132- [x] `ERR-3` [`provider/auth.ts`](../../src/provider/auth.ts) typed
133      validation/oauth errors (#27301).
134- [x] `HTTP-1` Unknown-500 details no longer leaked (#27251); follow-up
135      to stop exposing named defects (#27471).
136- [x] Session message reads typed and made effectful (#27269, #27275,
137      #27280, #27291).
138- [x] Session HTTP error contracts tightened (#27308); busy-session
139      mapping centralized (#27375, #27473).
140- [x] Provider init (#27484) and LSP init (#27494) errors typed.
141 
142### First PR Candidates
143 
144- [ ] `HTTP-2` Audit one route group for explicit error contracts and
145      decide which mappings stay inline vs. shared helper.
146- [ ] `ERR-4` Sweep remaining `NamedError.create(...)` and
147      `Effect.die(...)` callsites for expected failures — re-run `git
148grep` to build a current inventory.
149- [ ] `RENDER-2` Audit CLI and TUI surfaces for any remaining opaque
150      `Error: Name` rendering of typed errors.
151 
152## P1: Tests
153 
154When touching tests, migrate them toward the ideal patterns in
155[`test/EFFECT_TEST_MIGRATION.md`](../../test/EFFECT_TEST_MIGRATION.md):
156 
157- Use `testEffect(...)` with explicit layers.
158- Prefer `it.instance(...)` for service tests that need an instance.
159- Prefer `it.live(...)` for real timers, filesystem mtimes, child
160  processes, git, locks, or other live integration behavior.
161- Avoid sleeps; wait on real events or deterministic state transitions.
162- Do not mutate `process.env` or mutable globals after layers are built.
163- Use explicit layer variants, such as `RuntimeFlags.layer(...)`, for
164  behavior changes.
165 
166## P2: RuntimeFlags / Flag Deletion
167 
168Recently completed:
169 
170- [x] Plugin/pure-mode flags moved to RuntimeFlags.
171- [x] Tool visibility flags moved to RuntimeFlags.
172- [x] Built-in websearch provider selection uses the same runtime flags as
173      tool visibility.
174- [x] Removed global default-plugin disabling from test preload.
175- [x] `RF-1` Reference reads routed through runtime flags (#27318).
176- [x] `RF-2` Plan-mode prompt read routed through runtime flags (#27320).
177- [x] `RF-3` Event-system reads routed through runtime flags (#27323).
178- [x] `RF-4` Workspaces reads routed through runtime flags for session
179      (#27335), sync (#27336), and control-plane (#27337).
180- [x] LLM client (#27368) and installation client (#27369) routed
181      through runtime flags.
182- [x] TUI plugin runtime flags simplified (#27506).
183- [x] Background-subagents flag moved to RuntimeFlags, then removed
184      (`refactor(task): use runtime flag for background subagents`,
185      `refactor(flags): remove background subagents flag`).
186 
187Remaining cleanup:
188 
189- [ ] Sweep lingering `Flag.*` reads — many CLI/TUI/config/observability
190      callsites still import [`flag.ts`](../../../core/src/flag/flag.ts).
191      Decide per-callsite whether to route through RuntimeFlags, accept
192      as legitimate env/config boundary, or migrate to typed `Config`.
193- [ ] Delete [`test/fixture/flag.ts`](../../test/fixture/flag.ts) once
194      tests no longer mutate `Flag`.
195- [ ] Delete [`flag.ts`](../../../core/src/flag/flag.ts) once no packages
196      import it.
197 
198## P3: Global Paths
199 
200[`global.ts`](../../../core/src/global.ts) is real connective tissue, not
201just cosmetic ugliness. It currently mixes path calculation, import-time
202directory creation, `Flock` setup, mutable exported `Path` state, and a
203`Flag` dependency.
204 
205Problems to reduce:
206 
207- Importing the module creates directories.
208- Tests override `Global.Path` by mutating exported module state.
209- Most callers use `Global.Path` directly instead of the Effect service.
210- `Global.make()` still reads mutable `Flag.OPENCODE_CONFIG_DIR`.
211 
212Next PR candidates:
213 
214- [ ] Replace mutable `Global.Path` test overrides with explicit test
215      layers or scoped helpers.
216- [ ] Move directory creation and `Flock` setup behind an explicit init
217      boundary where possible.
218- [ ] Remove the `Flag` dependency from global path resolution.
219 
220## P4: Instance And Bridge
221 
222Instance context migration is complete for the legacy sync shim. Promise and callback interop continues through [`effect/bridge.ts`](../../src/effect/bridge.ts).
223 
224Current rules:
225 
226- Effect services read instance data from `InstanceRef`, `WorkspaceRef`, `InstanceState`, or explicit arguments.
227- Plain JavaScript callback boundaries use `EffectBridge` or explicit context arguments.
228- Runtime entrypoints must provide refs explicitly when they are instance-scoped.
229 
230## Lower Priority Tracks
231 
232- `PROC` / `FS` — continue AppProcess and FSUtil migrations as
233  focused PRs when touching relevant files.
234- `RT` — remove service-local runtime facades only when they are not an
235  intentional boundary.
236- `OA` — shrink [`public.ts`](../../src/server/routes/instance/httpapi/public.ts)
237  by tightening source schemas one workaround at a time.
238- `fetch` → `HttpClient` — migrate raw fetch callsites when the caller is
239  already effectful or being effectified.
240- `Tools` — remaining tool cleanup is narrow: `webfetch` HTML extraction
241  and `shell` raw stream/promise edges.
242