Skip to content

feat: fetch GonkaGate models dynamically #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Dankosik merged 1 commit into from
Jul 6, 2026
Merged

feat: fetch GonkaGate models dynamically #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 24 additions & 32 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,12 @@ npx @gonkagate/opencode-setup
Current honest state:

- the real end-to-end public installer flow is implemented
- the public CLI validates local `opencode`, resolves a curated model and
scope, collects a GonkaGate API key through the supported safe inputs before
managed writes, verifies both the durable and current-session effective
- the public CLI validates local `opencode`, collects a GonkaGate API key through the supported safe inputs, fetches live models, resolves model and scope before managed writes, verifies both the durable and current-session effective
OpenCode config, and ends with plain `opencode`
- the product docs, CI, package contract, and PRD are implemented and now
describe the shipped runtime
- the public curated model picker is shipped and currently exposes three
validated models
- the installer writes every validated curated model into
- the live GonkaGate model picker is shipped and uses the `/v1/models` response
- the installer writes every fetched GonkaGate model id into
`provider.gonkagate.models` so OpenCode's `/models` command can switch
between managed GonkaGate models after setup
- native Windows support is part of the current contract and is backed by
Expand All @@ -43,16 +40,16 @@ The intended happy path is:

1. user runs `npx @gonkagate/opencode-setup`
2. installer validates local `opencode`
3. installer offers the public curated model picker in interactive mode and
accepts recommended defaults through `--yes` or safe non-interactive
selection rules
4. installer asks for `user` or `project` scope
5. installer collects a GonkaGate `gp-...` key through a hidden prompt,
3. installer collects a GonkaGate `gp-...` key through a hidden prompt,
`GONKAGATE_API_KEY`, or `--api-key-stdin`
6. installer writes the minimum safe OpenCode config layers
7. installer verifies the durable OpenCode config and the current session's
4. installer fetches `GET https://api.gonkagate.com/v1/models` with Bearer auth
5. installer offers the live GonkaGate model picker in interactive mode and
accepts defaults through `--yes` or safe non-interactive selection rules
6. installer asks for `user` or `project` scope
7. installer writes the minimum safe OpenCode config layers
8. installer verifies the durable OpenCode config and the current session's
effective OpenCode config
8. user returns to plain `opencode`
9. user returns to plain `opencode`

For `project` scope, the user-level config owns the provider definition and
secret binding, while the repository-local `opencode.json` contains only
Expand All @@ -75,14 +72,14 @@ refactor; it is a product change.
replacement for the global config target
- `OPENCODE_CONFIG_CONTENT` is a runtime-only higher-precedence override layer,
not a durable install target
- interactive mode keeps the public curated model picker visible even when only
one validated model is currently available
- `--yes` and safe non-interactive flows may accept the recommended validated
model without showing the picker
- interactive mode keeps the live GonkaGate model picker visible even when only
one GonkaGate model is currently available
- `--yes` and safe non-interactive flows may accept the first fetched model
without showing the picker
- project config target is `opencode.json`
- the managed user-level provider key is `provider.gonkagate`
- the managed user-level provider catalog under `provider.gonkagate.models`
includes every public validated curated model
includes every model id returned by `/v1/models`
- `project` scope writes only activation settings
- repo-local `opencode.json` rewrites must keep rollback backups under
`~/.gonkagate/opencode/backups/project-config` instead of beside the
Expand All @@ -103,8 +100,8 @@ refactor; it is a product change.
--pure` as the final truth source instead of reimplementing the full
upstream merge engine
- resolved effective-config verification must stay responsible for `model`,
`small_model`, `provider.gonkagate`, validated transport and base URL shape,
curated model-catalog shape, and provider allow/deny gating
`small_model`, `provider.gonkagate`, transport and base URL shape,
live model-catalog shape, and provider allow/deny gating
- secret-binding provenance verification must separately enforce
`provider.gonkagate.options.apiKey` ownership instead of inferring it from
redacted resolved-config output
Expand Down Expand Up @@ -145,13 +142,12 @@ refactor; it is a product change.
- shell profile mutation is out of scope
- `.env` file generation is out of scope
- arbitrary custom base URLs are out of scope for v1
- arbitrary custom model ids are out of scope for v1
- arbitrary model ids not returned by `/v1/models` are out of scope for v1
- the installer must not depend on `gonkagate doctor`
- `small_model` is explicitly set by the runtime
- `model` and `small_model` select the setup default; they are not the full
GonkaGate model catalog
- the curated model registry contract must be able to carry compatibility
metadata required for validated OpenCode flows, not only model ids
- the live `/v1/models` response is the runtime source of truth for model availability

## Security Invariants

Expand Down Expand Up @@ -199,11 +195,7 @@ These are implementation facts today, not future plans:
installer-owned scope normalization, separate resolved-config versus
secret-binding provenance verification, redacted effective-config
diagnostics, and the end-to-end installer flow
- the curated model registry under `src/constants/models.ts` now includes
pinned public validated entries for
`qwen/qwen3-235b-a22b-instruct-2507-fp8`,
`moonshotai/Kimi-K2.6`, and `minimaxai/minimax-m2.7`, with Kimi K2.6 marked
as the recommended default
- the installer fetches `GET https://api.gonkagate.com/v1/models` after API-key intake and uses the live response for model selection, `--model` validation, provider catalog writes, and verification
- a mirrored skill pack is present under `.agents/skills/` and
`.claude/skills/`, imported from `codex-setup` as an initial shared
engineering baseline
Expand All @@ -221,8 +213,8 @@ This repo currently does:
- define the product contract for the OpenCode setup tool
- define security, scope, and transport constraints
- provide npm packaging, CI, release-please, and publish scaffolding
- provide a working public CLI entrypoint with a curated public model picker
- provide end-to-end managed config writes, a validated GonkaGate model catalog
- provide a working public CLI entrypoint with a live GonkaGate model picker
- provide end-to-end managed config writes, a fetched GonkaGate model catalog
for OpenCode `/models` switching, scope-aware ownership, rerun-safe rollback,
and redacted effective-config verification under `src/install/`
- provide docs and tests that protect the current contract
Expand Down Expand Up @@ -327,7 +319,7 @@ When behavior changes:
The installer is now real:

- remove or revise any wording that drifts back toward scaffold-only language
- update the curated model registry truth when the public picker changes
- no repository update is needed when GonkaGate adds or removes a model from `/v1/models`
- add runtime behavior tests before claiming any new end-user capability

## Validation
Expand Down
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# Changelog

## Unreleased

### Features

* fetch the GonkaGate model catalog from `/v1/models` during setup

## [0.5.1](https://github.com/GonkaGate/opencode-setup/compare/v0.5.0...v0.5.1) (2026-06-23)


Expand Down
68 changes: 33 additions & 35 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,13 +57,13 @@ npx @gonkagate/opencode-setup

The happy path is:

1. The CLI checks that `opencode` is installed and supported.
2. It shows the public curated model picker.
3. It asks whether GonkaGate should be activated for `user` or `project`
scope.
4. It asks for your GonkaGate API key in a hidden prompt.
5. It writes the managed config, verifies the result, and tells you to go back
to plain `opencode`.
1. CLI checks `opencode` is installed and supported.
2. It asks for your GonkaGate API key through a hidden prompt.
3. It fetches `GET https://api.gonkagate.com/v1/models` with Bearer auth.
4. It shows the live GonkaGate model picker.
5. It asks whether GonkaGate should be activated in `user` or `project` scope.
6. It writes managed config, verifies the result, and tells you to go back to
plain `opencode`.

### Non-interactive setup

Expand Down Expand Up @@ -115,19 +115,19 @@ npx @gonkagate/opencode-setup
Under the hood, the shipped runtime:

- validates local `opencode`
- keeps the public curated model picker visible in interactive mode, even
as the curated validated model list grows
- resolves the curated validated model and activation scope
- accepts the secret only through a hidden prompt, `GONKAGATE_API_KEY`, or
`--api-key-stdin`
- fetches `GET https://api.gonkagate.com/v1/models` with Bearer auth after
API-key intake
- uses the live response for the model picker, `--model` fetched model id
validation, defaults, config writes, and verification
- writes only the minimum safe OpenCode config layers
- verifies both the durable plain-`opencode` outcome and the current session's
- verifies the durable plain-`opencode` outcome and the current session
effective OpenCode outcome
- finishes by returning the user to plain `opencode`

For `project` scope, the installer keeps the provider definition and secret
binding in user scope and writes only activation settings to repo-local
`opencode.json`.
For `project` scope, installer keeps the provider definition and secret binding
in user scope and writes only activation settings to repo-local `opencode.json`.

## Where Files Go

Expand Down Expand Up @@ -176,31 +176,29 @@ rely on inherited per-user ACLs instead of portable `chmod`-style enforcement.

## Current Product Truth

The current public curated model picker is shipped and currently exposes three
validated models:
The live GonkaGate model picker is backed by:

- `qwen/qwen3-235b-a22b-instruct-2507-fp8`
- `moonshotai/Kimi-K2.6`
- `minimaxai/minimax-m2.7`
```http
GET https://api.gonkagate.com/v1/models
Authorization: Bearer <GonkaGate API key>
```

Interactive mode keeps the public curated model picker visible. `--yes` and
safe non-interactive flows may auto-select the recommended validated model
without showing the picker.
That response is the source of truth for picker choices, `--model` fetched
model id validation, defaults, config writes, and verification. Interactive mode
keeps the live picker visible. `--yes` safe non-interactive flows may
auto-select the first fetched model without showing the picker.

The runtime is curated-model-first:
The runtime live-model-first contract:

- the stable provider id is `gonkagate`
- the managed user-level provider key is `provider.gonkagate`
- the canonical base URL is `https://api.gonkagate.com/v1`
- the current transport target is `chat/completions`
- stable provider id is `gonkagate`
- managed user-level provider key is `provider.gonkagate`
- canonical base URL is `https://api.gonkagate.com/v1`
- current transport target is `chat/completions`
- future migration should add `responses` support without renaming the product
- the installer writes every validated curated GonkaGate model into
`provider.gonkagate.models` so OpenCode's `/models` command can switch
between managed GonkaGate models
- the selected setup model remains the activation default through `model` and
- installer writes every fetched model id into `provider.gonkagate.models` so
OpenCode's `/models` command can switch between managed GonkaGate models
- selected setup model remains the activation default through `model` and
`small_model`
- the curated registry can carry compatibility metadata, provider options,
model options, and headers when a validated OpenCode flow needs them

## Verification And Config Precedence

Expand All @@ -209,8 +207,8 @@ Success is based on effective OpenCode config.

For durable verification, `opencode debug config --pure` stays the final truth
source. The installer uses that resolved result to verify `model`,
`small_model`, `provider.gonkagate`, the validated transport and base URL
shape, the curated model-catalog shape, and provider allow/deny gating.
`small_model`, `provider.gonkagate`, the transport and base URL
shape, the live model-catalog shape, and provider allow/deny gating.

OpenCode precedence matters here:

Expand Down
2 changes: 1 addition & 1 deletion docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
This repository currently contains:

- the shipped installer runtime for `@gonkagate/opencode-setup`
- the public CLI, curated model picker UI, and rerun-safe rollback behavior
- the public CLI, live GonkaGate model picker UI, and rerun-safe rollback behavior
- Phase 1 through Phase 5 runtime implementation under `src/install/`
- CI and release tooling
- the final product contract
Expand Down
53 changes: 12 additions & 41 deletions docs/architecture-decisions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,54 +49,26 @@ Verified upstream facts used here:
- `opencode debug config` outputs resolved config values, including substituted
secret material, so raw output is secret-bearing.

## Decision 1: Expose only validated curated GonkaGate models
## Decision 1: Use the live GonkaGate model catalog

**Decision**

The runtime must expose only curated model entries marked `validated`, with one
explicit recommended default for automation-safe flows.
After API-key intake, the runtime fetches `GET https://api.gonkagate.com/v1/models` with Bearer auth and uses only that response for model availability.

- the installer keeps the public curated picker visible in interactive mode
- `--yes` and safe non-interactive flows may auto-select the recommended
validated model
- `model` and `small_model` are both set to the selected validated model
- every validated curated model is written to `provider.gonkagate.models` so
OpenCode's `/models` command can switch between managed GonkaGate models
- additional public model choices may land after they pass the same validation
gate
- installer keeps the live GonkaGate model picker visible in interactive mode
- `--yes` safe non-interactive flows may auto-select the first fetched model
- `--model` must match a fetched model id
- `model` and `small_model` are both set to the selected fetched model id
- every fetched model id is written to `provider.gonkagate.models` so OpenCode.s `/models` command can switch managed GonkaGate models
- adding or removing a GonkaGate model does not require a repository update

**Rationale**

The safest public shape is to keep the picker visible in interactive mode while
still allowing automatic recommended-default behavior when prompts are
intentionally bypassed:

- bounded compatibility surface
- smallest rollback surface
- no ambiguity about the recommended default in automation-safe paths
- stable public UX even as more validated models are added later
- no hidden dependency on unproven model variants

What matters architecturally is not guessing a model name early. What matters
is forcing the runtime to ship only behind end-to-end proof.
GonkaGate owns model availability. Keeping the catalog in the API avoids stale CLI releases and removes repository-owned allowlists from user-facing setup behavior.

**Implementation consequence**

- The runtime must refuse to expose or auto-fallback to any model that is not
marked `validated`.
- The curated registry should add explicit default-selection metadata such as
`recommended: true` rather than relying on array order once multiple
validated models exist.
- The managed provider catalog should be derived from validated registry
entries, while `model` and `small_model` remain only the setup defaults.
- Each public GonkaGate model ID must be pinned in a model validation record
before it is exposed through the picker or provider catalog.

**What this means for v1**

- Every public picker entry must pass the validation matrix from the PRD.
- Interactive users still see the public picker, while `--yes` and safe
non-interactive flows may accept the recommended default.
The runtime rejects empty or invalid model responses and rejects `--model` values not returned by `/v1/models`.

## Decision 2: Do not reconcile or mutate `OPENCODE_CONFIG` in v1

Expand Down Expand Up @@ -220,8 +192,7 @@ At minimum, the verification gate should confirm:
- `small_model` resolves to the same v1 model
- `provider.gonkagate` is present with the expected transport package and base
URL
- required compatibility fragments and model catalog entries from the curated
registry are present
- every fetched model catalog entry is present
- no higher-precedence layer excludes `gonkagate`

## Decision 4: Prefer the plugin-safe verification path when available
Expand Down Expand Up @@ -343,7 +314,7 @@ These decisions fix the v1 production shape as follows:

- only validated GonkaGate models are exposed, with later choices gated by the
same validation bar
- interactive public picker remains visible while the curated model list is
- interactive public picker remains visible while the live model list is
small
- durable writes only to the documented user config target, project activation
file, and GonkaGate-managed user storage
Expand Down
Loading
Loading