Apply PR #18452: fix: lazy runtime imports in facades to break bundle cycles

Author: opencode-agent[bot]

packages/opencode/specs/effect-migration.md

@@ -46,35 +46,64 @@ Rules:
 - Export `defaultLayer` only when wiring dependencies is useful
 - Use the direct namespace form once the module is fully migrated
 
-## Temporary mixed-mode pattern
+## Service / Facade split
 
-Prefer a single namespace whenever possible.
+Migrated services are split into two files:
 
-Use a `*Effect` namespace only when there is a real mixed-mode split, usually because a legacy boundary facade still exists or because merging everything immediately would create awkward cycles.
+- **Service module** (`service.ts`, `*-service.ts`, or `*-effect.ts`) — contains `Interface`, `Service`, `layer`, `defaultLayer`, schemas, types, errors, and pure helpers. Must **never** import `@/effect/runtime`.
+- **Facade** (`index.ts`) — thin async wrapper that calls `runInstance()` or `run()` from `@/effect/run`. Contains **only** runtime-backed convenience functions. No re-exports of schemas, types, Service, layer, or anything else.
 
-```ts
-export namespace FooEffect {
-  export interface Interface {
-    readonly get: (id: FooID) => Effect.Effect<Foo, FooError>
-  }
+### Facade rules (critical for bundle safety)
 
-  export class Service extends ServiceMap.Service<Service, Interface>()("@opencode/Foo") {}
+1. **No eager import of `@/effect/runtime`** — use `run()` / `runInstance()` from `@/effect/run` instead, which lazy-imports the runtime.
+2. **No eager import of the service module** if the service is in the circular dependency SCC (auth, account, skill, truncate). Use the lazy `svc()` pattern:
+   ```ts
+   const svc = () => import("./service").then((m) => m.Foo.Service)
+   ```
+3. **No value re-exports** — consumers that need schemas, types, `Service`, or `layer` import from the service module directly.
+4. **Only async wrapper functions** — each function awaits `svc()` and passes an Effect to `run()` / `runInstance()`.
 
-  export const layer = Layer.effect(...)
-}
-```
+### Why
+
+Bun's bundler flattens all modules into a single file. When a circular dependency exists (`runtime → instances → services → config → auth → runtime`), the bundler picks an arbitrary evaluation order. If a facade eagerly imports `@/effect/runtime` or re-exports values from a service in the SCC, those values may be `undefined` when accessed at module load time — causing `undefined is not an object` crashes.
 
-Then keep the old boundary thin:
+The lazy `svc()` + `run()` pattern defers all access to call time, when all modules have finished initializing.
+
+### Example facade
 
 ```ts
-export namespace Foo {
-  export function get(id: FooID) {
-    return runtime.runPromise(FooEffect.Service.use((svc) => svc.get(id)))
+// src/question/index.ts (facade)
+import { runInstance } from "@/effect/run"
+import type { Question as S } from "./service"
+
+const svc = () => import("./service").then((m) => m.Question.Service)
+
+export namespace Question {
+  export async function ask(input: { ... }): Promise<S.Answer[]> {
+    return runInstance((await svc()).use((s) => s.ask(input)))
+  }
+
+  export async function list() {
+    return runInstance((await svc()).use((s) => s.list()))
   }
 }
 ```
 
-Remove the `Effect` suffix when the boundary split is gone.
+### Current facades
+
+| Facade | Service module | Scope |
+|---|---|---|
+| `src/question/index.ts` | `src/question/service.ts` | instance |
+| `src/permission/index.ts` | `src/permission/service.ts` | instance |
+| `src/format/index.ts` | `src/format/service.ts` | instance |
+| `src/file/index.ts` | `src/file/service.ts` | instance |
+| `src/file/time.ts` | `src/file/time-service.ts` | instance |
+| `src/provider/auth.ts` | `src/provider/auth-service.ts` | instance |
+| `src/skill/index.ts` | `src/skill/service.ts` | instance |
+| `src/snapshot/index.ts` | `src/snapshot/service.ts` | instance |
+| `src/auth/index.ts` | `src/auth/effect.ts` | global |
+| `src/account/index.ts` | `src/account/effect.ts` | global |
+| `src/tool/truncate.ts` | `src/tool/truncate-effect.ts` | global |
 
 ## Scheduled Tasks
 

packages/opencode/src/account/index.ts

@@ -1,34 +1,27 @@
-import { Effect, Option } from "effect"
-
-import { Account as S, type AccountError, type AccessToken, AccountID, Info as Model, OrgID } from "./effect"
+import { Option } from "effect"
+import { run } from "@/effect/run"
+import { lazy } from "@/util/lazy"
+import { type AccessToken, AccountID, Info as Model, OrgID } from "./effect"
 
 export { AccessToken, AccountID, OrgID } from "./effect"
 
-import { runtime } from "@/effect/runtime"
-
-function runSync<A>(f: (service: S.Interface) => Effect.Effect<A, AccountError>) {
-  return runtime.runSync(S.Service.use(f))
-}
-
-function runPromise<A>(f: (service: S.Interface) => Effect.Effect<A, AccountError>) {
-  return runtime.runPromise(S.Service.use(f))
-}
+const svc = lazy(() => import("./effect").then((m) => m.Account.Service))
 
 export namespace Account {
   export const Info = Model
   export type Info = Model
 
-  export function active(): Info | undefined {
-    return Option.getOrUndefined(runSync((service) => service.active()))
+  export async function active(): Promise<Info | undefined> {
+    return Option.getOrUndefined(await run((await svc()).use((s) => s.active())))
   }
 
   export async function config(accountID: AccountID, orgID: OrgID): Promise<Record<string, unknown> | undefined> {
-    const config = await runPromise((service) => service.config(accountID, orgID))
+    const config = await run((await svc()).use((s) => s.config(accountID, orgID)))
     return Option.getOrUndefined(config)
   }
 
   export async function token(accountID: AccountID): Promise<AccessToken | undefined> {
-    const token = await runPromise((service) => service.token(accountID))
+    const token = await run((await svc()).use((s) => s.token(accountID)))
     return Option.getOrUndefined(token)
   }
 }

packages/opencode/src/agent/agent.ts

@@ -5,7 +5,7 @@ import { ModelID, ProviderID } from "../provider/schema"
 import { generateObject, streamObject, type ModelMessage } from "ai"
 import { SystemPrompt } from "../session/system"
 import { Instance } from "../project/instance"
-import { Truncate } from "../tool/truncate"
+import { Truncate } from "../tool/truncate-effect"
 import { Auth } from "../auth"
 import { ProviderTransform } from "../provider/transform"
 

packages/opencode/src/auth/index.ts

@@ -1,13 +1,10 @@
-import { Effect } from "effect"
 import z from "zod"
-import { runtime } from "@/effect/runtime"
-import * as S from "./effect"
+import { run } from "@/effect/run"
+import { lazy } from "@/util/lazy"
 
 export { OAUTH_DUMMY_KEY } from "./effect"
 
-function runPromise<A>(f: (service: S.Auth.Interface) => Effect.Effect<A, S.AuthError>) {
-  return runtime.runPromise(S.Auth.Service.use(f))
-}
+const svc = lazy(() => import("./effect").then((m) => m.Auth.Service))
 
 export namespace Auth {
   export const Oauth = z
@@ -40,18 +37,18 @@ export namespace Auth {
   export type Info = z.infer<typeof Info>
 
   export async function get(providerID: string) {
-    return runPromise((service) => service.get(providerID))
+    return run((await svc()).use((s) => s.get(providerID)))
   }
 
   export async function all(): Promise<Record<string, Info>> {
-    return runPromise((service) => service.all())
+    return run((await svc()).use((s) => s.all()))
   }
 
   export async function set(key: string, info: Info) {
-    return runPromise((service) => service.set(key, info))
+    return run((await svc()).use((s) => s.set(key, info)))
   }
 
   export async function remove(key: string) {
-    return runPromise((service) => service.remove(key))
+    return run((await svc()).use((s) => s.remove(key)))
   }
 }

packages/opencode/src/cli/cmd/account.ts

@@ -1,7 +1,7 @@
 import { cmd } from "./cmd"
 import { Duration, Effect, Match, Option } from "effect"
 import { UI } from "../ui"
-import { runtime } from "@/effect/runtime"
+import { run } from "@/effect/run"
 import { AccountID, Account, OrgID, PollExpired, type PollResult } from "@/account/effect"
 import { type AccountError } from "@/account/schema"
 import * as Prompt from "../effect/prompt"
@@ -160,7 +160,7 @@ export const LoginCommand = cmd({
     }),
   async handler(args) {
     UI.empty()
-    await runtime.runPromise(loginEffect(args.url))
+    await run(loginEffect(args.url))
   },
 })
 
@@ -174,7 +174,7 @@ export const LogoutCommand = cmd({
     }),
   async handler(args) {
     UI.empty()
-    await runtime.runPromise(logoutEffect(args.email))
+    await run(logoutEffect(args.email))
   },
 })
 
@@ -183,7 +183,7 @@ export const SwitchCommand = cmd({
   describe: false,
   async handler() {
     UI.empty()
-    await runtime.runPromise(switchEffect())
+    await run(switchEffect())
   },
 })
 
@@ -192,7 +192,7 @@ export const OrgsCommand = cmd({
   describe: false,
   async handler() {
     UI.empty()
-    await runtime.runPromise(orgsEffect())
+    await run(orgsEffect())
   },
 })
 

packages/opencode/src/cli/cmd/debug/agent.ts

@@ -7,7 +7,7 @@ import type { MessageV2 } from "../../../session/message-v2"
 import { MessageID, PartID } from "../../../session/schema"
 import { ToolRegistry } from "../../../tool/registry"
 import { Instance } from "../../../project/instance"
-import { PermissionNext } from "../../../permission"
+import { Permission as PermissionNext } from "../../../permission/service"
 import { iife } from "../../../util/iife"
 import { bootstrap } from "../../bootstrap"
 import { cmd } from "../cmd"

packages/opencode/src/cli/cmd/run.ts

@@ -11,7 +11,7 @@ import { createOpencodeClient, type Message, type OpencodeClient, type ToolPart
 import { Server } from "../../server/server"
 import { Provider } from "../../provider/provider"
 import { Agent } from "../../agent/agent"
-import { PermissionNext } from "../../permission"
+import { Permission as PermissionNext } from "../../permission/service"
 import { Tool } from "../../tool/tool"
 import { GlobTool } from "../../tool/glob"
 import { GrepTool } from "../../tool/grep"

packages/opencode/src/config/config.ts

@@ -11,7 +11,6 @@ import fs from "fs/promises"
 import { lazy } from "../util/lazy"
 import { NamedError } from "@opencode-ai/util/error"
 import { Flag } from "../flag/flag"
-import { Auth } from "../auth"
 import { Env } from "../env"
 import {
   type ParseError as JsoncParseError,
@@ -30,11 +29,13 @@ import { GlobalBus } from "@/bus/global"
 import { Event } from "../server/event"
 import { Glob } from "../util/glob"
 import { iife } from "@/util/iife"
-import { Account } from "@/account"
 import { ConfigPaths } from "./paths"
 import { Filesystem } from "@/util/filesystem"
 import { Npm } from "@/npm"
 
+import { Auth } from "../auth"
+import { Account } from "@/account"
+
 export namespace Config {
   const ModelId = z.string().meta({ $ref: "https://models.dev/model-schema.json#/$defs/Model" })
 
@@ -72,7 +73,7 @@ export namespace Config {
   }
 
   export const state = Instance.state(async () => {
-    const auth = await Auth.all()
+    const entries = await Auth.all()
 
     // Config loading order (low -> high precedence): https://opencode.ai/docs/config#precedence-order
     // 1) Remote .well-known/opencode (org defaults)
@@ -83,7 +84,7 @@ export namespace Config {
     // 6) Inline config (OPENCODE_CONFIG_CONTENT)
     // Managed config directory is enterprise-only and always overrides everything above.
     let result: Info = {}
-    for (const [key, value] of Object.entries(auth)) {
+    for (const [key, value] of Object.entries(entries)) {
       if (value.type === "wellknown") {
         const url = key.replace(/\/+$/, "")
         process.env[value.key] = value.token
@@ -172,13 +173,10 @@ export namespace Config {
       log.debug("loaded custom config from OPENCODE_CONFIG_CONTENT")
     }
 
-    const active = Account.active()
+    const active = await Account.active()
     if (active?.active_org_id) {
       try {
-        const [config, token] = await Promise.all([
-          Account.config(active.id, active.active_org_id),
-          Account.token(active.id),
-        ])
+        const [config, token] = await Promise.all([Account.config(active.id, active.active_org_id), Account.token(active.id)])
         if (token) {
           process.env["OPENCODE_CONSOLE_TOKEN"] = token
           Env.set("OPENCODE_CONSOLE_TOKEN", token)

packages/opencode/src/effect/run.ts

@@ -0,0 +1,24 @@
+import type { Effect } from "effect"
+import type { GlobalServices } from "@/effect/runtime"
+import type { InstanceServices } from "@/effect/instances"
+import { lazy } from "@/util/lazy"
+
+/**
+ * Lazy wrappers that defer the import of @/effect/runtime to call time.
+ *
+ * Adapter modules must not eagerly import @/effect/runtime — or even
+ * their own service modules — because bun's bundler can evaluate them
+ * before their dependencies have finished initializing.
+ */
+
+const runtime = lazy(() => import("@/effect/runtime"))
+
+/** For global services (Auth, Account, etc.) */
+export async function run<A, E>(effect: Effect.Effect<A, E, GlobalServices>): Promise<A> {
+  return (await runtime()).runtime.runPromise(effect)
+}
+
+/** For instance-scoped services (Skill, Snapshot, Question, etc.) */
+export async function runInstance<A, E>(effect: Effect.Effect<A, E, InstanceServices>): Promise<A> {
+  return (await runtime()).runPromiseInstance(effect)
+}

packages/opencode/src/effect/runtime.ts

@@ -7,9 +7,11 @@ import { Installation } from "@/installation"
 import { Truncate } from "@/tool/truncate-effect"
 import { Instance } from "@/project/instance"
 
+export type GlobalServices = Account.Service | Installation.Service | Truncate.Service | Instances | Auth.Service
+
 export const runtime = ManagedRuntime.make(
   Layer.mergeAll(
-    Account.defaultLayer, //
+    Account.defaultLayer,
     Installation.defaultLayer,
     Truncate.defaultLayer,
     Instances.layer,