Skip to content

Free plan: use the server's model for every role the user didn't set - #245

Merged
AdamT merged 1 commit into
mainfrom
free-models
Nov 16, 2026
Merged

AdamT merged 1 commit into
mainfrom
free-models

Conversation

@AdamT

@AdamT AdamT commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Intent

When the server's model list says a person is on the Free plan, kai uses the server's model for every role the person didn't set, commit review included. A model the person did set that the Free plan doesn't include is not run: the command stops and says so in one sentence.

Nothing changes for anyone the server doesn't mark as Free. Their model list has no free key, and every role, review stage and default is exactly as today (TestFreePlan_NoFreeKeyChangesNothing). The only new thing is one GET /api/v1/llm/models per command, with a 3-second limit; any failure reads as "not Free".

What a Free user sees

  • Roles nobody set run the server's defaults, silently: executor coder, planner planner, chat chat, and the classifier and commit review agent (the server sends no key for those two).
  • Models chosen outside the config follow too: a review stage on its own built-in default (finder2, sweep2, rank, humanize), the critic and the consult tool run the server's agent model; the fast pass doesn't swap in its own model, and the planner's finalize turn keeps the planner's.
  • A model they set (a KAI_*_MODEL variable, --planner-model/--agent-model where the command applies them, or .kai/config.yaml; a config value equal to the built-in default counts as unset) that the Free plan doesn't include stops the command:
    <model> isn't available on the Free plan. Choose another model, or upgrade: <server>/billing.
    A model they set that the plan does include runs as asked. KAI_OPENAI_MODEL/KAI_ANTHROPIC_MODEL (read only by a provider the person brought) and an "off"/"disabled" value don't count.
  • A review whose models were chosen for it (the server sent a set, KAI_REVIEW_SET_VERSION, or a profile is loaded) keeps them and is never stopped.

The provider stays *provider.Kailab (no wrapper), so the engine's end-of-run cost and transcript uploads still find it.

Also in this PR

Four comments and two tests on main described the Free set by vendor; they now describe it by what it does (review_commit_backups.go, review_commit_retry.go, usage_view.go, TestFreeSetWithAFailingModelStaysInItsSet, TestUsageFreeReviews). Test ids are placeholders (free/model-fast, free/model-strong, free/model-small).

How

  • internal/freeplan: reads the list once per process (free, defaults, the included ids), resolves a role, and Checks the person's models.
  • internal/config: Load records which role sections of .kai/config.yaml set a model (ModelsSet).
  • cmd/kai/free_plan.go: the role table; called where the TUI, the headless agent and buildGateProvider (commit review, gate) resolve models. The TUI stops before it opens.

Tests

  • internal/freeplan: the list with and without free, included ids, role resolution, the stop sentence.
  • cmd/kai/free_plan_test.go against a fake model list: no free key changes nothing; unset roles take the defaults; an env, flag or config model the plan doesn't include stops the command (and commit review) with the sentence; an included one runs; commit review on Free (review model, fast pass, ensemble stages, consult); a server-chosen review keeps its models.
  • go test ./... passes, also with -count=2 for these tests.

🤖 Generated with Claude Code


Kai context

Written by Kai from the change itself. Kai only edits this section; everything above it is the author's.

On the Free plan, kai now runs the server's model for every role the person didn't set, and stops with one sentence if a model they did set isn't included in the plan. Anyone the server doesn't mark as Free sees no change.

Changes

  • internal/freeplan (new): Fetch does one GET /api/v1/llm/models with a 3-second limit, and any failure gives the zero Plan ("not Free"). Current caches the result once per process. Allows, Default, Resolve and Check cover the included ids, the per-role defaults (falling back to the agent key) and the stop sentence with the <server>/billing link.
  • internal/config: Load fills the new Config.ModelsSet with the role sections of .kai/config.yaml that set a model, including sections written as yaml aliases. The field is excluded from yaml and JSON.
  • cmd/kai/free_plan.go (new): cliFreePlan only asks for Kai's own provider. applyFreePlan rewrites the unset role models for agent, planner, chat, classifier and review. It first runs Check over explicitModels (the KAI_*_MODEL(S) variables, minus KAI_OPENAI_MODEL, KAI_ANTHROPIC_MODEL and off/none/disabled values, plus the config and flag models). A config value equal to the built-in default counts as unset. freeDefault exposes the server's model to code that picks models outside the config.
  • Call sites: buildAgentServices (agentsvc.go), buildPlannerServices (tui.go) and buildGateProvider (gate.go) call applyFreePlan. The TUI keeps the error in freePlanStop, and runCodeTUI returns it before opening. The provider stays *provider.Kailab.
  • Models chosen outside the config:
    • rcEnsembleModel uses the server's model for a stage on its own default.
    • rcFastModel doesn't swap in its substitute model.
    • consultModelFromEnv uses the server's model.
    • The critic gets CriticModel.
    • The planner finalize fallback to z-ai/glm-5.1 is skipped on Free.
  • Server-chosen reviews: rcReviewModelsChosen (review_commit_profile.go) is true when a profile is loaded or KAI_REVIEW_SET_VERSION is set. In that case buildGateProvider doesn't apply the plan.
  • rcReviewProvider: now returns an error as a fourth value, set only for the Free stop (freeStopError), so review_commit.go and review_replay.go show the sentence instead of "run kai login". The two test callers are updated.
  • Wording only: comments in review_commit_backups.go, review_commit_retry.go and usage_view.go, and the test names, ids and comments in review_commit_partial_test.go and usage_view_test.go, no longer name a vendor.

Testing

  • internal/freeplan: the list with and without free, included ids (including the :reasoning variant), unreachable servers, Resolve, and Check with its exact sentence.
  • internal/config: ModelsSet next to top-level scalars, through a yaml alias, and absent from the JSON form.
  • cmd/kai/free_plan_test.go, against a fake model list:
    • TestFreePlan_NoFreeKeyChangesNothing: with no free key, nothing changes.
    • TestFreePlan_UnsetRolesTakeServerDefaults: unset roles take the server defaults.
    • TestFreePlan_SetModelNotOnThePlanStops: an env or flag model outside the plan stops the command, and commit review stops too.
    • TestFreePlan_SetModelOnThePlanRuns: an included model runs.
    • TestFreePlan_ConfigModels: config models, and a config value equal to the default counting as unset.
    • TestFreePlan_CommitReview: commit review, fast pass, ensemble stages and consult on Free.
    • TestFreePlan_CommitReviewStopShown: the stop shown by rcReviewProvider.
    • TestFreePlan_ServerChosenReviewKeepsItsSet: a server-chosen review keeps its models.
    • TestFreePlan_FlagNotAppliedDoesntCount: an unapplied flag doesn't count.

@kaicontext kaicontext Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewView in KaiKai review · Ready to merge (10/10)

Read the whole thing — it does what it says, and nothing jumped out at me.

Next: merge when your checks are green — I found nothing to fix.

Important files changed
File Change
cmd/kai/agentsvc.go modified · +7 −0
cmd/kai/free_plan.go modified · +153 −0
cmd/kai/free_plan_test.go modified · +297 −0
cmd/kai/gate.go modified · +14 −0
cmd/kai/review_commit.go modified · +15 −6
cmd/kai/review_commit_backups.go modified · +1 −1
cmd/kai/review_commit_challenge_test.go modified · +1 −1
cmd/kai/review_commit_citation_test.go modified · +1 −1

+13 more changed files in the full analysis.

How I reviewed it — 18 files, 16 turns, 3m14s

Free-plan model resolution matches its stated intent, does nothing without a free key, and every changed file checked out with no behavioural defect or nit found.

What I opened
7 of the 21 changed files don't appear below: cmd/kai/review_commit_challenge_test.go, cmd/kai/review_commit_citation_test.go, cmd/kai/review_commit_partial_test.go, cmd/kai/usage_view_test.go, internal/config/config_test.go, internal/freeplan/freeplan.go, internal/freeplan/freeplan_test.go.

  • cmd/kai/agentsvc.go
  • cmd/kai/free_plan.go
  • cmd/kai/free_plan_test.go
  • cmd/kai/gate.go
  • cmd/kai/review_analyze.go
  • cmd/kai/review_commit.go
  • cmd/kai/review_commit_backups.go
  • cmd/kai/review_commit_batches.go
  • cmd/kai/review_commit_ensemble.go
  • cmd/kai/review_commit_fast.go
  • cmd/kai/review_commit_profile.go
  • cmd/kai/review_commit_retry.go
  • cmd/kai/review_commit_sweep.go
  • cmd/kai/review_replay.go
  • cmd/kai/tui.go
  • cmd/kai/usage_view.go
  • internal/config/config.go
  • internal/tui/views/critic.go
Full read-through

Scope: kaicontext/kai-cli at the merged commit, the same code as my earlier review. I have now read every changed file:

  • the Free-plan code (free_plan.go, freeplan.go, config.go) and its tests;
  • the provider-resolution sites (gate.go, agentsvc.go, tui.go, review_commit.go, review_replay.go);
  • the review-stage hooks (review_commit_ensemble.go, review_commit_fast.go, review_commit_profile.go);
  • the reworded comments and tests.

I did not run the tests. I did not read the engine code that consumes CriticModel, beyond resolveCriticModel in internal/tui/views/critic.go. I also cannot see what the real server sends in the free and defaults fields.

What it does: The change asks GET /api/v1/llm/models once per process, with a 3-second limit. Any failure, a non-Free caller, or a non-Kai provider gives a zero Plan, and then applyFreePlan, freeDefault, the ensemble, fast-pass and consult hooks, and the finalize-turn guard all do nothing.

On Free:

  • applyFreePlan first runs Check over every model the person named. That covers KAI_*_MODEL(S) variables with comma lists split, flags the command applied, and config values that differ from the default. A model the plan doesn't include returns a freeStopError.
  • It then writes the person's env value into cfg for each role, and gives each unset role the server default.
  • rcReviewProvider unwraps the stop with errors.As, so kai review-commit and review_replay show the sentence instead of "run kai login".
  • buildGateProvider skips the plan entirely when the review's models were chosen for it. That is rcActiveProfile != nil or KAI_REVIEW_SET_VERSION set. runReviewCommit loads the profile before it calls rcReviewProvider, so the check sees it.
  • Profile stage settings still win over the Free substitution in rcEnsembleModel, because rcStageModel runs after it.
  • The TUI stops through freePlanStop before it opens.
  • The provider stays *provider.Kailab.

Callers: I checked each caller of the changed rcReviewProvider signature: review_commit.go, review_replay.go and the two live tests. All handle the new return value. judgeProvider in review_analyze.go calls buildGateProvider and drops any error. On Free with a disallowed model, that analyzer silently degrades to no should-touch findings. It was already that lenient for provider errors, so it is not a regression.

Tests: They cover the real behaviours. The no-free-key case checks that nothing changes. The stop cases check the exact sentence, including through buildGateProvider and rcReviewProvider. A model the plan includes runs as asked. Config values equal to the default count as unset. A server-chosen review keeps its built-in models. signInTo clears every KAI_*_MODEL(S) variable and the role flags and restores the globals, so the tests don't depend on the developer's shell and survive -count=2.

Withdrawn: In my first pass this session I raised a nit about the ModelsSet comment at internal/config/config.go:28, saying it contradicted roleSetInConfig. That was wrong. modelsSetIn records any non-empty model, including one equal to the default, and roleSetInConfig applies the default-value filter afterwards. The comment describes ModelsSet accurately.

I found no defect with a reachable trigger.

Merge readiness: merge.

Size L · Risk M · +887 −27 · 21 files · reaches 97 · the full analysis · Reply to any of my comments and I'll answer, or say @kaicontext anywhere on this PR — a question, or "take another look at the retry logic". · Some repos review new pushes only when asked. Comment @kaicontext review any time for a review right away.
Kept up to date: this is update 15, for 66a2c67. Earlier points that still apply stay on their lines.

Comment thread cmd/kai/free_plan.go Resolved
Comment thread cmd/kai/free_plan.go Resolved
Comment thread cmd/kai/free_plan_test.go Resolved
@AdamT
AdamT marked this pull request as draft November 16, 2026 05:59

@kaicontext kaicontext Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kai · 1 new point on 31d88cf — on the lines below. The review is updated.

Comment thread internal/config/config.go Resolved
@AdamT AdamT changed the title Free plan: run the server's Google models for every role nobody set Free plan: use the server's model for every role the user didn't set Nov 16, 2026
@AdamT
AdamT marked this pull request as ready for review November 16, 2026 06:10

@kaicontext kaicontext Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kai · 1 new point on 84ca890 — on the lines below. The review is updated.

Comment thread internal/config/config.go Resolved
@AdamT

AdamT commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

@kaicontext review

@kaicontext

kaicontext Bot commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

On it. The review will appear on this pull request in a few minutes.

@AdamT

AdamT commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

@kaicontext Your review says the change "does only part of what the description says". Which part of the description do you find the code doesn't do?

@kaicontext

kaicontext Bot commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

That line isn't mine — I didn't post a "does only part of what the description says" comment, and it's not in what you quoted from my review above. Can you point me at where that's written? If it's in a different comment on this PR I haven't seen it, and I'd want to check the actual wording before answering.

@AdamT

AdamT commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

@kaicontext review

@kaicontext

kaicontext Bot commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

On it. The review will appear on this pull request in a few minutes.

@AdamT
AdamT force-pushed the free-models branch 2 times, most recently from ccab8b3 to 23343db Compare November 16, 2026 08:33
@AdamT

AdamT commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

@kaicontext review

@kaicontext

kaicontext Bot commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

On it. The review will appear on this pull request in a few minutes.

@kaicontext kaicontext Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kai · 1 new point on 23343db — on the lines below. The review is updated.

Comment thread cmd/kai/free_plan.go Resolved
@AdamT

AdamT commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

@kaicontext review

@kaicontext

kaicontext Bot commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

On it. The review will appear on this pull request in a few minutes.

@AdamT

AdamT commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

@kaicontext review

@kaicontext

kaicontext Bot commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

On it. The review will appear on this pull request in a few minutes.

@kaicontext kaicontext Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kai · 1 new point on 523e69c. The review is updated.

  • Fix before merge rcReviewProvider drops the error returned by buildGateProvider and returns nil, "", "", so the Free-plan refusal for a commit-review model outside the plan becomes "no LLM provider available (run kai login)". (also: cmd/kai/review_replay.go:146)

When the model list (GET /api/v1/llm/models) says the caller is on the
Free plan, kai uses the server's defaults for every role whose model the
person didn't set: the executor (coder), planner, chat, and the
classifier and commit review (agent). Models chosen outside the config
follow too: a review stage on its own default, the critic and the
consult tool run the server's agent model; the fast pass doesn't swap in
its own model, and the planner's finalize turn keeps the planner's.

A model the person did set (a KAI_*_MODEL variable, --planner-model or
--agent-model where applied, or a .kai/config.yaml value other than
the built-in default) that the Free plan doesn't include is not run: the command stops
with "<model> isn't available on the Free plan. Choose another model, or
upgrade: <server>/billing." config.Load records which role sections set
a model (Config.ModelsSet); a value equal to the built-in default
counts as unset.

A review whose models were chosen for it (the server sent a set, or a
profile is loaded) keeps them. The list is asked for once per command
with a 3-second limit; without a free key, or on any failure, nothing
changes. Four comments and two tests that described the Free set by
vendor now describe it by what it does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@AdamT

AdamT commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

@kaicontext review

@kaicontext

kaicontext Bot commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

On it. The review will appear on this pull request in a few minutes.

@AdamT
AdamT merged commit 2e85331 into main Nov 16, 2026
7 checks passed
@AdamT
AdamT deleted the free-models branch November 16, 2026 12:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant