RAG refactor (v7) breaks configs without explicit version field — migration unreachable

[aheritier]

Summary

PR #2210 ("Refactor RAG from agent-level config to standard toolset type") moved rag from an agent-level field to a standard toolset entry (type: rag with ref). A v6→v7 migration was added in pkg/config/latest/parse.go to automatically convert the old syntax, but it is unreachable for configs that don't set an explicit version field.

Root Cause

In pkg/config/config.go line 32:

raw.Version = cmp.Or(raw.Version, latest.Version)

When no version is specified, the config defaults to the latest version ("7"). This means the YAML is parsed directly by the v7 strict parser, which rejects the old rag field on AgentConfig with:

[13:1] unknown field "rag"

The v6→v7 upgrader in parse.go only triggers when the config is parsed as a previous.Config (v6), which requires version: "6" to be explicitly set — something most users never do.

Impact

Any user who had a working config with agent-level rag: [...] (the documented syntax before v1.37.0) and upgrades docker-agent will get a cryptic unknown field "rag" error. The migration path exists but is silently bypassed.

This affects configs that reference the schema URL ($schema=https://raw.githubusercontent.com/docker/docker-agent/main/agent-schema.json) since the schema was updated to remove rag from agent properties, and users following it would never have set a version field.

Suggested Improvements

Two complementary improvements could reduce friction:

1. Better error message: When parsing fails on an agent with an unknown rag field, detect this specific case and suggest the fix:

   agent 'root': unknown field "rag" — the agent-level rag field was replaced 
   by toolset entries in config v7. Replace rag: [name] with toolset entries:
     - type: rag
       ref: name
   Or add version: "6" to your config for automatic migration.
   

2. Auto-migration for unversioned configs: When no version is set and strict v7 parsing fails, attempt a v6 parse + migration before returning the error. This would make the migration actually work for the majority of users.

Workarounds

Users can fix their configs by either:

• Adding version: "6" to trigger the automatic migration
• Manually replacing rag: [name1, name2] on each agent with toolset entries:

  toolsets:
    # ... existing toolsets ...
    - type: rag
      ref: name1
    - type: rag
      ref: name2

Reproduction

1. Create a config file without a version field that uses the old agent-level rag syntax:

   rag:
     my-docs:
       docs: [README.md]
       strategies:
         - type: bm25
           database: data/bm25.db
   
   agents:
     root:
       model: balanced
       instruction: "Hello"
       rag: [my-docs]
       toolsets:
         - type: shell

2. Run docker-agent → unknown field "rag" error

References

• PR Refactor RAG from agent-level config to standard toolset type #2210: Refactor RAG from agent-level config to standard toolset type
• Commit cab21861: The refactor commit
• pkg/config/config.go:32: Default version assignment
• pkg/config/latest/parse.go: v6→v7 migration code

[dgageot]

Unfortunately, that's a bit by design. Unversionned config files use "latest" and "latest" is not stable.

[aheritier]

@dgageot There's a related regression in the same RAG refactor (PR #2210).

createRAGTool doesn't pass the Models map to ManagersBuildConfig

In pkg/teamloader/registry.go, createRAGTool builds the rag.ManagersBuildConfig without populating the Models field:

mgr, err := rag.NewManager(ctx, ragName, toolset.RAGConfig, rag.ManagersBuildConfig{
    ParentDir:     parentDir,
    ModelsGateway: runConfig.ModelsGateway,
    Env:           runConfig.EnvProvider(),
    // Models is not set — remains nil
})

This means any RAG config that uses a model alias for reranking (e.g. model: balanced referencing a named model from the top-level models: section) fails at runtime with:

toolset rag failed: failed to create RAG manager: failed to build manager
config for RAG "rag": failed to build reranking config: failed to resolve
reranking model "balanced": model "balanced" not found in configuration

The resolveModelConfig() function in pkg/rag/builder.go checks buildCfg.Models[modelName], but that map is always empty since createRAGTool never passes it.

Workaround

Use an inline provider/model reference instead of a model alias in the RAG reranking config:

# Before (broken — alias not resolved)
results:
  reranking:
    model: balanced

# After (works — inline reference bypasses alias lookup)
results:
  reranking:
    model: anthropic/claude-sonnet-4-6

Fix

createRAGTool in registry.go needs access to cfg.Models to pass it through. The ToolsetCreator function signature doesn't currently provide the config's models map, so this likely needs either:

• Adding Models to RuntimeConfig, or
• Extending the ToolsetCreator signature to include the parsed config, or
• Passing cfg.Models through some other mechanism available at toolset creation time.

[aheritier]

Additional issue: emitToolsChanged 5-second timeout races with RAG initialization

Problem

When the TUI starts, RAG toolsets and MCP toolsets initialize concurrently. If an MCP server connects and fires OnToolsChanged before the RAG strategies finish their file collection/indexing, emitToolsChanged() in runtime.go creates a 5-second timeout context:

func (r *LocalRuntime) emitToolsChanged() {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    agentTools, err := r.CurrentAgentTools(ctx)
    // ...
}

This calls CurrentAgentTools(ctx) → agent.Tools(ctx) → ensureToolSetsAreStarted(ctx) → startable.Start(ctx).

If the RAG toolset hasn't started yet, Start(ctx) triggers Initialize() which runs fsx.CollectFiles(ctx, ...). For projects with many files (e.g., ~2000 source files), file collection takes longer than 5 seconds → context deadline exceeded.

The error surfaces as:

*builtin.RAGTool start failed: failed to initialize RAG manager "rag":
one or more strategies failed to initialize: failed to collect files:
context deadline exceeded

Since StartableToolSet.Start() leaves started = false on failure, the toolset is retried on the next call. But the warning is already recorded via addToolWarning() and displayed in the TUI sidebar.

Reproduction

Any config with both MCP and RAG toolsets on the same agent, where the RAG indexes a non-trivial number of files. The faster the MCP server connects, the more likely the race.

Suggested fix

emitToolsChanged should not attempt to start toolsets that haven't been started yet. It should only list tools from already-started toolsets. Something like:

func (r *LocalRuntime) emitToolsChanged() {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    // Only list tools from already-started toolsets, don't trigger Start()
    agentTools, err := r.CurrentAgentStartedTools(ctx)
    // ...
}

Or alternatively, ensureToolSetsAreStarted could skip toolsets that are currently being started by another goroutine rather than blocking on the mutex and then retrying with a tight deadline.