feat: add free model resolution for --model free

  Resolves --model free to a random free opencode model before
  prompting. Supports --variant any for random variant selection.

  Closes #21863

Author: caretak3r

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

@@ -636,22 +636,26 @@ export const RunCommand = cmd({
         process.exit(1)
       })
 
+      const resolved = await Provider.resolveSelection(args.model, args.variant)
+      const model = resolved.model
+      const variant = resolved.variant
+
       if (args.command) {
         await sdk.session.command({
           sessionID,
           agent,
-          model: args.model,
+          model,
           command: args.command,
           arguments: message,
-          variant: args.variant,
+          variant,
         })
       } else {
-        const model = args.model ? Provider.parseModel(args.model) : undefined
+        const modelObj = model ? Provider.parseModel(model) : undefined
         await sdk.session.prompt({
           sessionID,
           agent,
-          model,
-          variant: args.variant,
+          model: modelObj,
+          variant,
           parts: [...files, { type: "text", text: message }],
         })
       }

packages/opencode/src/cli/cmd/tui/app.tsx

@@ -342,6 +342,7 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
           })
         local.model.set({ providerID, modelID }, { recent: true })
       }
+      if (args.variant) local.model.variant.set(args.variant)
       if (args.sessionID && !args.fork) {
         route.navigate({
           type: "session",

packages/opencode/src/cli/cmd/tui/context/args.tsx

@@ -2,6 +2,7 @@ import { createSimpleContext } from "./helper"
 
 export interface Args {
   model?: string
+  variant?: string
   agent?: string
   prompt?: string
   continue?: boolean

packages/opencode/src/cli/cmd/tui/thread.ts

@@ -17,6 +17,7 @@ import { writeHeapSnapshot } from "v8"
 import { TuiConfig } from "./config/tui"
 import { OPENCODE_PROCESS_ROLE, OPENCODE_RUN_ID, ensureRunID, sanitizedProcessEnv } from "@/util/opencode-process"
 import { validateSession } from "./validate-session"
+import { Provider } from "@/provider"
 
 declare global {
   const OPENCODE_WORKER_PATH: string
@@ -101,6 +102,10 @@ export const TuiThreadCommand = cmd({
       .option("agent", {
         type: "string",
         describe: "agent to use",
+      })
+      .option("variant", {
+        type: "string",
+        describe: "model variant (provider-specific reasoning effort, e.g., high, max, minimal)",
       }),
   handler: async (args) => {
     // Keep ENABLE_PROCESSED_INPUT cleared even if other code flips it.
@@ -131,6 +136,9 @@ export const TuiThreadCommand = cmd({
         return
       }
       const cwd = Filesystem.resolve(process.cwd())
+      const pick = await Provider.resolveSelection(args.model, args.variant)
+      const model = pick.model
+      const variant = pick.variant
       const env = sanitizedProcessEnv({
         [OPENCODE_PROCESS_ROLE]: "worker",
         [OPENCODE_RUN_ID]: ensureRunID(),
@@ -236,7 +244,8 @@ export const TuiThreadCommand = cmd({
             continue: args.continue,
             sessionID: args.session,
             agent: args.agent,
-            model: args.model,
+            model,
+            variant,
             prompt,
             fork: args.fork,
           },

packages/opencode/src/provider/provider.ts

@@ -23,6 +23,7 @@ import { pathToFileURL } from "url"
 import { Effect, Layer, Context, Schema, Types } from "effect"
 import { EffectBridge } from "@/effect"
 import { InstanceState } from "@/effect"
+import { makeRuntime } from "@/effect/run-service"
 import { AppFileSystem } from "@opencode-ai/shared/filesystem"
 import { isRecord } from "@/util/record"
 import { withStatics } from "@/util/schema"
@@ -1705,6 +1706,53 @@ export function sort<T extends { id: string }>(models: T[]) {
   )
 }
 
+const FREE = "free"
+export const ANY = "any"
+
+function isFree(model: Model) {
+  const extra = model.cost.experimentalOver200K
+  return (
+    model.providerID === ProviderID.opencode &&
+    model.cost.input === 0 &&
+    model.cost.output === 0 &&
+    model.cost.cache.read === 0 &&
+    model.cost.cache.write === 0 &&
+    (!extra || (extra.input === 0 && extra.output === 0 && extra.cache.read === 0 && extra.cache.write === 0))
+  )
+}
+
+function isListed(model: Model) {
+  return model.id === "big-pickle" || model.id.endsWith("-free")
+}
+
+function freeVariants(model: Model) {
+  return Object.keys(model.variants ?? {})
+    .toSorted()
+    .filter((item) => item !== "default")
+}
+
+const { runPromise } = makeRuntime(Service, defaultLayer)
+
+export async function resolveSelection(model?: string, variant?: string) {
+  if (!model) return { model, variant }
+  if (model !== FREE) return { model, variant }
+  const providers = await runPromise((svc) => svc.list())
+  const provider = providers[ProviderID.opencode]
+  const models = sort(Object.values(provider?.models ?? {}).filter((item) => isFree(item) && isListed(item)))
+  const pick = models[Math.floor(Math.random() * models.length)]
+  if (!pick) throw new Error("No free opencode models found")
+  const next = variant === "any" ? freeVariants(pick) : []
+  const value = variant !== "any" ? variant : next[Math.floor(Math.random() * next.length)]
+  return {
+    model: `${pick.providerID}/${pick.id}`,
+    variant: value,
+  }
+}
+
+export async function resolveModel(model: string) {
+  return (await resolveSelection(model)).model!
+}
+
 export function parseModel(model: string) {
   const [providerID, ...rest] = model.split("/")
   return {

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

@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, mock, spyOn, test } from "bun:test"
+import * as SDK from "@opencode-ai/sdk/v2"
+import { Provider } from "../../../src/provider"
+
+const seen = {
+  prompt: [] as any[],
+  command: [] as any[],
+  variant: [] as any[],
+}
+
+function setup() {
+  spyOn(Provider, "resolveSelection").mockImplementation(async (model, variant) => ({
+    model: model === "free" ? "opencode/freebie" : model,
+    variant: variant === "any" ? "high" : variant,
+  }))
+  spyOn(SDK, "createOpencodeClient").mockImplementation(
+    () =>
+      ({
+        config: {
+          get: async () => ({ data: { share: "manual" } }),
+        },
+        event: {
+          subscribe: async () => ({
+            stream: (async function* () {})(),
+          }),
+        },
+        session: {
+          create: async () => ({ data: { id: "session-1" } }),
+          prompt: async (input: any) => {
+            seen.prompt.push(input)
+            seen.variant.push(input.variant)
+            return {}
+          },
+          command: async (input: any) => {
+            seen.command.push(input)
+            seen.variant.push(input.variant)
+            return {}
+          },
+        },
+      }) as any,
+  )
+}
+
+describe("run command", () => {
+  afterEach(() => {
+    mock.restore()
+    seen.prompt.length = 0
+    seen.command.length = 0
+    seen.variant.length = 0
+  })
+
+  async function call(extra?: Record<string, unknown>) {
+    setup()
+    const { RunCommand } = await import("../../../src/cli/cmd/run")
+    const tty = Object.getOwnPropertyDescriptor(process.stdin, "isTTY")
+
+    Object.defineProperty(process.stdin, "isTTY", {
+      configurable: true,
+      value: true,
+    })
+
+    try {
+      await RunCommand.handler({
+        _: [],
+        $0: "opencode",
+        message: ["hi"],
+        command: undefined,
+        continue: false,
+        session: undefined,
+        fork: false,
+        share: false,
+        model: "free",
+        agent: undefined,
+        format: "default",
+        file: undefined,
+        title: undefined,
+        attach: "http://127.0.0.1:4096",
+        password: undefined,
+        dir: undefined,
+        port: undefined,
+        variant: undefined,
+        thinking: false,
+        "dangerously-skip-permissions": false,
+        "--": [],
+        ...extra,
+      } as any)
+    } finally {
+      if (tty) Object.defineProperty(process.stdin, "isTTY", tty)
+      else delete (process.stdin as { isTTY?: boolean }).isTTY
+    }
+  }
+
+  test("resolves free before prompting", async () => {
+    await call()
+
+    expect(seen.prompt).toHaveLength(1)
+    expect(String(seen.prompt[0].model.providerID)).toBe("opencode")
+    expect(String(seen.prompt[0].model.modelID)).toBe("freebie")
+  })
+
+  test("passes the resolved model to command sessions", async () => {
+    await call({ command: "echo" })
+
+    expect(seen.command).toHaveLength(1)
+    expect(seen.command[0].model).toBe("opencode/freebie")
+  })
+
+  test("passes the resolved any variant to sessions", async () => {
+    await call({ variant: "any" })
+
+    expect(seen.prompt).toHaveLength(1)
+    expect(seen.variant[0]).toBe("high")
+  })
+})

packages/opencode/test/cli/tui/thread.test.ts

@@ -9,10 +9,13 @@ import * as Timeout from "../../../src/util/timeout"
 import * as Network from "../../../src/cli/network"
 import * as Win32 from "../../../src/cli/cmd/tui/win32"
 import { TuiConfig } from "../../../src/cli/cmd/tui/config/tui"
+import { Provider } from "../../../src/provider"
 
 const stop = new Error("stop")
 const seen = {
   tui: [] as string[],
+  model: [] as (string | undefined)[],
+  variant: [] as (string | undefined)[],
 }
 
 function setup() {
@@ -23,6 +26,8 @@ function setup() {
   // https://github.com/oven-sh/bun/issues/7823 and #12823.
   spyOn(App, "tui").mockImplementation(async (input) => {
     if (input.directory) seen.tui.push(input.directory)
+    seen.model.push(input.args.model)
+    seen.variant.push(input.args.variant)
     throw stop
   })
   spyOn(Rpc, "client").mockImplementation(() => ({
@@ -40,21 +45,26 @@ function setup() {
   })
   spyOn(Win32, "win32DisableProcessedInput").mockImplementation(() => {})
   spyOn(Win32, "win32InstallCtrlCGuard").mockReturnValue(undefined)
+  spyOn(Provider, "resolveSelection").mockImplementation(async (model, variant) => ({
+    model: model === "free" ? "opencode/freebie" : model,
+    variant: variant === "any" ? "high" : variant,
+  }))
 }
 
 describe("tui thread", () => {
   afterEach(() => {
     mock.restore()
   })
 
-  async function call(project?: string) {
+  async function call(project?: string, model?: string, variant?: string) {
     const { TuiThreadCommand } = await import("../../../src/cli/cmd/tui/thread")
     const args: Parameters<NonNullable<typeof TuiThreadCommand.handler>>[0] = {
       _: [],
       $0: "opencode",
       project,
       prompt: "hi",
-      model: undefined,
+      model,
+      variant,
       agent: undefined,
       session: undefined,
       continue: false,
@@ -69,7 +79,12 @@ describe("tui thread", () => {
     return TuiThreadCommand.handler(args)
   }
 
-  async function check(project?: string) {
+  async function check(
+    project?: string,
+    model?: string,
+    variant?: string,
+    expected?: { model?: string; variant?: string },
+  ) {
     setup()
     await using tmp = await tmpdir({ git: true })
     const cwd = process.cwd()
@@ -79,6 +94,8 @@ describe("tui thread", () => {
     const link = path.join(path.dirname(tmp.path), path.basename(tmp.path) + "-link")
     const type = process.platform === "win32" ? "junction" : "dir"
     seen.tui.length = 0
+    seen.model.length = 0
+    seen.variant.length = 0
     await fs.symlink(tmp.path, link, type)
 
     Object.defineProperty(process.stdin, "isTTY", {
@@ -96,8 +113,10 @@ describe("tui thread", () => {
     try {
       process.chdir(tmp.path)
       process.env.PWD = link
-      await expect(call(project)).rejects.toBe(stop)
+      await expect(call(project, model, variant)).rejects.toBe(stop)
       expect(seen.tui[0]).toBe(tmp.path)
+      if (expected?.model) expect(seen.model[0]).toBe(expected.model)
+      if (expected?.variant) expect(seen.variant[0]).toBe(expected.variant)
     } finally {
       process.chdir(cwd)
       if (pwd === undefined) delete process.env.PWD
@@ -116,4 +135,12 @@ describe("tui thread", () => {
   test("uses the real cwd after resolving a relative project from PWD", async () => {
     await check(".")
   })
+
+  test("resolves the free model alias before launching the tui", async () => {
+    await check(undefined, "free", undefined, { model: "opencode/freebie" })
+  })
+
+  test("passes the resolved any variant before launching the tui", async () => {
+    await check(undefined, "free", "any", { model: "opencode/freebie", variant: "high" })
+  })
 })