Skip to content

fix(agents): bootstrap non-main models.json on skip to prevent Unknown model after agents.create#1735

Open
BingqingLyu wants to merge 4 commits into
mainfrom
fork-pr-58373-fix-non-main-models-bootstrap
Open

fix(agents): bootstrap non-main models.json on skip to prevent Unknown model after agents.create#1735
BingqingLyu wants to merge 4 commits into
mainfrom
fork-pr-58373-fix-non-main-models-bootstrap

Conversation

@BingqingLyu

@BingqingLyu BingqingLyu commented Apr 27, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Summary

  • Problem: agents.create creates a valid non-main agent (config/workspace), but does not create models.json by design. Under a narrow startup path, this can later fail with Unknown model.
  • Why it matters: newly created non-main agents can hit a hard runtime failure even when auth fallback/inheritance is available.
  • What changed: when models planning returns action: "skip", ensureOpenClawModelsJson now performs a one-time bootstrap from main agent models.json only if target is non-main and target models.json is missing.
  • What did NOT change (scope boundary): no continuous global-to-agent sync, no overwrite of existing per-agent models.json, no change to agents.create behavior itself.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor required for the fix
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Auth / tokens
  • Skills / tool execution
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

Root Cause / Regression History (if applicable)

  • Root cause: planOpenClawModelsJson returns skip when providers resolve empty; ensureOpenClawModelsJson previously returned early (wrote: false) without creating/bootstrapping missing non-main models.json.
  • Missing detection / guardrail: no fallback path for missing non-main models.json in the skip branch.
  • Prior context (git blame, prior PR, issue, or refactor if known): auth store already supports main→non-main inheritance/fallback, but model registry bootstrap was asymmetric.
  • Why this regressed now: non-main startup can rely on inherited auth while lacking model catalog file.
  • If unknown, what was ruled out: not a request for full global sync; this is a narrow runtime-failure prevention path.

Regression Test Plan (if applicable)

  • Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
  • Target test or file: src/agents/models-config.skips-writing-models-json-no-env-token.test.ts
  • Scenario the test should lock in: non-main + missing target models.json + plan.action === "skip" + existing non-empty main models.json => target file is created from main.
  • Why this is the smallest reliable guardrail: it exercises the exact skip branch and validates one-time bootstrap behavior.
  • Existing test that already covers this (if any): none specific to this branch.
  • If no new test is added, why not: N/A (new test added).

User-visible / Behavior Changes

  • After agents.create, a newly created non-main agent that enters the empty-provider skip path no longer proceeds with a missing model catalog and Unknown model hard failure.

Diagram (if applicable)

Before:
agents.create -> non-main agent exists (no models.json by design)
-> startup path (providers empty -> skip)
-> no models.json
-> runtime Unknown model

After:
agents.create -> non-main agent exists (no models.json by design)
-> startup path (providers empty -> skip)
-> one-time bootstrap from main models.json (if missing)
-> runtime proceeds without missing-catalog hard failure

## Security Impact (required)

- New permissions/capabilities? `No`
- Secrets/tokens handling changed? `No`
- New/changed network calls? `No`
- Command/tool execution surface changed? `No`
- Data access scope changed? `No`
- If any `Yes`, explain risk + mitigation: N/A

## Repro + Verification

### Environment

- OS: macOS 26 / Windows 11 (repro path observed in Windows packaging workflow)
- Runtime/container: Node 22+
- Model/provider: any provider/model requiring model registry lookup
- Integration/channel (if any): N/A
- Relevant config (redacted): standard multi-agent config with non-main agent created via `agents.create`
- Reproduced on: `v2026.3.28` and `main` (HEAD as of `2026-03-31`)

### Steps

1. Call `agents.create` to create a new non-main agent.
2. Confirm new agent dir exists and `models.json` is initially absent (current expected behavior of create path).
3. Ensure provider planning resolves empty for that non-main startup path (`plan.action === "skip"`).
4. Start/spawn session for that non-main agent.

### Expected

- Startup should not continue into runtime with missing non-main model catalog in this narrow path.

### Actual

- Before fix: non-main `models.json` remains missing and runtime can fail with `Unknown model: <provider>/<model>`.

## Evidence

- [x]  Failing test/log before + passing after
- [x]  Trace/log snippets
- [ ]  Screenshot/recording
- [ ]  Perf numbers (if relevant)
- Evidence notes:
- `agents.create` success path does not create `models.json` (by design).
- Scoped test added for `skip` branch bootstrap path.
- Local verification run:
- `pnpm test -- src/agents/models-config.skips-writing-models-json-no-env-token.test.ts -t "inherits models.json from main agent for new secondary agents when plan skips"`
- `pnpm build`
- `pnpm check`

## Human Verification (required)

- Verified scenarios:
- non-main + missing target models + skip branch + existing main models => target created and copied.
- existing per-agent target models remains untouched.
- main agent path does not self-copy.
- Edge cases checked:
- missing main models file => no bootstrap.
- empty main models file => no bootstrap.
- What you did **not** verify:
- full provider/channel matrix e2e.

## Review Conversations

- [ ]  I replied to or resolved every bot review conversation I addressed in this PR.
- [ ]  I left unresolved only the conversations that still need reviewer or maintainer judgment.

## Compatibility / Migration

- Backward compatible? `Yes`
- Config/env changes? `No`
- Migration needed? `No`
- If yes, exact upgrade steps: N/A

## Risks and Mitigations

- Risk: accidentally overwriting per-agent custom `models.json`.
- Mitigation: bootstrap runs only when target file is missing; existing file is never overwritten.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Bug]: Non-main agent may miss models.json and fail with "Unknown model" when provider plan is empty

2 participants

@BingqingLyu @xiangri678