fix(agents): inherit default agent model catalog for secondary agents

Summary

Secondary (non-default) agents created with openclaw agents add fail at runtime
with FailoverError: Unknown model: google/gemini-2.5-flash when using a
Google/Gemini model authenticated via GEMINI_API_KEY. The default/main agent
works with the same model and key.

Root cause: model discovery only runs for the default agent at gateway
startup, so generated plugin model catalogs (plugins/<provider>/catalog.json)
are only populated under the default agent dir. A secondary agent gets an
apiKey-only google catalog with no models. ModelRegistry.loadCustomModels()
loads plugin catalogs only from the current agent dir, with no read-through to
the default agent — unlike auth profiles, which already inherit via
inheritedAuthDir.

The fix

Add read-through inheritance for generated plugin model catalogs, mirroring the
existing auth-profile read-through (inheritedAuthDir). Implementation is
local-first with a per-provider gap-fill gate:

• ModelRegistry accepts an optional inheritedAgentDir. The agent's OWN
  catalogs (root models.json + local plugin catalogs) load first and establish
  its full local state (models + provider request config + per-model headers).
• Inheritance is gated per provider: a provider the local agent already has
  any model for is excluded from the inherited load entirely — it contributes no
  provider request config, no per-model headers, and no models. So "local always
  wins" never depends on write order, and the inherited catalog can neither read
  nor overwrite the local agent's request config/headers (closes the
  cross-agent boundary concern). Provider request config (baseUrl/api/auth/
  headers) is per-provider with a single slot, so this also avoids pairing an
  inherited model with a local provider's credential.
• Only providers the secondary agent does not configure at all are inherited
  (config + headers + models) — exactly the agent living on inheritance. apiKey
  values in catalogs are env refs (e.g. GEMINI_API_KEY) resolved per-agent, so
  no secret material crosses the agent boundary.
• A broken/invalid inherited catalog is skipped, never breaking the local agent.
• discoverModels threads inheritedAgentDir through to the registry.
• discoverCachedAgentStores passes the resolved default agent dir, and the
  inherited catalog files are folded into the discovery-cache fingerprint so
  changes to the default agent's catalog invalidate the secondary agent's cached
  snapshot.

The default agent never inherits from itself (path-equality guard), so its
behavior is unchanged.

A heavier alternative — running model discovery for every agent at startup — is
the deeper root-cause fix but is costly (per-agent network discovery, needs to
be lazy) and much larger in scope; noting it as a possible follow-up.

Files

• src/agents/sessions/model-registry.ts — inheritedAgentDir option + read-through merge
• src/agents/agent-model-discovery.ts — thread option through discoverModels
• src/agents/embedded-agent-runner/model-discovery-cache.ts — pass default dir + fingerprint
• src/agents/sessions/model-registry.test.ts — 6 new tests

Real behavior proof (required for external PRs)

• Behavior or issue addressed: A secondary agent created with openclaw agents add
  could not use google/gemini-2.5-flash (authed via GEMINI_API_KEY) and failed
  every turn with Unknown model: google/gemini-2.5-flash, while the default
  main agent worked with the same model and key.
• Real environment tested: Local OpenClaw 2026.6.2 install on macOS (launchd
  gateway), Google Gemini via GEMINI_API_KEY, default model
  google/gemini-2.5-flash, with a real main agent plus a secondary agent
  (english-tutor).
• Exact steps or command run after this patch: Applied the patch to my install,
  ran pnpm build, restarted the gateway, emptied the secondary agent's google
  plugin catalog to the apiKey-only state (the state agents add leaves behind),
  then ran a turn through the running gateway — the same lane a Telegram DM uses:
  openclaw agent --agent english-tutor -m "Hi Lexi, correct this: I has two cats yesterday." --json
• Evidence after fix (copied live output from the running gateway):

  $ cat ~/.openclaw/agents/english-tutor/agent/plugins/google/catalog.json
  {"generatedBy":"openclaw-plugin-model-catalog-v1","providers":{"google":{"apiKey":"GEMINI_API_KEY"}}}   # no models
  
  $ openclaw agent --agent english-tutor -m "Hi Lexi, correct this: I has two cats yesterday." --json
  "status": "ok"
  "text": "...Câu đúng phải là: \"I **had** two cats yesterday.\" ... (real model reply)"
  

  And the patched discovery path exercised directly against the real on-disk agent
  dirs (discoverModels):

  secondary agent dir : ~/.openclaw/agents/english-tutor/agent   (catalog: apiKey-only, no models)
  BEFORE (no inheritance): Unknown model (undefined)
  AFTER  (inherit main)  : google/gemini-2.5-flash  api=google-generative-ai  baseUrl=https://generativelanguage.googleapis.com/v1beta
  

• Observed result after fix: The secondary agent resolved
  google/gemini-2.5-flash via read-through inheritance, through the native
  google-generative-ai transport, and produced a real model reply — with no
  manual catalog seeding. Before the patch the identical gateway turn returned
  Unknown model: google/gemini-2.5-flash. Re-verified end-to-end on the final
  build with the per-provider gating: a secondary agent that configures no
  provider of its own inherits the default agent's google catalog and resolves
  the model (a provider the secondary configures itself would instead be
  local-owned and not inherited).
• What was not tested: A second independent reproduction on a non-macOS host.
  Full pnpm test was run; 4 shards each reported 1 failing test, all unrelated
  to this change (macOS /private/var path-normalization / packaged-worker /
  fixture assertions; none of those files reference the changed modules).
• Proof limitations or environment constraints: Verified on a single macOS
  workstation. The live gateway turn was invoked via the CLI agent command
  (which routes through the running gateway on the same agent lane as a Telegram
  DM) rather than by sending an actual Telegram message.
• Before evidence (optional): openclaw agent --agent <secondary> -m "..." →
  GatewayClientRequestError: FailoverError: Unknown model: google/gemini-2.5-flash
  (default main agent returned "status": "ok" for the same model).

Tests and validation

Supplemental (not a substitute for the real behavior proof above):

pnpm build        # exit 0
pnpm tsgo:all     # full prod + test typecheck, all projects — exit 0, 0 errors
npx oxlint <4 touched files>   # no warnings
npx vitest run src/agents/sessions/model-registry.test.ts src/agents/agent-model-discovery*.test.ts   # all pass

New tests cover: (1) a secondary agent inherits the default agent's catalog
models; (2) no inheritance without inheritedAgentDir; (3) the secondary agent's
own catalog wins over inherited models; (4)+(5) an inherited catalog never
overwrites a local provider's request config/headers and never leaks sibling
models into a provider the local agent owns — asserted at the request
resolution level (getApiKeyAndHeaders returns the local headers), for both the
root models.json and local plugin catalog paths; (6) an inherited-only
provider resolves with the inherited baseUrl and headers.

CI status (rebased onto current origin/main e5a9c60851)

This branch is rebased onto origin/main HEAD (e5a9c60851). Most of the CI
failures present on the earlier base have since been fixed upstream. Current state:

The single remaining check-test-types failure is pre-existing on main and
unrelated to this PR — it is two type errors in an extension test:

extensions/qa-lab/src/live-transports/whatsapp/cli.runtime.test.ts(48,5): error TS2322
extensions/qa-lab/src/live-transports/whatsapp/cli.runtime.test.ts(72,5): error TS2322

Verified by checking out clean origin/main (e5a9c60851) with none of this PR's
commits and running pnpm tsgo:extensions:test → the identical two errors, exit 2.
This PR changes only src/agents/** and does not touch extensions/qa-lab/**
(git diff --name-only origin/main HEAD lists four files, all under src/agents/),
so it cannot introduce this failure. The change's own surface is green: targeted
vitest for model-registry/agent-model-discovery passes and tsgo reports no
errors in the changed files.

AI assistance

Drafted with Claude Code (Opus); reviewed and validated by me. Session log
available on request.