From ee3ed0117e0f59abec3f275da3258fa85873be73 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Fri, 24 Jul 2026 10:22:07 -0500 Subject: [PATCH] fix(opencode): register configured model in runtime config (#10178) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source control plane people use to manage AI agents for work > - Agent runs depend on adapters translating Paperclip configuration into each agent runtime's native configuration > - The OpenCode local adapter passes configured models through the `--model provider/model` argument > - OpenCode only resolves that argument when the model id exists in the provider's runtime `models` map > - Valid provider-served model ids missing from OpenCode's bundled catalog therefore fail locally with `Model not found` > - This pull request registers the configured model in the injected runtime configuration without overwriting explicit provider definitions > - The benefit is that uncataloged routing variants and newly released models resolve while cataloged models retain their metadata ## Linked Issues or Issue Description ### Pre-submission checklist - [x] I have searched existing open and closed issues and this is not a duplicate. - [x] I can reproduce this on current `master`. - [x] I have confirmed the error originates in Paperclip's OpenCode adapter rather than the provider or local configuration. ### What happened? OpenCode local runs failed with `Model not found` when a configured `provider/model` id was valid at the provider but absent from OpenCode's bundled model catalog. OpenRouter routing variants such as model ids ending in `:nitro` are one example. ### Expected behavior Any configured provider-served model id should resolve when Paperclip starts OpenCode, including ids not yet present in the bundled catalog. ### Steps to reproduce 1. Configure the OpenCode local adapter with a valid provider/model id that is absent from OpenCode's bundled catalog. 2. Start an agent run. 3. Observe that OpenCode rejects the `--model` value with `Model not found` before the session starts. ### Paperclip version or commit Current `master` before this change. ### Deployment mode Local dev using the OpenCode local adapter and an existing provider API key. ### Installation method Built from source. ### Agent adapter(s) involved OpenCode local. ### Database mode Not database-related. ### Relevant logs or output `Model not found` ### Additional context Reproduced with OpenCode 1.15.5. No duplicate or related public GitHub issues or pull requests were found. ### Privacy checklist - [x] I have reviewed all pasted output for sensitive information and no secrets or PII are included. ## What Changed - Register the configured `provider/model` id as an empty custom model entry in the injected `opencode.json` provider configuration. - Preserve explicit model definitions from user configuration and `PAPERCLIP_OPENCODE_PROVIDERS`. - Skip registration for model strings that do not use the `provider/model` form. - Add focused coverage for uncataloged models, explicit definitions, and invalid model strings. ## Verification - `cd packages/adapters/opencode-local && pnpm exec vitest run src/server/runtime-config.test.ts` — 14 tests passed. - `cd packages/adapters/opencode-local && pnpm exec tsc --noEmit` — passed. - Manual reproduction with OpenCode 1.15.5: the uncataloged OpenRouter routing variant fails without the injected model entry and resolves with it. ## Risks - Low risk: the empty entry deep-merges with catalog metadata for known models, and existing explicit model definitions take precedence. - The behavior is limited to syntactically valid `provider/model` configuration values in the OpenCode local adapter. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, exact runtime model `gpt-5.6-sol` (context-window size not exposed by the runtime), with reasoning, tool use, terminal execution, and code-editing capabilities. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip --- .../src/server/runtime-config.test.ts | 61 +++++++++++++++++++ .../src/server/runtime-config.ts | 36 ++++++++++- 2 files changed, 96 insertions(+), 1 deletion(-) diff --git a/packages/adapters/opencode-local/src/server/runtime-config.test.ts b/packages/adapters/opencode-local/src/server/runtime-config.test.ts index 19f61c06d3..14791829a8 100644 --- a/packages/adapters/opencode-local/src/server/runtime-config.test.ts +++ b/packages/adapters/opencode-local/src/server/runtime-config.test.ts @@ -249,6 +249,67 @@ describe("prepareOpenCodeRuntimeConfig", () => { await prepared.cleanup(); }); + it("registers a configured model missing from the catalog on its provider", async () => { + const configHome = await makeConfigHome({ permission: { read: "allow" } }); + const prepared = await prepareOpenCodeRuntimeConfig({ + env: { XDG_CONFIG_HOME: configHome }, + config: { model: "openrouter/openai/gpt-oss-120b:nitro" }, + }); + cleanupPaths.add(prepared.env.XDG_CONFIG_HOME); + const runtimeConfig = JSON.parse( + await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"), + ) as { provider?: Record }> }; + expect(runtimeConfig.provider?.openrouter?.models).toEqual({ + "openai/gpt-oss-120b:nitro": {}, + }); + expect(prepared.notes).toContain( + "Registered configured model openrouter/openai/gpt-oss-120b:nitro in the runtime OpenCode config.", + ); + await prepared.cleanup(); + }); + + it("does not clobber an explicit model definition when registering the configured model", async () => { + const configHome = await makeConfigHome({ permission: { read: "allow" } }); + const providers = { + openrouter: { + models: { + "openai/gpt-oss-120b:nitro": { name: "GPT-OSS 120B (nitro)" }, + "example/other": {}, + }, + }, + }; + const prepared = await prepareOpenCodeRuntimeConfig({ + env: { + XDG_CONFIG_HOME: configHome, + PAPERCLIP_OPENCODE_PROVIDERS: JSON.stringify(providers), + }, + config: { model: "openrouter/openai/gpt-oss-120b:nitro" }, + }); + cleanupPaths.add(prepared.env.XDG_CONFIG_HOME); + const runtimeConfig = JSON.parse( + await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"), + ) as { provider?: Record }> }; + expect(runtimeConfig.provider?.openrouter?.models).toEqual(providers.openrouter.models); + expect( + prepared.notes.some((note) => note.startsWith("Registered configured model")), + ).toBe(false); + await prepared.cleanup(); + }); + + it("skips model registration when the configured model is not provider/model shaped", async () => { + const configHome = await makeConfigHome({ permission: { read: "allow" } }); + const prepared = await prepareOpenCodeRuntimeConfig({ + env: { XDG_CONFIG_HOME: configHome }, + config: { model: "not-a-provider-model" }, + }); + cleanupPaths.add(prepared.env.XDG_CONFIG_HOME); + const runtimeConfig = JSON.parse( + await fs.readFile(path.join(prepared.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"), + ) as Record; + expect(runtimeConfig.provider).toBeUndefined(); + await prepared.cleanup(); + }); + it("respects explicit opt-out", async () => { const configHome = await makeConfigHome(); const prepared = await prepareOpenCodeRuntimeConfig({ diff --git a/packages/adapters/opencode-local/src/server/runtime-config.ts b/packages/adapters/opencode-local/src/server/runtime-config.ts index 146b371f29..dd466cdb2d 100644 --- a/packages/adapters/opencode-local/src/server/runtime-config.ts +++ b/packages/adapters/opencode-local/src/server/runtime-config.ts @@ -84,6 +84,14 @@ function parseProviderConfig( return Object.keys(providers).length > 0 ? providers : null; } +function parseConfiguredModelRef(raw: unknown): { provider: string; model: string } | null { + if (typeof raw !== "string") return null; + const trimmed = raw.trim(); + const slash = trimmed.indexOf("/"); + if (slash <= 0 || slash === trimmed.length - 1) return null; + return { provider: trimmed.slice(0, slash), model: trimmed.slice(slash + 1) }; +} + async function readJsonObject(filepath: string): Promise> { try { const raw = await fs.readFile(filepath, "utf8"); @@ -162,7 +170,7 @@ export async function prepareOpenCodeRuntimeConfig(input: { notes, ); const existingProvider = isPlainObject(existingConfig.provider) ? existingConfig.provider : {}; - const nextProvider = gatewayProviders + let nextProvider = gatewayProviders ? { ...existingProvider, ...gatewayProviders } : existingProvider; if (gatewayProviders) { @@ -171,6 +179,32 @@ export async function prepareOpenCodeRuntimeConfig(input: { ); } + // Register the configured model on its provider's models map. OpenCode resolves + // `--model provider/model` only when the model id exists in that map, so ids the + // models.dev catalog does not carry — OpenRouter routing variants such as + // `openai/gpt-oss-120b:nitro`, or models newer than the bundled catalog — are + // otherwise rejected with "Model not found" even though the provider serves them. + // An empty entry deep-merges with catalog metadata, so this is a no-op for models + // the catalog already knows, and we never clobber an explicit definition from the + // user config or PAPERCLIP_OPENCODE_PROVIDERS. + const configuredModel = parseConfiguredModelRef(input.config.model); + if (configuredModel) { + const providerEntry = isPlainObject(nextProvider[configuredModel.provider]) + ? { ...(nextProvider[configuredModel.provider] as Record) } + : {}; + const providerModels = isPlainObject(providerEntry.models) + ? { ...(providerEntry.models as Record) } + : {}; + if (!isPlainObject(providerModels[configuredModel.model])) { + providerModels[configuredModel.model] = {}; + providerEntry.models = providerModels; + nextProvider = { ...nextProvider, [configuredModel.provider]: providerEntry }; + notes.push( + `Registered configured model ${configuredModel.provider}/${configuredModel.model} in the runtime OpenCode config.`, + ); + } + } + const nextConfig: Record = { ...existingConfig, permission: {