openAgent

1# Typed Error Migration
2 
3This note expands the `ERR`, `RENDER`, and `HTTP` tracks from
4[`todo.md`](./todo.md). It is the current reference for expected failures,
5typed service errors, and HTTP error boundaries.
6 
7For the migration architecture and queue, see
8[`error-boundaries-plan.md`](./error-boundaries-plan.md).
9 
10## Goal
11 
12- Expected service failures live on the Effect error channel.
13- Service interfaces expose those failures in their return types.
14- Domain errors are authored with `Schema.TaggedErrorClass`.
15- `Effect.die(...)` is reserved for defects: bugs, impossible states,
16  violated invariants, and final unknown-boundary fallbacks.
17- HTTP status codes and public wire bodies are handled at HTTP route
18  boundaries, not inside service modules.
19- User-facing boundaries render useful structured error details instead of
20  opaque `Error: SomeName` strings.
21 
22## Service Error Shape
23 
24```ts
25export class SessionBusyError extends Schema.TaggedErrorClass<SessionBusyError>()("SessionBusyError", {
26  sessionID: SessionID,
27  message: Schema.String,
28}) {}
29 
30export type Error = Storage.Error | SessionBusyError
31 
32export interface Interface {
33  readonly get: (id: SessionID) => Effect.Effect<Info, Error>
34}
35```
36 
37Rules:
38 
39- Use `Schema.TaggedErrorClass` for expected domain failures.
40- Export a domain-level `Error` union from each service module.
41- Put expected errors in service method signatures.
42- Use `yield* new DomainError(...)` for direct early failures in
43  `Effect.gen` / `Effect.fn`.
44- Use `Schema.Defect` for unknown cause fields when preserving the cause is
45  useful for logs or callers.
46- Use `Effect.try(...)`, `Effect.tryPromise(...)`, `Effect.mapError`,
47  `Effect.catchTag`, and `Effect.catchTags` to translate external
48  failures into domain errors.
49- Do not use `throw`, `Effect.die(...)`, or `catchDefect` for expected
50  user, IO, validation, missing-resource, auth, provider, worktree, or
51  busy-state failures.
52 
53## HTTP Boundary Shape
54 
55Service modules stay transport-agnostic. They should not import HTTP
56status codes, `HttpApiError`, `HttpServerResponse`, or route-specific
57error schemas.
58 
59HTTP handlers translate service errors into public endpoint errors:
60 
61```ts
62const get = Effect.fn("SessionHttpApi.get")(function* (ctx: { params: { sessionID: SessionID } }) {
63  return yield* session
64    .get(ctx.params.sessionID)
65    .pipe(Effect.catchTag("StorageNotFoundError", () => notFound("Session not found")))
66})
67```
68 
69Endpoint definitions declare which public errors can be emitted. Public
70HTTP error schemas carry their response status with `httpApiStatus` or the
71equivalent HttpApi schema annotation.
72 
73Effect's own HttpApi examples follow this pattern:
74 
75```ts
76export class Unauthorized extends Schema.TaggedErrorClass<Unauthorized>()(
77  "Unauthorized",
78  { message: Schema.String },
79  { httpApiStatus: 401 },
80) {}
81 
82export class Authorization extends HttpApiMiddleware.Service<
83  Authorization,
84  {
85    provides: CurrentUser
86  }
87>()("app/Authorization", {
88  security: { bearer: HttpApiSecurity.bearer },
89  error: Unauthorized,
90}) {}
91```
92 
93Endpoint-level errors use the same idea:
94 
95```ts
96export class ConfigApiError extends Schema.ErrorClass<ConfigApiError>("ConfigApiError")(
97  {
98    name: Schema.Union(Schema.Literal("ConfigInvalidError"), Schema.Literal("ConfigJsonError")),
99    data: Schema.Struct({ message: Schema.optional(Schema.String), path: Schema.String }),
100  },
101  { httpApiStatus: 400 },
102) {}
103 
104HttpApiEndpoint.get("get", "/config", {
105  success: Config.Info,
106  error: ConfigApiError,
107})
108```
109 
110The service error and HTTP error may be the same class only when the wire
111shape is intentionally public. Use separate HTTP error schemas when the
112service error contains internals, low-level causes, retry hints, or data
113that should not be exposed to API clients.
114 
115Do not map every domain error into one universal HTTP error class. Prefer a
116small public error vocabulary by route group: shared shapes like
117`ApiNotFoundError`, route-specific shapes like `ConfigApiError`, and built-in
118empty `HttpApiError.*` only when an empty/no-content body is the intended SDK
119contract.
120 
121## Mapping Guidance
122 
123- Keep one-off translations inline in the handler.
124- Extract tiny shared helpers when the same translation repeats across a
125  route group.
126- Do not create one giant `unknown -> status` mapper.
127- Do not grow generic HTTP middleware into a registry of domain errors.
128- Preserve existing public `{ name, data }` bodies until a deliberate
129  breaking API change.
130- Use built-in `HttpApiError.*` only when its generated body and SDK
131  surface are intentionally the public contract.
132- Prefer `Schema.ErrorClass` for public HTTP error bodies whose wire shape is
133  not the same as the internal domain error shape.
134- Prefer `Schema.TaggedErrorClass` for service/domain errors and middleware
135  errors that are naturally tagged by `_tag`.
136- If preserving a legacy `{ name, data }` body, model that shape explicitly in
137  the public API error schema instead of relying on `NamedError.toObject()` in
138  generic middleware.
139 
140## User-Facing Rendering
141 
142HTTP serialization and user rendering are separate boundaries. The server
143should send structured public errors; CLI and TUI code should format those
144structures through one shared formatter.
145 
146For SDK calls using `{ throwOnError: true }`, the generated client may wrap the
147decoded response body in an `Error`. The original body should remain available
148under `error.cause.body`; `FormatError` is the right place to unwrap and render
149that body. TUI aggregation helpers should call `FormatError` first, then fall
150back to generic `Error.message` / string rendering.
151 
152When several parallel startup requests fail from the same underlying issue,
153group identical rendered messages and list the affected request names once.
154For example:
155 
156```text
157Configuration is invalid at /path/to/opencode.json
158↳ Expected object, got "not-object" provider.bad.options
159Affected startup requests: config.providers, provider.list, app.agents, config.get
160```
161 
162## Middleware Guidance
163 
164HTTP middleware should be cross-cutting: auth, context, schema decode
165formatting, routing, and final unknown-defect fallback.
166 
167The current compatibility middleware still knows about some legacy domain
168errors. As route groups declare expected errors and handlers map them, that
169middleware should shrink. It should not gain new name checks.
170 
171Unknown `500` responses should log full details server-side with
172`Cause.pretty(cause)` and return a safe public body.
173 
174The config startup regression in #27056 is the failure mode this rule is meant
175to avoid: a user-authored invalid `opencode.json` crossed the HttpApi boundary
176as a defect, so middleware replaced a useful `ConfigInvalidError` with a safe
177generic `UnknownError`. The compatibility fix is to preserve config parse and
178validation errors as client-visible `400`s. The target architecture is better:
179config loading should fail on the typed error channel, config HTTP handlers
180should map those errors to declared `ConfigApiError` responses, and the generic
181middleware should never see them.
182 
183## Migration Order
184 
185Prefer small vertical slices:
186 
1871. Fix rendering at one user-visible boundary.
1882. Convert one service domain to `Schema.TaggedErrorClass` errors.
1893. Map those errors at the affected HTTP handlers.
1904. Remove the corresponding name-based middleware branch if possible.
1915. Add or update focused tests for both service error tags and HTTP wire
192   bodies.
193 
194Good early domains are storage not-found, worktree errors, and provider
195auth validation errors because they currently drive HTTP behavior.
196 
197Config parse and validation errors are also a good early slice because they
198are startup-blocking and must be rendered clearly in both CLI and TUI flows.
199 
200## Checklist For A PR
201 
202- [ ] Expected failures are typed errors, not defects.
203- [ ] Service method signatures expose the expected error union.
204- [ ] HTTP handlers translate domain errors at the boundary.
205- [ ] Public HTTP error bodies preserve existing wire contracts.
206- [ ] Generic middleware gets smaller or stays unchanged.
207- [ ] Focused tests cover the service error and any public HTTP response.
208