Fixes #95109

Summary

• Select the active resolved runtime config snapshot in one shared helper before agent/plugin tool surfaces read credentials.
• Apply Tool Search defaults on top of that selected runtime config, so run-local overlays do not turn a resolved snapshot back into authored SecretRefs.
• Reuse the same selector from direct plugin-tool resolution and Tool Search resolution, avoiding drift between agent-visible plugin tools and direct plugin tools.
• Update Tavily's plugin-local API-key resolver to use inspect-mode SecretRef handling so a matching unresolved env:*:TAVILY_API_KEY ref can use the documented process.env.TAVILY_API_KEY fallback.
• Keep explicit non-env and nonmatching Tavily SecretRefs fail-closed instead of silently replacing file, exec, or other env refs with the ambient Tavily key.
• Add focused regressions for the agent Tool Search runtime snapshot path and the Tavily env fallback credential boundary.

Root Cause

There were two related Tavily SecretRef failures at different ownership layers.

1. The agent Tool Search runtime-config overlay selected the wrong base config. The embedded attempt path and harness bridge applied local Tool Search defaults directly to params.config. When params.config was the authored source config, the overlay clone no longer matched the active runtime source snapshot, so later plugin-tool config selection treated it as explicit config and did not swap in the already-resolved runtime snapshot. Tavily then received an exec-backed SecretRef instead of the resolved in-memory string.
2. Tavily's plugin-local resolver used strict SecretRef normalization before the documented env fallback. extensions/tavily/src/config.ts called strict normalization on plugins.entries.tavily.config.webSearch.apiKey; an unresolved env SecretRef threw before process.env.TAVILY_API_KEY could be read.

RCA proof:

• Agent Tool Search before behavior: src/agents/embedded-agent-runner/run/attempt.ts and src/agents/harness/tool-surface-bridge.ts applied Tool Search defaults before runtime snapshot selection.
• Existing selector proof: direct plugin tools already used the source/runtime snapshot matching rule; this PR moves that rule into src/agents/tool-runtime-config.ts and reuses it.
• Tavily before behavior: extensions/tavily/src/config.ts used strict SecretRef normalization ahead of the env fallback, which matches the UnresolvedSecretInputError in Tavily plugin throws UnresolvedSecretInputError before falling back to process.env #95109.
• Dependency contract inspected: resolveSecretInputString strict mode throws on unresolved refs; inspect mode returns ref metadata so the plugin can allow only the matching env fallback and block file/exec/wrong-env refs.

What Problem This Solves

Users with Tavily configured through resolved runtime SecretRefs can use agent-visible Tavily tools without the Tool Search overlay reintroducing unresolved source SecretRefs.

Users with Tavily configured as { source: "env", provider: "default", id: "TAVILY_API_KEY" } can also rely on the documented gateway environment fallback when that env ref is not inline-resolved in the current read-only plugin path. Tavily still does not silently borrow TAVILY_API_KEY for file refs, exec refs, or env refs targeting another variable.

Why This Change Was Made

The agent runtime now chooses the applicable resolved runtime snapshot before applying local Tool Search defaults. That keeps run-local config overlays in memory, preserves the authored SecretRef in source config, and avoids storing plaintext credentials.

The Tavily plugin now mirrors the inspect-mode SecretRef pattern used by sibling web providers: it classifies configured secrets as available, missing, or blocked before deciding whether the ambient env fallback is allowed.

User Impact

Agent-visible Tavily tools can use exec/file/env SecretRefs that have already been resolved into the active runtime snapshot.

Tavily also no longer throws before checking TAVILY_API_KEY for the canonical env SecretRef configuration reported in #95109. Explicit non-env Tavily SecretRefs remain fail-closed if unavailable.

Real behavior proof

Behavior fixed: Tool Search runtime config now carries resolved in-memory Tavily API key values to agent/plugin tools while the source config keeps the authored SecretRef; Tavily's plugin-local resolver now allows the matching env SecretRef fallback without weakening file/exec/wrong-env credential boundaries.

Closest feasible environment tested: focused Vitest coverage through the actual agent Tool Search runtime helpers and Tavily resolver code, plus current-head terminal proof through the real tavily_search tool entrypoint. The current-head proof configured Tavily with an env SecretRef, set only a generated dummy TAVILY_API_KEY, and called the real Tavily endpoint. Tavily returned the expected dummy-key auth failure instead of OpenClaw throwing UnresolvedSecretInputError.

Current-head Tavily env SecretRef proof:

node --import tsx --input-type=module <<'SCRIPT'
# script imported createTavilySearchTool and resolveTavilyApiKey from this checkout
# cfg.plugins.entries.tavily.config.webSearch.apiKey = { source: "env", provider: "default", id: "TAVILY_API_KEY" }
# process.env.TAVILY_API_KEY = generated dummy value only
SCRIPT

PR #97827 current-head Tavily env SecretRef proof
commit: 1b921e49532747c9031dc98096179f90fc3fb6b9
configured apiKey: env:default:TAVILY_API_KEY
endpoint: https://api.tavily.com/search
env key: generated dummy value only (redacted)
resolveTavilyApiKey returned env dummy: true
Tavily endpoint reached with dummy key: true
UnresolvedSecretInputError observed: no
observed error: Tavily Search API error (401): {"detail":{"error":"Unauthorized: missing or invalid API key."}}

Focused regression output:

node scripts/run-vitest.mjs extensions/tavily/src/config.test.ts src/agents/harness/tool-surface-bridge.test.ts src/agents/openclaw-tools.browser-plugin.integration.test.ts

[test] starting test/vitest/vitest.agents.config.ts
Test Files  2 passed (2)
Tests  10 passed (10)

[test] starting test/vitest/vitest.extension-misc.config.ts
Test Files  1 passed (1)
Tests  8 passed (8)

[test] passed 2 Vitest shards in 8.75s

Observed after behavior:

• Agent Tool Search config keeps Tavily's resolved runtime string while the source config remains an authored SecretRef.
• Tavily resolves a matching unresolved env:*:TAVILY_API_KEY SecretRef from process.env.TAVILY_API_KEY instead of throwing first.
• The tavily_search tool path reaches Tavily with the resolved dummy env key and receives a Tavily auth error, proving provider execution was reached.
• Tavily does not fall back to the ambient env key for file SecretRefs, exec SecretRefs, env refs with another id, or env providers whose allowlist blocks TAVILY_API_KEY.
• No plaintext real credential is written to config, committed, or printed.

Evidence

Current-head real behavior proof:

node --import tsx --input-type=module <<'SCRIPT'
# redacted inline proof script; see Real behavior proof output above
SCRIPT
# commit: 1b921e49532747c9031dc98096179f90fc3fb6b9
# resolveTavilyApiKey returned env dummy: true
# Tavily endpoint reached with dummy key: true
# UnresolvedSecretInputError observed: no
# observed error: Tavily Search API error (401): {"detail":{"error":"Unauthorized: missing or invalid API key."}}

Focused tests:

node scripts/run-vitest.mjs extensions/tavily/src/config.test.ts src/agents/harness/tool-surface-bridge.test.ts src/agents/openclaw-tools.browser-plugin.integration.test.ts
# Test Files  3 passed (3); Tests 18 passed (18)

Formatting, lint, whitespace:

pnpm exec oxfmt --check --threads=1 extensions/tavily/src/config.ts extensions/tavily/src/config.test.ts src/agents/tool-runtime-config.ts src/agents/tool-search-runtime-config.ts src/agents/harness/tool-surface-bridge.ts src/agents/harness/tool-surface-bridge.test.ts src/agents/embedded-agent-runner/run/attempt.ts src/agents/openclaw-plugin-tools.ts
# All matched files use the correct format.

node scripts/run-oxlint.mjs extensions/tavily/src/config.ts extensions/tavily/src/config.test.ts src/agents/tool-runtime-config.ts src/agents/tool-search-runtime-config.ts src/agents/harness/tool-surface-bridge.ts src/agents/harness/tool-surface-bridge.test.ts src/agents/embedded-agent-runner/run/attempt.ts src/agents/openclaw-plugin-tools.ts
# passed with no diagnostics

git diff --check
# passed

Autoreview:

.agents/skills/autoreview/scripts/autoreview --mode local
# autoreview clean: no accepted/actionable findings reported
# overall: patch is correct (0.86)

Requested update command:

oc-update
# pushed commit 1b921e49532 first, then oc-update completed; health check passed on attempt 2/3

GitHub CI:

All required GitHub checks for commit 1b921e49532747c9031dc98096179f90fc3fb6b9 were green when this proof update was added.

Verification

• Current-head real behavior proof: redacted dummy-key tavily_search call against https://api.tavily.com/search reached Tavily and returned 401 instead of UnresolvedSecretInputError.
• Focused regression: node scripts/run-vitest.mjs extensions/tavily/src/config.test.ts src/agents/harness/tool-surface-bridge.test.ts src/agents/openclaw-tools.browser-plugin.integration.test.ts
• Formatting: pnpm exec oxfmt --check --threads=1 ...
• Lint: node scripts/run-oxlint.mjs ...
• Whitespace: git diff --check
• Autoreview: .agents/skills/autoreview/scripts/autoreview --mode local
• Requested update command: oc-update
• GitHub CI: required checks green for 1b921e49532747c9031dc98096179f90fc3fb6b9

What was not tested

• Live Tavily search with a real Tavily credential, to avoid exposing or storing a real API key. The current-head proof intentionally used a generated dummy key and treated Tavily's 401 response as proof that the provider endpoint was reached.
• A successful Tavily result payload with a real account quota.
• Unrelated local oc-update doctor/security warnings, including local skill/tooling/security-audit findings, were not repaired by this PR.

AI Assistance

AI-assisted with Codex. I understand the change: it keeps the active resolved runtime snapshot as the base config for agent Tool Search overlays and direct plugin tools, and it repairs Tavily's plugin-local env SecretRef fallback without allowing unrelated configured credential refs to be silently replaced by ambient env state.