Skip to content

fix(agents): compact lean local tool catalogs#88822

Merged
vincentkoc merged 1 commit into
mainfrom
local-model-lean-tool-search-20260601
Jun 8, 2026
Merged

fix(agents): compact lean local tool catalogs#88822
vincentkoc merged 1 commit into
mainfrom
local-model-lean-tool-search-20260601

Conversation

@vincentkoc

@vincentkoc vincentkoc commented May 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

  • default localModelLean runs to structured Tool Search controls when the operator has not configured tools.toolSearch
  • keep explicit Tool Search config authoritative, including tools.toolSearch: false
  • preserve direct message delivery semantics for message_tool_only / forced-message runs instead of hiding that tool behind Tool Search
  • document that lean mode hides larger plugin/MCP/client catalogs behind tool_search, tool_describe, and tool_call except for direct message delivery runs

Refs #86599

Verification

  • Refreshed and force-pushed head 6153fb5ecb47e01a546af38c8c4b1b7286a77337 after rebasing onto origin/main 5c5391836b1eaca048f7ae9ef0b72333b90169ef.
  • node scripts/docs-list.js passed.
  • node scripts/check-docs-mdx.mjs docs/concepts/experimental-features.md docs/gateway/local-models.md docs/providers/ollama.md passed.
  • node scripts/format-docs.mjs --check docs/concepts/experimental-features.md docs/gateway/local-models.md docs/providers/ollama.md passed.
  • node_modules/.bin/oxfmt --check --threads=1 docs/concepts/experimental-features.md docs/gateway/local-models.md docs/providers/ollama.md src/agents/local-model-lean.ts src/agents/local-model-lean.test.ts src/agents/embedded-agent-runner/run/attempt.ts src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts passed after formatting the rebased attempt.ts import ordering.
  • node scripts/run-oxlint.mjs src/agents/local-model-lean.ts src/agents/local-model-lean.test.ts src/agents/embedded-agent-runner/run/attempt.ts src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts passed.
  • git diff --check origin/main...HEAD passed.
  • TMPDIR=$PWD/.tmp/vitest-88822 OPENCLAW_VITEST_MAX_WORKERS=1 node scripts/run-vitest.mjs src/agents/local-model-lean.test.ts --reporter=dot passed, 1 file / 11 tests.
  • TMPDIR=$PWD/.tmp/vitest-88822 OPENCLAW_VITEST_MAX_WORKERS=1 node scripts/run-vitest.mjs src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts --reporter=dot --testNamePattern 'defaults local-model lean embedded runs|keeps Tool Search controls off for lean message-tool-only delivery' passed, 2 files / 4 focused tests run / 116 skipped.
  • .agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main reported autoreview clean: no accepted/actionable findings reported, overall: patch is correct (0.83).
  • Fresh GitHub checks passed on 6153fb5: CI 27111011466, CodeQL/Security High 27111011468, CodeQL Critical Quality 27111011471, OpenGrep PR Diff 27111011476, Real behavior proof 27111014608, Dependency Guard 27111010702, Workflow Sanity 27111011460.

Real behavior proof

Behavior addressed: smaller/local-model runs can keep large extra tool catalogs out of the direct prompt surface without disabling tools entirely, while message-tool-only delivery still keeps the direct message tool visible.

Real environment tested: linked OpenClaw gwt worktree plus fresh GitHub CI on the refreshed PR head.

Exact steps or command run after this patch: focused lean-mode and embedded-attempt Vitest proof, docs list, docs MDX, docs formatting, oxfmt, oxlint, diff-check, local autoreview, and the fresh GitHub CI/check matrix listed above.

Evidence after fix: local focused tests covered the default lean Tool Search path, explicit tools.toolSearch: false, and sourceReplyDeliveryMode: "message_tool_only" preserving the direct message tool. GitHub CI also passed the selected agent-runtime-boundary critical shard, agent embedded/core/runtime shards, docs checks, type checks, lint, guards, security high scans, OpenGrep changed-path scan, and real-behavior-proof workflow.

Observed result after fix: lean-mode embedded runs enable Tool Search controls by default for normal runs, preserve explicit operator config, pass the resolved Tool Search config into core, OpenClaw, MCP, and client catalog construction, and skip the lean default when direct message delivery is forced.

What was not tested: live Ollama model-family validation for the broader local-model issue. AWS Crabbox proof was not rerun from this machine because the AWS broker login is missing here; GitHub CI supplied the remote proof for this refreshed head.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime agents Agent runtime and tooling size: S maintainer Maintainer-authored PR labels May 31, 2026
@vincentkoc vincentkoc self-assigned this May 31, 2026
@clawsweeper

clawsweeper Bot commented May 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: found issues before merge. Reviewed June 1, 2026, 12:21 AM ET / 04:21 UTC.

Summary
The PR makes localModelLean synthesize Tool Search defaults when tools.toolSearch is unset, threads that runtime config through embedded tool/catalog/client construction, adds lean-mode tests, and updates local-model docs.

PR surface: Source +34, Tests +137, Docs +2. Total +173 across 7 files.

Reproducibility: no. high-confidence live reproduction for the broader Windows/Ollama issue is included; the PR body says live Ollama model-family validation was not tested. Source inspection does show the current-main behavior and the PR’s proposed lean-mode default path clearly.

Review metrics: 2 noteworthy metrics.

  • Runtime default surfaces: 1 changed. Unset tools.toolSearch now gets a synthesized Tool Search config for lean runs, which changes upgrade behavior for existing experimental users.
  • Open lean-mode sibling PRs: 2 open. The related open PRs modify the same localModelLean design surface and should not land as conflicting partial defaults.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦞 diamond lobster
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Record the maintainer decision on whether existing localModelLean users should get Tool Search by default or only through opt-in config.
  • Resolve the overlap with the two related lean-mode PRs so one canonical design lands.

Risk before merge

  • [P1] Existing users with localModelLean enabled and no tools.toolSearch setting would upgrade from direct plugin/MCP/client catalog exposure to structured tool_search/tool_describe/tool_call controls by default.
  • [P1] The linked Windows/Ollama responsiveness report is broader than this mitigation, and the PR body explicitly says live Ollama model-family validation was not tested.
  • [P1] Two related open lean-mode PRs touch adjacent behavior, so maintainers need one canonical lean-mode design before landing defaults that affect existing configs.

Maintainer options:

  1. Approve or gate the default (recommended)
    Maintainers should either approve structured Tool Search as the new localModelLean upgrade behavior or change the branch to preserve current direct-catalog behavior unless users opt in.
  2. Accept experimental churn
    Maintainers may intentionally accept the behavior change because localModelLean is experimental, but the PR body should make the upgrade tradeoff explicit.
  3. Pause for one lean-mode branch
    If the adjacent lean-mode PRs are still competing designs, pause this PR and pick one canonical branch before merging defaults.

Next step before merge

  • [P2] Protected maintainer PR changes compatibility-sensitive lean-mode defaults and overlaps active related PRs, so the remaining action is owner/product review rather than a narrow automation repair.

Security
Cleared: The diff uses existing Tool Search plumbing and docs/tests, with no new dependencies, workflows, permissions, package metadata, or secret-handling surfaces.

Review findings

  • [P1] Gate lean Tool Search default behind upgrade approval — src/agents/local-model-lean.ts:102-107
Review details

Best possible solution:

Land one maintainer-approved lean-mode design: either accept this experimental default as the intended upgrade behavior or gate it behind explicit opt-in/default-preserving behavior, then align the related lean-mode PRs around that decision.

Do we have a high-confidence way to reproduce the issue?

No high-confidence live reproduction for the broader Windows/Ollama issue is included; the PR body says live Ollama model-family validation was not tested. Source inspection does show the current-main behavior and the PR’s proposed lean-mode default path clearly.

Is this the best way to solve the issue?

Unclear as a final fix: the implementation uses the existing Tool Search owner boundary and preserves explicit operator config, but making this the default for existing lean users needs a maintainer upgrade decision and coordination with related PRs.

Full review comments:

  • [P1] Gate lean Tool Search default behind upgrade approval — src/agents/local-model-lean.ts:102-107
    Existing users who already set localModelLean: true but left tools.toolSearch unset currently get direct plugin/MCP/client catalog exposure. Synthesizing this Tool Search config silently changes the model-visible tool surface and search limits on upgrade, so this needs an explicit maintainer upgrade decision or a default-preserving opt-in path before merge.
    Confidence: 0.84

Overall correctness: patch is incorrect
Overall confidence: 0.82

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against b2a1c5caa854.

Label changes

Label justifications:

  • P1: The PR targets an urgent local-model agent usability path tied to a P1 Windows/Ollama report and changes runtime behavior for that workflow.
  • merge-risk: 🚨 compatibility: Merging changes the default model-visible tool surface for existing localModelLean configs that did not explicitly configure Tool Search.
  • rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
  • status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The maintainer PR body includes focused after-fix tests plus AWS Crabbox changed-gate proof for the embedded lean-mode path; the remaining gap is live Ollama validation for the broader linked report.
  • proof: sufficient: Contributor real behavior proof is sufficient. The maintainer PR body includes focused after-fix tests plus AWS Crabbox changed-gate proof for the embedded lean-mode path; the remaining gap is live Ollama validation for the broader linked report.
Evidence reviewed

PR surface:

Source +34, Tests +137, Docs +2. Total +173 across 7 files.

View PR surface stats
Area Files Added Removed Net
Source 2 42 8 +34
Tests 2 137 0 +137
Docs 3 7 5 +2
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 7 186 13 +173

What I checked:

  • Root and scoped policy applied: Root, src/agents, src/agents/embedded-agent-runner/run, and docs AGENTS.md files were read; the relevant guidance treats config/default behavior and agent runtime changes as compatibility-sensitive and requires review beyond the diff. (AGENTS.md:13, b2a1c5caa854)
  • Current main lean behavior: Current main only filters browser, cron, and message from lean-mode tools; it does not synthesize Tool Search config in the lean helper. (src/agents/local-model-lean.ts:65, b2a1c5caa854)
  • Current main Tool Search default contract: resolveToolSearchConfig enables Tool Search only when configured fields exist; otherwise enabled resolves false, so unset tools.toolSearch is currently direct-catalog behavior. (src/agents/tool-search.ts:423, b2a1c5caa854)
  • PR default change: The PR head adds applyLocalModelLeanToolSearchDefaults, which returns a copied config with tools.toolSearch enabled in structured tools mode when lean mode is enabled and no operator Tool Search config exists. (src/agents/local-model-lean.ts:91, 1e2991d2ee0f)
  • PR runtime threading: The PR head resolves toolSearchRuntimeConfig before embedded tool construction, uses it to decide Tool Search enablement, and passes it into OpenClaw tool, catalog, and client-tool catalog creation. (src/agents/embedded-agent-runner/run/attempt.ts:1115, 1e2991d2ee0f)
  • Focused PR coverage: The PR adds tests for default lean Tool Search controls, explicit tools.toolSearch: false preservation, and message_tool_only delivery preserving direct message. (src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts:287, 1e2991d2ee0f)

Likely related people:

  • vincentkoc: Prior main history introduced the experimental lean local-model mode and docs, and GitHub commit history shows recent lean-mode work in src/agents/local-model-lean.ts; included here because the author also has merged history on this surface. (role: feature owner and recent area contributor; confidence: high; commits: f09a4d9ba07d, a780151fd1aa, 4d135ae28b; files: src/agents/local-model-lean.ts, docs/concepts/experimental-features.md, docs/gateway/local-models.md)
  • steipete: GitHub commit history for src/agents/tool-search.ts and src/agents/embedded-agent-runner/run/attempt.ts shows recent Tool Search, code-mode, and embedded-runner changes adjacent to this defaulting path. (role: recent adjacent owner; confidence: medium; commits: 4150c6ff82, ec8cb8bcbf, 287687da20; files: src/agents/tool-search.ts, src/agents/embedded-agent-runner/run/attempt.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P1 High-priority user-facing bug, regression, or broken workflow. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. labels May 31, 2026
@vincentkoc
vincentkoc force-pushed the local-model-lean-tool-search-20260601 branch from 991ca72 to 7bd90c6 Compare June 1, 2026 00:48
@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels Jun 1, 2026
@vincentkoc
vincentkoc force-pushed the local-model-lean-tool-search-20260601 branch 3 times, most recently from 4b59386 to 967cc13 Compare June 1, 2026 02:06
@clawsweeper clawsweeper Bot mentioned this pull request Jun 1, 2026
Merged
@vincentkoc
vincentkoc force-pushed the local-model-lean-tool-search-20260601 branch from 967cc13 to 1e2991d Compare June 1, 2026 03:54
@clawsweeper clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 1, 2026
@vincentkoc
vincentkoc marked this pull request as ready for review June 1, 2026 04:14
@vincentkoc
vincentkoc force-pushed the local-model-lean-tool-search-20260601 branch from 1e2991d to 6153fb5 Compare June 8, 2026 01:28
@vincentkoc

vincentkoc commented Jun 8, 2026

Copy link
Copy Markdown
Member Author

Land-ready after refresh on 6153fb5ecb47e01a546af38c8c4b1b7286a77337.

Verification run before merge:

node scripts/docs-list.js
node scripts/check-docs-mdx.mjs docs/concepts/experimental-features.md docs/gateway/local-models.md docs/providers/ollama.md
node scripts/format-docs.mjs --check docs/concepts/experimental-features.md docs/gateway/local-models.md docs/providers/ollama.md
node_modules/.bin/oxfmt --check --threads=1 docs/concepts/experimental-features.md docs/gateway/local-models.md docs/providers/ollama.md src/agents/local-model-lean.ts src/agents/local-model-lean.test.ts src/agents/embedded-agent-runner/run/attempt.ts src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts
node scripts/run-oxlint.mjs src/agents/local-model-lean.ts src/agents/local-model-lean.test.ts src/agents/embedded-agent-runner/run/attempt.ts src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts
git diff --check origin/main...HEAD
TMPDIR=$PWD/.tmp/vitest-88822 OPENCLAW_VITEST_MAX_WORKERS=1 node scripts/run-vitest.mjs src/agents/local-model-lean.test.ts --reporter=dot
TMPDIR=$PWD/.tmp/vitest-88822 OPENCLAW_VITEST_MAX_WORKERS=1 node scripts/run-vitest.mjs src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts --reporter=dot --testNamePattern 'defaults local-model lean embedded runs|keeps Tool Search controls off for lean message-tool-only delivery'
.agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main

Fresh GitHub checks passed on this SHA: CI 27111011466, CodeQL/Security High 27111011468, CodeQL Critical Quality 27111011471, OpenGrep PR Diff 27111011476, Real behavior proof 27111014608, Dependency Guard 27111010702, Workflow Sanity 27111011460.

Known gap: local AWS Crabbox broker auth is missing on this machine, so I did not rerun AWS Crabbox for the refreshed head. The fresh GitHub matrix covered the remote proof before merge.

@vincentkoc
vincentkoc merged commit 8b03fd1 into main Jun 8, 2026
174 of 175 checks passed
@vincentkoc
vincentkoc deleted the local-model-lean-tool-search-20260601 branch June 8, 2026 01:33
@vincentkoc vincentkoc mentioned this pull request Jun 8, 2026
Closed
@Haderach-Ram Haderach-Ram mentioned this pull request Jun 8, 2026
Open
This was referenced Jun 12, 2026
Merged
Closed
Closed
Closed
@clawsweeper clawsweeper Bot mentioned this pull request Jun 21, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@vincentkoc vincentkoc

Labels

agents Agent runtime and tooling docs Improvements or additions to documentation gateway Gateway runtime maintainer Maintainer-authored PR merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. P1 High-priority user-facing bug, regression, or broken workflow. proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. size: M status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@vincentkoc