Skip to content

refactor(onboard): extract web search verification probe#3305

Merged
cv merged 83 commits into
mainfrom
refactor/onboard-web-search-verify
May 13, 2026
Merged

refactor(onboard): extract web search verification probe#3305
cv merged 83 commits into
mainfrom
refactor/onboard-web-search-verify

Conversation

@cv

@cv cv commented May 9, 2026

Copy link
Copy Markdown
Collaborator

Summary

Extract the post-create web-search verification probe out of the large onboarding module. This keeps web-search setup and verification in focused helper modules while leaving onboarding flow orchestration unchanged.

Changes

  • Add src/lib/onboard/web-search-verify.ts for best-effort Hermes/OpenClaw web-search runtime verification.
  • Update src/lib/onboard.ts to delegate web-search verification through the extracted helper.
  • Add unit tests covering active Hermes/OpenClaw detection, disabled/malformed OpenClaw config warnings, unsupported-agent warnings, and probe-error handling.
  • Update the source-shape regression to include the extracted verification module.

Type of Change

  • Code change (feature, bug fix, or refactor)
  • Code change with doc updates
  • Doc only (prose changes, no code sample modifications)
  • Doc only (includes code sample changes)

Verification

  • npx prek run --all-files passes
  • npm test passes
  • Tests added or updated for new or changed behavior
  • No secrets, API keys, or credentials committed
  • Docs updated for user-facing behavior changes
  • make docs builds without warnings (doc changes only)
  • Doc pages follow the style guide (doc changes only)
  • New doc pages include SPDX header and frontmatter (new pages only)

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

  • New Features

    • Runtime verification that web search is actually enabled inside sandboxes; logs success or emits non-fatal warnings when verification cannot be completed.
  • Tests

    • Expanded automated tests covering multiple agent/config scenarios, parsing edge cases, and probe failures to ensure robust verification behavior.

Review Change Stack

@cv cv self-assigned this May 9, 2026
@coderabbitai

coderabbitai Bot commented May 9, 2026

Copy link
Copy Markdown
Contributor

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Extracts web-search verification into a dependency-injected helper with agent-specific probes (Hermes/OpenClaw), adds unit tests covering success and failure cases, and refactors onboard.ts to delegate verification to the new helper; tests updated to include the new module in probe-command assertions.

Changes

Web Search Verification Modularization

Layer / File(s) Summary
Web Search Verification Module
src/lib/onboard/web-search-verify.ts, src/lib/onboard/web-search-verify.test.ts
Adds WebSearchVerifyAgent and WebSearchVerifyDeps; implements verifyWebSearchInsideSandbox with Hermes (hermes dump output regex) and OpenClaw (read/parse openclaw.json) probes; emits non-fatal warnings on failures and logs successes; unit tests cover agent variants, parse errors, disabled config, unknown agents, and probe exceptions.
Onboard Integration
src/lib/onboard.ts, test/onboard.test.ts
Replaces the prior in-file verification with a thin delegation wrapper that calls the DI helper, injecting runCaptureOpenshell and cliName; updates the probe test to concatenate the new module source when validating sandbox exec command patterns.

Sequence Diagram(s)

sequenceDiagram
  participant Onboard
  participant Verify as verifyWebSearchInsideSandbox
  participant Runner as runCaptureOpenshell
  participant FS as filesystem
  participant Logger
  Onboard->>Verify: verifyWebSearchInsideSandbox(sandboxName, agent, deps)
  Verify->>Runner: run "hermes dump" (when agent=hermes)
  Verify->>FS: read /sandbox/.openclaw/openclaw.json (when agent=openclaw)
  Runner-->>Verify: command output or error
  FS-->>Verify: file contents or read/parse error
  Verify->>Logger: log success or warn on failure
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

  • ericksoa
  • jyaunches
  • prekshivyas

Poem

🐰✨ I hopped through code with nimble feet,
Separated probes so checks are neat.
Hermes speaks, OpenClaw reads its file,
Tests all dance and logs compile.
A tiny rabbit cheers—modular and sweet!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main refactoring: extracting web search verification probe from the onboarding module into a dedicated helper, which aligns with all the core changes described in the changeset.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch refactor/onboard-web-search-verify

Comment @coderabbitai help to get the list of available commands and usage tips.

@cv cv marked this pull request as draft May 9, 2026 03:24
@copy-pr-bot

copy-pr-bot Bot commented May 9, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@copy-pr-bot

copy-pr-bot Bot commented May 9, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@cv cv removed the v0.0.39 label May 12, 2026

@cjagwani cjagwani 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.

lgtm. clean 1:1 extraction — diffed the new module against the deleted block and it's identical modulo console.* → log/warn indirection (same regexes, same argv arrays, same 10s timeout, same json path).

single caller at onboard.ts:6101 still matches the 2-arg wrapper, and the wrapper forwards runCaptureOpenshell + cliName so prod logging behavior is preserved by the console.* defaults.

tests are a real upgrade — the original probe had zero direct coverage and we now hit all 5 branches (active hermes, missing backend, active openclaw, malformed+disabled openclaw, unknown agent + throwing probe). source-shape regression keeps the "sandbox","exec","-n",...,"hermes"|"cat" invariant by concatenating both files, nice touch.

no SSRF surface here — argv is hardcoded, sandboxName flows positionally, catch blocks emit static strings so no creds leak via error.message.

coderabbit skipped on draft, no human comments to reconcile. ready to mark ready-for-review whenever #3304 lands.

@cv cv changed the title refactor(onboard): extract web search verification probe refactor(onboard): extract web search config and verification helpers May 13, 2026
@cv cv changed the base branch from refactor/onboard-web-search-config to main May 13, 2026 03:05
@cv cv marked this pull request as ready for review May 13, 2026 03:06
Comment thread src/lib/onboard.ts Fixed

@coderabbitai coderabbitai 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.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/onboard/web-search-config.ts`:
- Around line 167-171: The non-interactive branch currently only reads
env[BRAVE_API_KEY_ENV] via deps.normalizeCredentialValue, causing web search to
be disabled even if a saved credential exists; modify the branch in the
isNonInteractive() block to first attempt to retrieve a stored credential using
deps.getCredential(BRAVE_API_KEY_ENV) (falling back to env[BRAVE_API_KEY_ENV] if
getCredential returns nothing), then normalize that value with
deps.normalizeCredentialValue and proceed as before—this mirrors the behavior of
ensureValidatedBraveSearchCredential(...) so saved keys are honored in
non-interactive mode.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: b9839ac6-2e30-4021-b29c-f09d32dab7c9

📥 Commits

Reviewing files that changed from the base of the PR and between 17325de and 1404c87.

📒 Files selected for processing (6)
  • src/lib/onboard.ts
  • src/lib/onboard/web-search-config.test.ts
  • src/lib/onboard/web-search-config.ts
  • src/lib/onboard/web-search-verify.test.ts
  • src/lib/onboard/web-search-verify.ts
  • test/onboard.test.ts

Comment thread src/lib/onboard/web-search-config.ts Outdated
Comment on lines +167 to +171
if (deps.isNonInteractive()) {
const braveApiKey = deps.normalizeCredentialValue(env[BRAVE_API_KEY_ENV]);
if (!braveApiKey) {
return null;
}

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.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Use saved credential fallback in non-interactive mode before disabling web search.

This branch only reads env[BRAVE_API_KEY_ENV]. If a key was previously stored via saveCredential, non-interactive onboarding still returns null and disables web search unexpectedly. Reuse getCredential(...) here, consistent with ensureValidatedBraveSearchCredential(...).

Suggested patch
-      const braveApiKey = deps.normalizeCredentialValue(env[BRAVE_API_KEY_ENV]);
+      const braveApiKey = deps.normalizeCredentialValue(
+        deps.getCredential(BRAVE_API_KEY_ENV) ?? env[BRAVE_API_KEY_ENV],
+      );
       if (!braveApiKey) {
         return null;
       }
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/onboard/web-search-config.ts` around lines 167 - 171, The
non-interactive branch currently only reads env[BRAVE_API_KEY_ENV] via
deps.normalizeCredentialValue, causing web search to be disabled even if a saved
credential exists; modify the branch in the isNonInteractive() block to first
attempt to retrieve a stored credential using
deps.getCredential(BRAVE_API_KEY_ENV) (falling back to env[BRAVE_API_KEY_ENV] if
getCredential returns nothing), then normalize that value with
deps.normalizeCredentialValue and proceed as before—this mirrors the behavior of
ensureValidatedBraveSearchCredential(...) so saved keys are honored in
non-interactive mode.

@cjagwani cjagwani 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-reviewed at head 1404c87 after my earlier approval at 14494ce.

the 47 new commits break down as: 45 already-merged-on-main PRs (zero review burden) plus the merge of the parent-stack #3304 branch into this one. against main the actual PR diff is 6 files / +496/-230 — verify.ts and verify.test.ts are byte-identical to what i approved, and the config.ts/config.test.ts content is the same #3304 work that github says "merged" but whose merge commit (8bb073b) is not actually on main HEAD (17325de). so practically, #3305 is the only path to ship #3304 to main right now.

coderabbit flagged a missing getCredential() fallback in the non-interactive branch at config.ts:167 — i diffed it against main onboard.ts:2505 and that branch already only reads process.env on main. not a regression, pre-existing behavior preserved by the extraction. fine to handle in a follow-up if we want it.

ci is clean (19 success, 2 in-progress on wsl-e2e + advisor). re-approving.

cv and others added 2 commits May 12, 2026 20:15
…ort, function or class'

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
@cv cv changed the title refactor(onboard): extract web search config and verification helpers refactor(onboard): extract web search verification probe May 13, 2026

@cjagwani cjagwani 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-reviewed the two new commits on top of 1404c87:

  • 5aabaff extracts a sibling gateway module and removes the old web-search-config; touches onboard.ts plumbing but leaves web-search-verify.{ts,test.ts} byte-identical to what i approved, and the wrapper + guarded call site are unchanged.
  • 2a30b20 is a clean main rebase pulling in destroy/shields/timer work; zero web-search-verify churn.

probe semantics, DI shape, and call site all preserved. re-approving at 9273b30.

@github-actions

Copy link
Copy Markdown
Contributor

E2E Advisor Recommendation

Required E2E: None
Optional E2E: brave-search-e2e, cloud-onboard-e2e, onboard-resume-e2e

Dispatch hint: brave-search-e2e,cloud-onboard-e2e,onboard-resume-e2e

Workflow run

Full advisor summary

Pi Semantic E2E Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

  • None. Pure refactor: verifyWebSearchInsideSandbox is moved verbatim from src/lib/onboard.ts to src/lib/onboard/web-search-verify.ts with dependency injection; onboard.ts retains a thin wrapper that calls the new module with the same arguments. The function is a best-effort warning probe that never aborts onboarding, has no security/network/credentials impact, and is now fully covered by a new vitest unit suite plus an updated assertion in test/onboard.test.ts that reads both files. No behavior change, no new call sites, no API surface change — required E2E coverage is not warranted; brave-search-e2e remains the most relevant optional confidence check.

Optional E2E

  • brave-search-e2e (medium): This is the only E2E that exercises the web search onboarding path end-to-end with a real BRAVE_API_KEY (B2b checks openclaw web-search config selection, B4a/B4b confirm functional search). It is the closest behavioral coverage of verifyWebSearchInsideSandbox, though the probe itself only emits warnings and never aborts onboarding.
  • cloud-onboard-e2e (medium): Refactor touches the onboard.ts entrypoint and changes how a sandbox-exec probe is invoked. Running the non-interactive cloud onboard path provides a smoke check that the post-creation flow (which calls verifyWebSearchInsideSandbox) still executes without crashing when web search is not configured.
  • onboard-resume-e2e (low): Light confidence check that splitting a helper out of onboard.ts did not perturb resume bookkeeping; cheap given the onboard entrypoint was edited.

New E2E recommendations

  • None.

Dispatch hint

  • Workflow: nightly-e2e.yaml
  • jobs input: brave-search-e2e,cloud-onboard-e2e,onboard-resume-e2e

@cjagwani cjagwani self-assigned this May 13, 2026
@cv cv merged commit 6ec0dbe into main May 13, 2026
59 checks passed
@cv cv deleted the refactor/onboard-web-search-verify branch May 27, 2026 21:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

refactor PR restructures code without intended behavior change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants