Skip to content

Instantly share code, notes, and snippets.

@jlongster
Created August 25, 2026 15:25
Show Gist options
  • Select an option

  • Save jlongster/3c3fb0f2c9dd0b63867c11111ff8b1ea to your computer and use it in GitHub Desktop.

Select an option

Save jlongster/3c3fb0f2c9dd0b63867c11111ff8b1ea to your computer and use it in GitHub Desktop.
Plan: OpenCode V1 loading of V2 configuration

V1 Loading of V2 Configuration

Status: Planned for dev.

Problem

OpenCode V1 and OpenCode V2 read configuration from the same global and project paths. OpenCode V2 commands continue to write native V2 fields. A user can therefore start with a valid V1 file, run a V2 command such as opencode2 mcp add, and produce a mixed document that V2 accepts but V1 cannot load.

The V1 decoder already ignores unknown object properties. Most V2-only top-level fields therefore do not cause a failure; they are simply unavailable to V1. Failures occur when both versions recognize the same key but assign it incompatible shapes. The important examples are:

  • V1 treats mcp as a flat server map, while V2 uses an object containing servers and timeout.
  • V1 accepts a string model, while V2 also accepts an explicit model-selection object.
  • V1 accepts a { paths, urls } skills object, while V2 accepts a string array.

V1 currently validates each parsed document as one ConfigV1.Info value. One incompatible recognized field rejects the whole document, including unrelated valid V1 settings.

Goal

The V1 runtime on dev should load V1, V2, and mixed V1/V2 configuration without rewriting the source document.

V1 should:

  • Preserve existing V1 behavior for valid V1 fields.
  • Lower recognizable V2 fields when V1 can provide equivalent or useful behavior.
  • Ignore unsupported V2 fields instead of rejecting the complete document.
  • Continue rejecting malformed values that match neither valid V1 nor recognizable V2 syntax.
  • Apply the same behavior to every configuration source and preserve existing source precedence.

Compatibility is best effort, not an exact V2-to-V1 round trip. V1 cannot implement V2-only runtime features.

Non-Goals

  • V2 commands will not write V1 syntax.
  • The compatibility path will not edit, migrate, or reformat configuration files.
  • V1 will not emulate V2-only runtime features.
  • The complete current V2 schema will not be copied into dev.
  • The older V2 schema already present in packages/core on dev will not define this compatibility contract. It is not synchronized with the current V2 format.

The V1 loader has pre-existing behavior that may create a global config or insert $schema when it is absent. That behavior is independent of this compatibility work.

Ownership

This is a read-time adapter for the legacy application, so its implementation belongs under:

packages/opencode/src/config/v2-compat.ts

It should not be added to the newer Core config loader. The adapter is invoked only by the V1 application.

The integration point is loadConfig in packages/opencode/src/config/config.ts, after variable substitution and JSONC parsing but before ConfigV1.Info decoding:

const parsed = ConfigParse.jsonc(expanded, source)
const lowered = ConfigV2Compat.lower(parsed)
const data = ConfigParse.schema(ConfigV1.Info, lowered.value, source)

This placement applies compatibility independently to each source before sources are merged. It covers global, project, explicit, environment-content, remote, account, and managed configuration while retaining the existing precedence model.

Schema Strategy

The destination remains the existing ConfigV1.Info schema. It is the final authority on values consumed by V1.

The adapter defines only permissive input schemas for current V2 shapes that can be lowered. These schemas are not a second complete V2 config schema. They are narrow decoders such as:

ModelSelectionV2
PermissionRuleV2
AgentV2
CommandV2
PluginV2
McpConfigV2
McpServerV2
ProviderV2
ProviderModelV2

Each input field is decoded independently. Unknown members are ignored. A malformed or unsupported member does not prevent other supported members of the same document from loading.

The adapter must not decode the entire document through the older Config.Info on dev. That schema predates the current V2 format and would reject or misinterpret newer valid values.

Precedence

Within one document, a successfully lowered V2 value takes precedence over the V1 form of the same canonical setting. This matches the current V2 mixed-config policy and treats explicitly written native V2 syntax as the newer intent.

If the V2 value is malformed or cannot be lowered at all, a valid V1 value remains in effect. Unsupported leaves inside an otherwise usable V2 entry are omitted without discarding the complete entry.

Configuration source precedence remains unchanged because lowering happens before the existing source merge.

Compatibility Matrix

Directly Compatible

These fields already have compatible encoded shapes. They remain in place and are validated by ConfigV1.Info:

V2 field V1 behavior
$schema Preserved.
shell Preserved.
default_agent Preserved.
autoupdate Preserved when the value is accepted by V1.
share Preserved.
enterprise Preserved for fields understood by V1.
username Preserved.
watcher Preserved for the shared shape.
formatter Preserved for entries accepted by V1.
lsp Preserved when the entry satisfies V1 requirements.
tool_output Preserved.
instructions Preserved.
references Preserved.

Fully Lowerable

These V2 fields have a V1 representation for their supported current shape:

V2 field V1 output Notes
snapshots snapshot Boolean value is unchanged.
media attachment Image settings are retained.
commands command template, description, agent, subtask, and representable model selection are retained.
plugins plugin Strings remain strings; { package, options } becomes [package, options].
Basic local MCP server Flat mcp[name] command, cwd, and environment are retained.
Basic remote MCP server Flat mcp[name] url, headers, and representable OAuth settings are retained.
MCP disabled MCP enabled The boolean is inverted.
OAuth snake-case keys OAuth camel-case keys client_id, client_secret, callback_port, and redirect_uri are renamed.
compaction.keep.tokens compaction.preserve_recent_tokens Numeric value is retained.
compaction.buffer compaction.reserved Numeric value is retained.
compaction.auto compaction.auto Boolean value is unchanged.

Partially Lowerable

These fields are lowered entry by entry. Unsupported leaves are omitted while useful V1 behavior is retained:

V2 field V1 output Limitation
Top-level model object model: "provider/model" A top-level variant has no V1 representation and is ignored. String selections already remain compatible.
skills array skills.paths and skills.urls HTTP(S) URLs are classified as URLs; other values are paths. V2 ordering between paths and URLs cannot be preserved.
agents agent Basic identity, prompt, model, permissions, color, mode, visibility, and step settings are lowered.
Agent system Agent prompt Content is retained.
Agent disabled Agent disable Boolean value is retained.
Agent request.body Agent options Body values are retained, but their original V1 spelling cannot be recovered.
Agent model selection Agent model and variant Representable without loss.
permissions permission Rules are grouped by action and resource. Exact ordering is not always representable.
Permission shell Permission bash Action is renamed.
Permission subagent Permission task Action is renamed.
MCP server timeout Scalar server timeout Emitted only when catalog and execution agree and no incompatible startup value is required.
Global MCP timeout experimental.mcp_timeout Emitted only when one scalar safely represents the configured phases.
providers provider Basic provider and model metadata, options, headers, limits, modalities, and known package mappings are lowered.
Provider model selection/package V1 provider/model fields Only package identities usable by V1 are retained.
Provider model variants V1 variant map Only unique, settings-only variants are representable.
experimental.policies enabled_providers or disabled_providers Only the canonical provider allowlist/denylist patterns are lowered.

For repeated V2 permission rules targeting the same action and resource, the final matching rule wins. The adapter must not claim to preserve arbitrary ordered-rule semantics after grouping rules into the V1 object format.

Accepted but Ignored

These current settings have no reliable V1 equivalent. Their presence must not reject the document:

V2 field Reason
websearch V1 has no equivalent provider-selection configuration.
warming V1 has no equivalent warming policy.
experimental.portable_shell_scanner V1 has no corresponding behavior.
MCP codemode V1 cannot expose MCP tools through V2 Code Mode.
Independent MCP timeout phases V1 supports only one scalar timeout.
Agent request.headers V1 agents have no equivalent request-header field.
Arbitrary ordered provider policies V1 only supports provider allow and deny lists.
Current-only plugin directives or built-in IDs V1 may misinterpret them as package specifications.
Provider/model transport compatibility flags V1 cannot reproduce current transport behavior.
Provider/model request body overlays without a safe V1 mapping Treating them as ordinary options could change semantics.
Multiple provider cost tiers V1 cannot represent the general current tier model.
Model response-WebSocket capability V1 has no equivalent capability.
Model compatibility fields without V1 equivalents Includes current-only token and finish-reason behavior.

Unknown V2 top-level fields continue to be ignored by the existing excess-property decoding policy.

Invalid Input Policy

The adapter distinguishes recognizable V2 syntax from malformed V1 syntax:

  • A valid V2-shaped collision is lowered or ignored instead of reaching the incompatible V1 field decoder.
  • A valid V1-shaped value continues through unchanged.
  • A value matching neither shape continues to fail V1 validation.
  • A malformed entry inside a V2-only plural map is skipped without rejecting valid sibling entries.
  • Discarded or lossy values produce path-based diagnostics in logs without changing the source file.

This policy prevents V2 additions from making V1 unusable without turning all V1 configuration mistakes into silent failures.

Implementation Plan

  1. Add integration fixtures on dev that reproduce V1 failures for current V2 mcp, object model, and array skills.
  2. Add the adapter and field-level schemas under packages/opencode/src/config/v2-compat.ts.
  3. Invoke it from loadConfig before ConfigV1.Info decoding.
  4. Implement collision handling first so recognizable V2 shapes cannot reject complete documents.
  5. Add direct renames and fully lowerable fields.
  6. Add agents, commands, plugins, permissions, and skills with explicit lossy behavior.
  7. Add conservative provider/model lowering separately because it has the largest compatibility surface.
  8. Add path-based diagnostics for ignored and lossy values.
  9. Add mixed V1/V2 conflict tests and preserve native V2 precedence.
  10. Verify the dev V1 binary against isolated current-V2 fixtures, including a file modified by opencode2 mcp add.

Verification

Tests should establish these invariants:

  • Every lowered result decodes successfully as ConfigV1.Info.
  • Valid V1 configuration has unchanged decoded behavior.
  • Recognizable V2-only fields never reject an otherwise usable document.
  • Malformed V1 values still fail.
  • Mixed flat V1 and enveloped V2 MCP servers both load.
  • V2 wins only when its value was successfully lowered.
  • Unsupported leaves do not discard supported sibling settings.
  • Lowering is pure and does not mutate the parsed input or source file.
  • Per-source lowering preserves existing global/project/managed precedence.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment