refactor(core): move models.dev into core (#27347)

packages/core/src/catalog.ts

@@ -5,6 +5,7 @@ import { produce, type Draft } from "immer"
 import { ModelV2 } from "./model"
 import { PluginV2 } from "./plugin"
 import { ProviderV2 } from "./provider"
+import { Instance } from "./instance"
 
 type ProviderRecord = {
   provider: ProviderV2.Info
@@ -56,6 +57,7 @@ export class Service extends Context.Service<Service, Interface>()("@opencode/v2
 export const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
+    yield* Instance.Service
     let records = HashMap.empty<ProviderV2.ID, ProviderRecord>()
     let defaultModel: { providerID: ProviderV2.ID; modelID: ModelV2.ID } | undefined
     const plugin = yield* PluginV2.Service

packages/core/src/instance-layer.ts

@@ -0,0 +1,12 @@
+import { Layer, LayerMap } from "effect"
+import { Instance } from "./instance"
+import { Catalog } from "./catalog"
+import { PluginBoot } from "./plugin/boot"
+
+export class InstanceServiceMap extends LayerMap.Service<InstanceServiceMap>()("@opencode/example/InstanceServiceMap", {
+  lookup: (ref: Instance.Ref) => {
+    const instance = Layer.succeed(Instance.Service, Instance.Service.of(ref))
+    return Layer.mergeAll(Catalog.defaultLayer, PluginBoot.defaultLayer).pipe(Layer.provide(instance))
+  },
+  idleTimeToLive: "5 minutes",
+}) {}

packages/core/src/instance.ts

@@ -0,0 +1,10 @@
+import { Context } from "effect"
+
+export * as Instance from "./instance"
+
+export type Ref = {
+  readonly directory: string
+  readonly workspaceID?: string
+}
+
+export class Service extends Context.Service<Service, Ref>()("@opencode/Instance") {}

packages/core/src/models-snapshot.d.ts

@@ -0,0 +1,2 @@
+// Auto-generated by build.ts - do not edit
+export declare const snapshot: Record<string, unknown>

packages/core/src/models.ts

@@ -0,0 +1,226 @@
+import path from "path"
+import { Context, Duration, Effect, Layer, Option, Schedule, Schema } from "effect"
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/unstable/http"
+import { Global } from "./global"
+import { Flag } from "./flag/flag"
+import { Flock } from "./util/flock"
+import { Hash } from "./util/hash"
+import { AppFileSystem } from "./filesystem"
+import { InstallationChannel, InstallationVersion } from "./installation/version"
+
+export const CatalogModelStatus = Schema.Literals(["alpha", "beta", "deprecated"])
+export type CatalogModelStatus = typeof CatalogModelStatus.Type
+
+const USER_AGENT = `opencode/${InstallationChannel}/${InstallationVersion}/${Flag.OPENCODE_CLIENT}`
+
+const CostTier = Schema.Struct({
+  input: Schema.Finite,
+  output: Schema.Finite,
+  cache_read: Schema.optional(Schema.Finite),
+  cache_write: Schema.optional(Schema.Finite),
+  tier: Schema.Struct({
+    type: Schema.Literal("context"),
+    size: Schema.Finite,
+  }),
+})
+
+const Cost = Schema.Struct({
+  input: Schema.Finite,
+  output: Schema.Finite,
+  cache_read: Schema.optional(Schema.Finite),
+  cache_write: Schema.optional(Schema.Finite),
+  tiers: Schema.optional(Schema.Array(CostTier)),
+  context_over_200k: Schema.optional(
+    Schema.Struct({
+      input: Schema.Finite,
+      output: Schema.Finite,
+      cache_read: Schema.optional(Schema.Finite),
+      cache_write: Schema.optional(Schema.Finite),
+    }),
+  ),
+})
+
+export const Model = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  family: Schema.optional(Schema.String),
+  release_date: Schema.String,
+  attachment: Schema.Boolean,
+  reasoning: Schema.Boolean,
+  temperature: Schema.Boolean,
+  tool_call: Schema.Boolean,
+  interleaved: Schema.optional(
+    Schema.Union([
+      Schema.Literal(true),
+      Schema.Struct({
+        field: Schema.Literals(["reasoning_content", "reasoning_details"]),
+      }),
+    ]),
+  ),
+  cost: Schema.optional(Cost),
+  limit: Schema.Struct({
+    context: Schema.Finite,
+    input: Schema.optional(Schema.Finite),
+    output: Schema.Finite,
+  }),
+  modalities: Schema.optional(
+    Schema.Struct({
+      input: Schema.Array(Schema.Literals(["text", "audio", "image", "video", "pdf"])),
+      output: Schema.Array(Schema.Literals(["text", "audio", "image", "video", "pdf"])),
+    }),
+  ),
+  experimental: Schema.optional(
+    Schema.Struct({
+      modes: Schema.optional(
+        Schema.Record(
+          Schema.String,
+          Schema.Struct({
+            cost: Schema.optional(Cost),
+            provider: Schema.optional(
+              Schema.Struct({
+                body: Schema.optional(Schema.Record(Schema.String, Schema.MutableJson)),
+                headers: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+              }),
+            ),
+          }),
+        ),
+      ),
+    }),
+  ),
+  status: Schema.optional(CatalogModelStatus),
+  provider: Schema.optional(
+    Schema.Struct({ npm: Schema.optional(Schema.String), api: Schema.optional(Schema.String) }),
+  ),
+})
+export type Model = Schema.Schema.Type<typeof Model>
+
+export const Provider = Schema.Struct({
+  api: Schema.optional(Schema.String),
+  name: Schema.String,
+  env: Schema.Array(Schema.String),
+  id: Schema.String,
+  npm: Schema.optional(Schema.String),
+  models: Schema.Record(Schema.String, Model),
+})
+
+export type Provider = Schema.Schema.Type<typeof Provider>
+
+export interface Interface {
+  readonly get: () => Effect.Effect<Record<string, Provider>>
+  readonly refresh: (force?: boolean) => Effect.Effect<void>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/ModelsDev") {}
+
+type Requirements = AppFileSystem.Service | HttpClient.HttpClient
+
+export const layer: Layer.Layer<Service, never, Requirements> = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const fs = yield* AppFileSystem.Service
+    const http = HttpClient.filterStatusOk(
+      (yield* HttpClient.HttpClient).pipe(
+        HttpClient.retryTransient({
+          retryOn: "errors-and-responses",
+          times: 2,
+          schedule: Schedule.exponential(200).pipe(Schedule.jittered),
+        }),
+      ),
+    )
+
+    const source = Flag.OPENCODE_MODELS_URL || "https://models.dev"
+    const filepath = path.join(
+      Global.Path.cache,
+      source === "https://models.dev" ? "models.json" : `models-${Hash.fast(source)}.json`,
+    )
+    const ttl = Duration.minutes(5)
+    const lockKey = `models-dev:${filepath}`
+
+    const fresh = Effect.fnUntraced(function* () {
+      const stat = yield* fs.stat(filepath).pipe(Effect.catch(() => Effect.succeed(undefined)))
+      if (!stat) return false
+      const mtime = Option.getOrElse(stat.mtime, () => new Date(0)).getTime()
+      return Date.now() - mtime < Duration.toMillis(ttl)
+    })
+
+    const fetchApi = Effect.fn("ModelsDev.fetchApi")(function* () {
+      return yield* HttpClientRequest.get(`${source}/api.json`).pipe(
+        HttpClientRequest.setHeader("User-Agent", USER_AGENT),
+        http.execute,
+        Effect.flatMap((res) => res.text),
+        Effect.timeout("10 seconds"),
+      )
+    })
+
+    const loadFromDisk = fs.readJson(Flag.OPENCODE_MODELS_PATH ?? filepath).pipe(
+      Effect.catch(() => Effect.succeed(undefined)),
+      Effect.map((v) => v as Record<string, Provider> | undefined),
+    )
+
+    // Bundled at build time; absent in dev — `tryPromise` covers both.
+    const loadSnapshot = Effect.tryPromise({
+      // @ts-ignore — generated at build time, may not exist in dev
+      try: () => import("./models-snapshot.js").then((m) => m.snapshot as Record<string, Provider> | undefined),
+      catch: () => undefined,
+    }).pipe(Effect.catch(() => Effect.succeed(undefined)))
+
+    const fetchAndWrite = Effect.fn("ModelsDev.fetchAndWrite")(function* () {
+      const text = yield* fetchApi()
+      yield* fs.writeWithDirs(filepath, text)
+      return text
+    })
+
+    const populate = Effect.gen(function* () {
+      const fromDisk = yield* loadFromDisk
+      if (fromDisk) return fromDisk
+      const snapshot = yield* loadSnapshot
+      if (snapshot) return snapshot
+      if (Flag.OPENCODE_DISABLE_MODELS_FETCH) return {}
+      // Flock is cross-process: concurrent opencode CLIs can race on this cache file.
+      const text = yield* Effect.scoped(
+        Effect.gen(function* () {
+          yield* Flock.effect(lockKey)
+          return yield* fetchAndWrite()
+        }),
+      )
+      return JSON.parse(text) as Record<string, Provider>
+    }).pipe(Effect.withSpan("ModelsDev.populate"), Effect.orDie)
+
+    const [cachedGet, invalidate] = yield* Effect.cachedInvalidateWithTTL(populate, Duration.infinity)
+
+    const get = (): Effect.Effect<Record<string, Provider>> => cachedGet
+
+    const refresh = Effect.fn("ModelsDev.refresh")(function* (force = false) {
+      if (!force && (yield* fresh())) return
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          yield* Flock.effect(lockKey)
+          // Re-check under the lock: another process may have refreshed between
+          // our outer check and lock acquisition.
+          if (!force && (yield* fresh())) return
+          yield* fetchAndWrite()
+          yield* invalidate
+        }),
+      ).pipe(
+        Effect.tapCause((cause) =>
+          Effect.logError("Failed to fetch models.dev").pipe(Effect.annotateLogs("cause", cause)),
+        ),
+        Effect.ignore,
+      )
+    })
+
+    if (!Flag.OPENCODE_DISABLE_MODELS_FETCH && !process.argv.includes("--get-yargs-completions")) {
+      // Schedule.spaced runs the effect once, then waits between completions.
+      yield* Effect.forkScoped(refresh().pipe(Effect.repeat(Schedule.spaced("60 minutes")), Effect.ignore))
+    }
+
+    return Service.of({ get, refresh })
+  }),
+)
+
+export const defaultLayer: Layer.Layer<Service> = layer.pipe(
+  Layer.provide(FetchHttpClient.layer),
+  Layer.provide(AppFileSystem.defaultLayer),
+)
+
+export * as ModelsDev from "./models"

packages/core/src/plugin/boot.ts

@@ -0,0 +1,66 @@
+export * as PluginBoot from "./boot"
+
+import { Context, Deferred, Effect, Layer } from "effect"
+import { AuthV2 } from "../auth"
+import { Catalog } from "../catalog"
+import { Npm } from "../npm"
+import { PluginV2 } from "../plugin"
+import { AuthPlugin } from "./auth"
+import { EnvPlugin } from "./env"
+import { ModelsDevPlugin } from "./models-dev"
+import { ProviderPlugins } from "./provider"
+
+type Plugin = {
+  id: PluginV2.ID
+  effect: Effect.Effect<PluginV2.HookFunctions | void, never, Catalog.Service | AuthV2.Service | Npm.Service>
+}
+
+export interface Interface {
+  readonly wait: () => Effect.Effect<void>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/v2/PluginBoot") {}
+
+export const layer: Layer.Layer<Service, never, Catalog.Service | PluginV2.Service | AuthV2.Service | Npm.Service> = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const catalog = yield* Catalog.Service
+    const plugin = yield* PluginV2.Service
+    const auth = yield* AuthV2.Service
+    const npm = yield* Npm.Service
+    const done = yield* Deferred.make<void>()
+
+    const add = Effect.fn("PluginBoot.add")(function* (input: Plugin) {
+      yield* plugin.add({
+        id: input.id,
+        effect: input.effect.pipe(
+          Effect.provideService(Catalog.Service, catalog),
+          Effect.provideService(AuthV2.Service, auth),
+          Effect.provideService(Npm.Service, npm),
+        ),
+      })
+    })
+
+    const boot = Effect.gen(function* () {
+      yield* add(EnvPlugin)
+      yield* add(AuthPlugin)
+      for (const item of ProviderPlugins) {
+        yield* add(item)
+      }
+      yield* add(ModelsDevPlugin)
+    }).pipe(Effect.withSpan("PluginBoot.boot"))
+
+    yield* boot.pipe(Effect.exit, Effect.flatMap((exit) => Deferred.done(done, exit)), Effect.forkScoped)
+
+    return Service.of({
+      wait: () => Deferred.await(done),
+    })
+  }),
+)
+
+export const defaultLayer = layer.pipe(
+  Layer.provide(Catalog.defaultLayer),
+  Layer.provide(PluginV2.defaultLayer),
+  Layer.provide(Layer.orDie(AuthV2.defaultLayer)),
+  Layer.provide(Npm.defaultLayer),
+)

packages/core/src/plugin/models-dev.ts

@@ -0,0 +1,108 @@
+import { DateTime, Effect } from "effect"
+import { Catalog } from "../catalog"
+import { ModelV2 } from "../model"
+import { ModelsDev } from "../models"
+import { PluginV2 } from "../plugin"
+import { ProviderV2 } from "../provider"
+
+function released(date: string) {
+  const time = Date.parse(date)
+  return DateTime.makeUnsafe(Number.isFinite(time) ? time : 0)
+}
+
+function cost(input: ModelsDev.Model["cost"]) {
+  const base = {
+    input: input?.input ?? 0,
+    output: input?.output ?? 0,
+    cache: {
+      read: input?.cache_read ?? 0,
+      write: input?.cache_write ?? 0,
+    },
+  }
+  if (!input?.context_over_200k) return [base]
+  return [
+    base,
+    {
+      tier: {
+        type: "context" as const,
+        size: 200_000,
+      },
+      input: input.context_over_200k.input,
+      output: input.context_over_200k.output,
+      cache: {
+        read: input.context_over_200k.cache_read ?? 0,
+        write: input.context_over_200k.cache_write ?? 0,
+      },
+    },
+  ]
+}
+
+function variants(model: ModelsDev.Model) {
+  return Object.entries(model.experimental?.modes ?? {}).map(([id, item]) => ({
+    id: ModelV2.VariantID.make(id),
+    headers: { ...(item.provider?.headers ?? {}) },
+    body: { ...(item.provider?.body ?? {}) },
+    aisdk: {
+      provider: {},
+      request: {},
+    },
+  }))
+}
+
+export const ModelsDevPlugin = PluginV2.define({
+  id: PluginV2.ID.make("models-dev"),
+  effect: Effect.gen(function* () {
+    const catalog = yield* Catalog.Service
+    const modelsDev = yield* ModelsDev.Service
+    for (const item of Object.values(yield* modelsDev.get())) {
+      const providerID = ProviderV2.ID.make(item.id)
+      yield* catalog.provider.update(providerID, (provider) => {
+        provider.name = item.name
+        provider.env = [...item.env]
+        provider.endpoint = item.npm
+          ? {
+              type: "aisdk",
+              package: item.npm,
+              url: item.api,
+            }
+          : {
+              type: "unknown",
+            }
+      })
+
+      for (const model of Object.values(item.models)) {
+        const modelID = ModelV2.ID.make(model.id)
+        yield* catalog.model
+          .update(providerID, modelID, (draft) => {
+            draft.name = model.name
+            draft.family = model.family ? ModelV2.Family.make(model.family) : undefined
+            draft.endpoint = model.provider?.npm
+              ? {
+                  type: "aisdk",
+                  package: model.provider?.npm,
+                  url: model.provider.api,
+                }
+              : {
+                  type: "unknown",
+                }
+            draft.capabilities = {
+              tools: model.tool_call,
+              input: [...(model.modalities?.input ?? [])],
+              output: [...(model.modalities?.output ?? [])],
+            }
+            draft.variants = variants(model)
+            draft.time.released = released(model.release_date)
+            draft.cost = cost(model.cost)
+            draft.status = model.status ?? "active"
+            draft.enabled = true
+            draft.limit = {
+              context: model.limit.context,
+              input: model.limit.input,
+              output: model.limit.output,
+            }
+          })
+          .pipe(Effect.orDie)
+      }
+    }
+  }).pipe(Effect.provide(ModelsDev.defaultLayer)),
+})

packages/core/test/catalog.test.ts

@@ -1,12 +1,14 @@
 import { describe, expect } from "bun:test"
 import { DateTime, Effect, Layer, Option } from "effect"
 import { Catalog } from "@opencode-ai/core/catalog"
+import { Instance } from "@opencode-ai/core/instance"
 import { ModelV2 } from "@opencode-ai/core/model"
 import { PluginV2 } from "@opencode-ai/core/plugin"
 import { ProviderV2 } from "@opencode-ai/core/provider"
-import { testEffect } from "../lib/effect"
+import { testEffect } from "./lib/effect"
 
-const it = testEffect(Catalog.layer.pipe(Layer.provideMerge(PluginV2.defaultLayer)))
+const instanceLayer = Layer.succeed(Instance.Service, Instance.Service.of({ directory: "test" }))
+const it = testEffect(Catalog.layer.pipe(Layer.provideMerge(PluginV2.defaultLayer), Layer.provide(instanceLayer)))
 
 describe("CatalogV2", () => {
   it.effect("normalizes provider baseURL into endpoint url", () =>

packages/core/test/models.test.ts

@@ -0,0 +1,263 @@
+import { describe, expect, beforeAll, beforeEach, afterAll } from "bun:test"
+import { Effect, Layer, Ref } from "effect"
+import { HttpClient, HttpClientResponse } from "effect/unstable/http"
+import { AppFileSystem } from "@opencode-ai/core/filesystem"
+import { Flag } from "@opencode-ai/core/flag/flag"
+import { Global } from "@opencode-ai/core/global"
+import { ModelsDev } from "@opencode-ai/core/models"
+import { it } from "./lib/effect"
+import { rm, writeFile, utimes, mkdir } from "fs/promises"
+import path from "path"
+
+// test/preload.ts pins OPENCODE_MODELS_PATH to a fixture so other tests can
+// resolve providers without network. These tests need to drive the on-disk
+// cache themselves and silence the eager refresh fork. Save/restore around
+// the suite — never leak the mutation to subsequent test files in the same
+// bun process.
+const ORIGINAL_MODELS_PATH = Flag.OPENCODE_MODELS_PATH
+const ORIGINAL_DISABLE_FETCH = Flag.OPENCODE_DISABLE_MODELS_FETCH
+beforeAll(() => {
+  Flag.OPENCODE_MODELS_PATH = undefined
+  Flag.OPENCODE_DISABLE_MODELS_FETCH = true
+})
+afterAll(() => {
+  Flag.OPENCODE_MODELS_PATH = ORIGINAL_MODELS_PATH
+  Flag.OPENCODE_DISABLE_MODELS_FETCH = ORIGINAL_DISABLE_FETCH
+})
+
+const cacheFile = path.join(Global.Path.cache, "models.json")
+
+const fixture: Record<string, ModelsDev.Provider> = {
+  acme: {
+    id: "acme",
+    name: "Acme",
+    env: ["ACME_API_KEY"],
+    models: {
+      "acme-1": {
+        id: "acme-1",
+        name: "Acme One",
+        release_date: "2026-01-01",
+        attachment: false,
+        reasoning: false,
+        temperature: true,
+        tool_call: true,
+        limit: { context: 128000, output: 8192 },
+      },
+    },
+  },
+}
+
+const fixture2: Record<string, ModelsDev.Provider> = {
+  beta: {
+    id: "beta",
+    name: "Beta",
+    env: ["BETA_API_KEY"],
+    models: {
+      "beta-1": {
+        id: "beta-1",
+        name: "Beta One",
+        release_date: "2026-02-01",
+        attachment: false,
+        reasoning: true,
+        temperature: false,
+        tool_call: false,
+        limit: { context: 64000, output: 4096 },
+      },
+    },
+  },
+}
+
+interface MockState {
+  body: string
+  status: number
+  calls: Array<{ url: string; userAgent: string | null }>
+}
+
+const makeMockClient = (state: Ref.Ref<MockState>) =>
+  HttpClient.make((request) =>
+    Effect.gen(function* () {
+      yield* Ref.update(state, (s) => ({
+        ...s,
+        calls: [...s.calls, { url: request.url, userAgent: request.headers["user-agent"] ?? null }],
+      }))
+      const s = yield* Ref.get(state)
+      return HttpClientResponse.fromWeb(request, new Response(s.body, { status: s.status }))
+    }),
+  )
+
+const buildLayer = (state: Ref.Ref<MockState>) =>
+  // Layer.fresh is required: ModelsDev.layer is a module-level Layer constant,
+  // and Effect.provide uses a process-global MemoMap by default — without fresh,
+  // every test would reuse the cachedInvalidateWithTTL state from the first run.
+  Layer.fresh(ModelsDev.layer).pipe(
+    Layer.provide(Layer.succeed(HttpClient.HttpClient, makeMockClient(state))),
+    Layer.provide(AppFileSystem.defaultLayer),
+  )
+
+const writeCache = (data: object, mtimeMs?: number) =>
+  Effect.promise(async () => {
+    await mkdir(Global.Path.cache, { recursive: true })
+    await writeFile(cacheFile, JSON.stringify(data))
+    if (mtimeMs !== undefined) {
+      const t = mtimeMs / 1000
+      await utimes(cacheFile, t, t)
+    }
+  })
+
+const provided = <A, E>(state: Ref.Ref<MockState>, eff: Effect.Effect<A, E, ModelsDev.Service>) =>
+  eff.pipe(Effect.provide(buildLayer(state)))
+
+beforeEach(async () => {
+  await rm(cacheFile, { force: true })
+})
+
+afterAll(async () => {
+  await rm(cacheFile, { force: true })
+})
+
+const initialState: MockState = {
+  body: JSON.stringify(fixture),
+  status: 200,
+  calls: [],
+}
+
+describe("ModelsDev Service", () => {
+  it.live("get() returns providers from disk when cache file exists", () =>
+    Effect.gen(function* () {
+      yield* writeCache(fixture)
+      const state = yield* Ref.make(initialState)
+      const result = yield* provided(
+        state,
+        ModelsDev.Service.use((s) => s.get()),
+      )
+      expect(result).toEqual(fixture)
+      const final = yield* Ref.get(state)
+      expect(final.calls).toEqual([])
+    }),
+  )
+
+  it.live("get() returns bundled snapshot when disk empty and fetch disabled", () =>
+    Effect.gen(function* () {
+      const state = yield* Ref.make(initialState)
+      const result = yield* provided(
+        state,
+        ModelsDev.Service.use((s) => s.get()),
+      )
+      expect(Object.keys(result).length).toBeGreaterThan(0)
+      const final = yield* Ref.get(state)
+      expect(final.calls).toEqual([])
+    }),
+  )
+
+  it.live("get() is single-flight under concurrent calls", () =>
+    Effect.gen(function* () {
+      yield* writeCache(fixture)
+      const state = yield* Ref.make(initialState)
+      const results = yield* provided(
+        state,
+        Effect.gen(function* () {
+          const svc = yield* ModelsDev.Service
+          return yield* Effect.all([svc.get(), svc.get(), svc.get(), svc.get(), svc.get()], {
+            concurrency: "unbounded",
+          })
+        }),
+      )
+      for (const result of results) expect(result).toEqual(fixture)
+    }),
+  )
+
+  it.live("get() caches across calls (later disk writes are ignored until invalidate)", () =>
+    Effect.gen(function* () {
+      yield* writeCache(fixture)
+      const state = yield* Ref.make(initialState)
+      const first = yield* provided(
+        state,
+        Effect.gen(function* () {
+          const svc = yield* ModelsDev.Service
+          const a = yield* svc.get()
+          // mutate disk between calls — cache should mask the change
+          yield* writeCache(fixture2)
+          const b = yield* svc.get()
+          return { a, b }
+        }),
+      )
+      expect(first.a).toEqual(fixture)
+      expect(first.b).toEqual(fixture)
+    }),
+  )
+
+  it.live("refresh(true) fetches via HttpClient and updates the cache", () =>
+    Effect.gen(function* () {
+      yield* writeCache(fixture)
+      const state = yield* Ref.make({ ...initialState, body: JSON.stringify(fixture2) })
+      const result = yield* provided(
+        state,
+        Effect.gen(function* () {
+          const svc = yield* ModelsDev.Service
+          const before = yield* svc.get()
+          yield* svc.refresh(true)
+          const after = yield* svc.get()
+          return { before, after }
+        }),
+      )
+      expect(result.before).toEqual(fixture)
+      expect(result.after).toEqual(fixture2)
+      const final = yield* Ref.get(state)
+      expect(final.calls.length).toBe(1)
+      expect(final.calls[0].url).toContain("/api.json")
+      expect(final.calls[0].userAgent).toContain("/cli")
+    }),
+  )
+
+  it.live("refresh(false) skips fetch when on-disk file is fresh", () =>
+    Effect.gen(function* () {
+      // Fresh: mtime within the 5-minute TTL.
+      yield* writeCache(fixture, Date.now() - 1000)
+      const state = yield* Ref.make({ ...initialState, body: JSON.stringify(fixture2) })
+      yield* provided(
+        state,
+        ModelsDev.Service.use((s) => s.refresh(false)),
+      )
+      const final = yield* Ref.get(state)
+      expect(final.calls).toEqual([])
+    }),
+  )
+
+  it.live("refresh(false) fetches when on-disk file is stale", () =>
+    Effect.gen(function* () {
+      // Stale: mtime 10 minutes ago, beyond the 5-minute TTL.
+      yield* writeCache(fixture, Date.now() - 10 * 60 * 1000)
+      const state = yield* Ref.make({ ...initialState, body: JSON.stringify(fixture2) })
+      const after = yield* provided(
+        state,
+        Effect.gen(function* () {
+          const svc = yield* ModelsDev.Service
+          yield* svc.refresh(false)
+          return yield* svc.get()
+        }),
+      )
+      const final = yield* Ref.get(state)
+      expect(final.calls.length).toBe(1)
+      expect(after).toEqual(fixture2)
+    }),
+  )
+
+  it.live("refresh swallows HTTP errors and leaves cache intact", () =>
+    Effect.gen(function* () {
+      yield* writeCache(fixture)
+      const state = yield* Ref.make({ ...initialState, status: 500, body: "boom" })
+      const result = yield* provided(
+        state,
+        Effect.gen(function* () {
+          const svc = yield* ModelsDev.Service
+          yield* svc.refresh(true)
+          return yield* svc.get()
+        }),
+      )
+      expect(result).toEqual(fixture)
+      // retryTransient retries 5xx, so calls may be > 1.
+      const final = yield* Ref.get(state)
+      expect(final.calls.length).toBeGreaterThanOrEqual(1)
+    }),
+  )
+})

packages/core/test/plugin/provider-azure.test.ts

@@ -4,7 +4,7 @@ import { AuthV2 } from "@opencode-ai/core/auth"
 import { PluginV2 } from "@opencode-ai/core/plugin"
 import { AuthPlugin } from "@opencode-ai/core/plugin/auth"
 import { AzurePlugin } from "@opencode-ai/core/plugin/provider/azure"
-import { testEffect } from "../../lib/effect"
+import { testEffect } from "../lib/effect"
 import { fakeSelectorSdk, it, model, npmLayer, provider, withEnv } from "./provider-helper"
 
 const itWithAuth = testEffect(Layer.mergeAll(PluginV2.defaultLayer, AuthV2.defaultLayer, npmLayer))

packages/core/test/plugin/provider-cloudflare-workers-ai.test.ts

@@ -5,7 +5,7 @@ import { ModelV2 } from "@opencode-ai/core/model"
 import { PluginV2 } from "@opencode-ai/core/plugin"
 import { AuthPlugin } from "@opencode-ai/core/plugin/auth"
 import { CloudflareWorkersAIPlugin } from "@opencode-ai/core/plugin/provider/cloudflare-workers-ai"
-import { testEffect } from "../../lib/effect"
+import { testEffect } from "../lib/effect"
 import { fakeSelectorSdk, it, model, npmLayer, provider, withEnv } from "./provider-helper"
 
 const itWithAuth = testEffect(Layer.mergeAll(PluginV2.defaultLayer, AuthV2.defaultLayer, npmLayer))

packages/core/test/plugin/provider-deepinfra.test.ts

@@ -3,7 +3,7 @@ import { Effect, Layer } from "effect"
 import { AISDK } from "@opencode-ai/core/aisdk"
 import { PluginV2 } from "@opencode-ai/core/plugin"
 import { DeepInfraPlugin } from "@opencode-ai/core/plugin/provider/deepinfra"
-import { testEffect } from "../../lib/effect"
+import { testEffect } from "../lib/effect"
 import { it, model } from "./provider-helper"
 
 const itAISDK = testEffect(Layer.provideMerge(AISDK.layer, PluginV2.defaultLayer))

packages/core/test/plugin/provider-dynamic.test.ts

@@ -9,7 +9,7 @@ import { AISDK } from "@opencode-ai/core/aisdk"
 import { ModelV2 } from "@opencode-ai/core/model"
 import { PluginV2 } from "@opencode-ai/core/plugin"
 import { DynamicProviderPlugin } from "@opencode-ai/core/plugin/provider/dynamic"
-import { testEffect } from "../../lib/effect"
+import { testEffect } from "../lib/effect"
 import { fixtureProvider, it, model, npmLayer } from "./provider-helper"
 
 const fixtureProviderPath = fileURLToPath(fixtureProvider)

packages/core/test/plugin/provider-github-copilot.test.ts

@@ -3,7 +3,7 @@ import { Effect } from "effect"
 import { ModelV2 } from "@opencode-ai/core/model"
 import { PluginV2 } from "@opencode-ai/core/plugin"
 import { GithubCopilotPlugin } from "@opencode-ai/core/plugin/provider/github-copilot"
-import { fakeSelectorSdk, it, model } from "../v2/plugin/provider-helper"
+import { fakeSelectorSdk, it, model } from "./provider-helper"
 
 describe("GithubCopilotPlugin", () => {
   it.effect("creates the bundled Copilot SDK for the GitHub Copilot package", () =>

packages/core/test/plugin/provider-gitlab.test.ts

@@ -4,7 +4,7 @@ import { AuthV2 } from "@opencode-ai/core/auth"
 import { PluginV2 } from "@opencode-ai/core/plugin"
 import { AuthPlugin } from "@opencode-ai/core/plugin/auth"
 import { GitLabPlugin } from "@opencode-ai/core/plugin/provider/gitlab"
-import { testEffect } from "../../lib/effect"
+import { testEffect } from "../lib/effect"
 import { it, model, npmLayer, provider, withEnv } from "./provider-helper"
 
 const gitlabSDKOptions: Record<string, unknown>[] = []

packages/core/test/plugin/provider-google.test.ts

@@ -4,7 +4,7 @@ import { AISDK } from "@opencode-ai/core/aisdk"
 import { ModelV2 } from "@opencode-ai/core/model"
 import { PluginV2 } from "@opencode-ai/core/plugin"
 import { GooglePlugin } from "@opencode-ai/core/plugin/provider/google"
-import { testEffect } from "../../lib/effect"
+import { testEffect } from "../lib/effect"
 import { it, model } from "./provider-helper"
 
 const itWithAISDK = testEffect(AISDK.layer.pipe(Layer.provideMerge(PluginV2.defaultLayer)))

packages/core/test/plugin/provider-groq.test.ts

@@ -6,7 +6,7 @@ import { ModelV2 } from "@opencode-ai/core/model"
 import { PluginV2 } from "@opencode-ai/core/plugin"
 import { GroqPlugin } from "@opencode-ai/core/plugin/provider/groq"
 import { it, model } from "./provider-helper"
-import { testEffect } from "../../lib/effect"
+import { testEffect } from "../lib/effect"
 
 const aisdkIt = testEffect(AISDK.layer.pipe(Layer.provideMerge(PluginV2.defaultLayer)))
 

packages/core/test/plugin/provider-helper.ts

@@ -5,7 +5,7 @@ import { Effect, Layer, Option } from "effect"
 import { ModelV2 } from "@opencode-ai/core/model"
 import { PluginV2 } from "@opencode-ai/core/plugin"
 import { ProviderV2 } from "@opencode-ai/core/provider"
-import { testEffect } from "../../lib/effect"
+import { testEffect } from "../lib/effect"
 
 export const fixtureProvider = new URL("./fixtures/provider-factory.ts", import.meta.url).href
 

packages/core/test/plugin/provider-opencode.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect } from "bun:test"
-import { DateTime, Effect, Option } from "effect"
+import { DateTime, Effect, Layer, Option } from "effect"
 import { Catalog } from "@opencode-ai/core/catalog"
+import { Instance } from "@opencode-ai/core/instance"
 import { ModelV2 } from "@opencode-ai/core/model"
 import { PluginV2 } from "@opencode-ai/core/plugin"
 import { OpencodePlugin } from "@opencode-ai/core/plugin/provider/opencode"
@@ -8,6 +9,7 @@ import { ProviderV2 } from "@opencode-ai/core/provider"
 import { it, model, provider, withEnv } from "./provider-helper"
 
 const cost = (input: number, output = 0) => [{ input, output, cache: { read: 0, write: 0 } }]
+const instanceLayer = Layer.succeed(Instance.Service, Instance.Service.of({ directory: "test" }))
 
 describe("OpencodePlugin", () => {
   it.effect("uses a public key and cancels paid models without credentials", () =>
@@ -190,6 +192,6 @@ describe("OpencodePlugin", () => {
       const selected = yield* catalog.model.small(providerID)
 
       expect(Option.getOrUndefined(selected)?.id).toBe(ModelV2.ID.make("gpt-5-nano"))
-    }).pipe(Effect.provide(Catalog.defaultLayer)),
+    }).pipe(Effect.provide(Catalog.defaultLayer.pipe(Layer.provide(instanceLayer)))),
   )
 })

packages/core/test/plugin/provider-xai.test.ts

@@ -4,7 +4,7 @@ import { ModelV2 } from "@opencode-ai/core/model"
 import { PluginV2 } from "@opencode-ai/core/plugin"
 import { XAIPlugin } from "@opencode-ai/core/plugin/provider/xai"
 import { ProviderV2 } from "@opencode-ai/core/provider"
-import { testEffect } from "../../lib/effect"
+import { testEffect } from "../lib/effect"
 import { fakeSelectorSdk } from "./provider-helper"
 
 const it = testEffect(PluginV2.defaultLayer)