Skip to content
Source
Sign inSign up
TanStack/ai

fix(ai): keep lazy-tool discovery callable when re-requested after all tools are discovered #795

Mergedseason179(GitHub profile, opens in a new tab)merged 3 commits intomain fromrefs/pull/795/headmerged by AlemTuzlak View on GitHub

Closes #788

Problem

When using lazy tools (progressive disclosure), the synthetic __lazy__tool__discovery__ tool is dropped from the set advertised to the model once every lazy tool has been discovered — a deliberate token optimization.

But if the model re-requests discovery after that point — common in long-context turns, or when it overlooks that a tool is already available — the call no longer matches any advertised tool and falls through to tool execution, coming back as:

Unknown tool: __lazy__tool__discovery__

Fix

Decouple the advertised tool set from the executable one:

  • The advertised set (getActiveTools()) is unchanged — the discovery tool still drops out once all lazy tools are discovered, preserving the token optimization.
  • A new getExecutableTools() keeps the discovery tool executable for a turn whenever a pending call references it, even after it has left the advertised set. Re-discovery now returns the tool schemas again instead of erroring.
  • Discovery is also made idempotent: re-requesting an already-discovered tool returns its schema without triggering a redundant tool-list refresh / continue in the agent loop.

__lazy__tool__discovery__'s name is now exported as DISCOVERY_TOOL_NAME so consumers writing custom message-compaction / history-trimming logic can reference it by constant instead of hard-coding the internal string.

Tests

  • tests/lazy-tool-manager.test.ts — coverage for getExecutableTools (re-discovery robustness: adds the discovery tool back when all are discovered and a call references it; no-op when nothing references it; no duplicate while still advertised; no-op with no lazy tools) and idempotent discovery.
  • tests/chat.test.ts — engine-level regression for #788 (model re-requests discovery after all lazy tools are discovered → no "Unknown tool", run reaches completion) plus a batched discovery-and-real-tool turn.

All 67 tests in the two suites pass; type-check is clean.

Summary by CodeRabbit

Bug Fixes

  • Fixed lazy tool re-discovery so repeated discovery requests for already-discovered tools no longer trigger “Unknown tool” execution errors.
  • Made lazy tool discovery idempotent, avoiding redundant discovery/list refresh behavior on repeated requests.
  • Ensured re-discovered lazy tools remain executable on subsequent turns.

New Features

  • Exported the lazy discovery tool name (DISCOVERY_TOOL_NAME) from @tanstack/ai for custom message compaction/history trimming logic.

Tests

  • Added regression coverage for re-discovery, batching behavior, and idempotency.
    1. Review Change Stack

      No actionable comments were generated in the recent review. 🎉

      ℹ️ Recent review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Pro

      Run ID: fae00190-c79b-4ab4-b1c2-e8d07202fef2

      📥 Commits

      Reviewing files that changed from the base of the PR and between 4f08793d10063a7c5db113f7cbec30f7158cb4a8 and 522ead54c017052532ab502383e9613c2e9766eb.

      📒 Files selected for processing (1)
      • .changeset/lazy-tool-rediscovery.md
      ✅ Files skipped from review due to trivial changes (1)
      • .changeset/lazy-tool-rediscovery.md

      📝 Walkthrough

      Walkthrough

      Fixes lazy tool re-discovery errors when models re-request __lazy__tool__discovery__ after it has been advertised. LazyToolManager adds getExecutableTools() to conditionally re-include the discovery tool when pending calls reference it, and makes re-discovery idempotent to avoid redundant refresh signaling. TextEngine uses a new resolveExecutableTools helper. DISCOVERY_TOOL_NAME is now publicly exported.

      Changes

      Lazy Tool Re-discovery Fix

      Layer / File(s)Summary
      LazyToolManager: export constant, getExecutableTools, idempotency fix
      packages/ai/src/activities/chat/tools/lazy-tool-manager.ts
      Promotes DISCOVERY_TOOL_NAME to an exported constant, adds getExecutableTools() to conditionally re-include the discovery tool in the executable set when pending calls reference it by name, and guards hasNewDiscoveries so repeated discovery of an already-known tool does not trigger a redundant tool-list refresh.
      TextEngine: resolveExecutableTools helper and updated execution paths
      packages/ai/src/activities/chat/index.ts
      Adds a private resolveExecutableTools helper that delegates to LazyToolManager.getExecutableTools, and updates both the pending-tool-calls and current-tool-phase execution paths to pass the resolved tool list instead of this.tools.
      Public export and changeset
      packages/ai/src/index.ts, .changeset/lazy-tool-rediscovery.md
      Re-exports DISCOVERY_TOOL_NAME from the package's public index and documents the patch, the behavioral fixes, and the new export in the changeset file.
      Regression and unit tests
      packages/ai/tests/chat.test.ts, packages/ai/tests/lazy-tool-manager.test.ts
      Adds two integration tests covering re-requested discovery (no unknown-tool error) and batched discovery+tool-call turns; adds unit tests for getExecutableTools edge cases and idempotent re-discovery; imports DISCOVERY_TOOL_NAME from the module instead of defining it locally.

      Estimated code review effort

      🎯 3 (Moderate) | ⏱️ ~25 minutes

      Suggested reviewers

      • tombeckenham

      Poem

      🐇 Hop hop, the lazy tool forgot its name, The model re-asked — what a shame! Now discovery stays, idempotent and bright, DISCOVERY_TOOL_NAME exported just right. No "Unknown tool" shall trouble this stream, The rabbit fixed bugs in a well-crafted scheme! 🌟

      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 0.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 nameStatusExplanation
      Title check✅ PassedThe title accurately summarizes the main change: fixing lazy-tool discovery to remain callable when re-requested after all tools are discovered.
      Description check✅ PassedThe description comprehensively covers the problem, solution, and changes made, with clear sections on problem statement, fix approach, and test coverage.
      Linked Issues check✅ PassedAll requirements from issue #788 are addressed: discovery tool remains callable when re-requested [#788], idempotent re-discovery implemented [#788], and DISCOVERY_TOOL_NAME is exported [#788].
      Out of Scope Changes check✅ PassedAll changes are directly scoped to fixing lazy tool discovery and exporting DISCOVERY_TOOL_NAME; no unrelated modifications were introduced.
      ✏️ Tip: You can configure your own custom pre-merge checks in the settings.
      ✨ Finishing Touches
      🧪 Generate unit tests (beta)
      • Create PR with unit tests

      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    2. Actionable comments posted: 1

      🧹 Nitpick comments (1)
      packages/ai/tests/chat.test.ts (1)

      1786-1804: ⚡ Quick win

      Use DISCOVERY_TOOL_NAME in these new regression tests instead of hard-coded literals.

      This keeps tests aligned with the newly exported public contract and avoids brittle string duplication.

      Suggested fix
      -yield ev.toolStart('c1', '__lazy__tool__discovery__')
      +yield ev.toolStart('c1', DISCOVERY_TOOL_NAME)
      
      -yield ev.toolStart('c2', '__lazy__tool__discovery__')
      +yield ev.toolStart('c2', DISCOVERY_TOOL_NAME)
      
      -expect(toolNamesPerCall[1]).not.toContain('__lazy__tool__discovery__')
      +expect(toolNamesPerCall[1]).not.toContain(DISCOVERY_TOOL_NAME)
      
      -yield ev.toolStart('d1', '__lazy__tool__discovery__')
      +yield ev.toolStart('d1', DISCOVERY_TOOL_NAME)
      
      -yield ev.toolStart('d2', '__lazy__tool__discovery__')
      +yield ev.toolStart('d2', DISCOVERY_TOOL_NAME)

      Also applies to: 1827-1827, 1863-1863, 1873-1873

      🤖 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 `@packages/ai/tests/chat.test.ts` around lines 1786 - 1804, Replace the
      hard-coded string literal '__lazy__tool__discovery__' with the
      DISCOVERY_TOOL_NAME constant in the regression test blocks. Specifically, update
      all occurrences in the toolStart method calls (at callCount === 1 and callCount
      === 2 blocks, and the other locations mentioned) to use DISCOVERY_TOOL_NAME
      instead of the string literal. Ensure the constant is imported or available in
      the test file if not already present.
      🤖 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 `@packages/ai/tests/lazy-tool-manager.test.ts`:
      - Around line 3-6: The import order in the lazy-tool-manager.test.ts file
      violates the import/order lint rule. Reorder the imports from
      '../src/activities/chat/tools/lazy-tool-manager' so that any value imports (like
      DISCOVERY_TOOL_NAME and LazyToolManager) are placed before any type-only
      imports. Ensure regular value imports appear first in the import statement,
      followed by any type-only imports if present.
      
      ---
      
      Nitpick comments:
      In `@packages/ai/tests/chat.test.ts`:
      - Around line 1786-1804: Replace the hard-coded string literal
      '__lazy__tool__discovery__' with the DISCOVERY_TOOL_NAME constant in the
      regression test blocks. Specifically, update all occurrences in the toolStart
      method calls (at callCount === 1 and callCount === 2 blocks, and the other
      locations mentioned) to use DISCOVERY_TOOL_NAME instead of the string literal.
      Ensure the constant is imported or available in the test file if not already
      present.
      🪄 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: defaults

      Review profile: CHILL

      Plan: Pro

      Run ID: abfdf887-d4eb-4cfc-abac-ff7f03f0e082

      📥 Commits

      Reviewing files that changed from the base of the PR and between 2cb0313c1f13e1db37c5550308e36bb0b9b73b98 and b85f67126b9212c0455bd34677d786fbb585bdac.

      📒 Files selected for processing (6)
      • .changeset/lazy-tool-rediscovery.md
      • packages/ai/src/activities/chat/index.ts
      • packages/ai/src/activities/chat/tools/lazy-tool-manager.ts
      • packages/ai/src/index.ts
      • packages/ai/tests/chat.test.ts
      • packages/ai/tests/lazy-tool-manager.test.ts
      Resolvedby coderabbitai[bot](GitHub profile, opens in a new tab)
    3. AlemTuzlak approved these changes

    4. View your CI Pipeline Execution ↗ for commit 522ead54c017052532ab502383e9613c2e9766eb

      CommandStatusDurationResult
      nx run-many --targets=build --exclude=examples/...✅ Succeeded1m 28sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-06-22 13:28:29 UTC

    5. View your CI Pipeline Execution ↗ for commit 522ead54c017052532ab502383e9613c2e9766eb


      ☁️ Nx Cloud last updated this comment at 2026-06-22 11:32:56 UTC

    6. Open in StackBlitz

      @tanstack/ai

      npm i https://pkg.pr.new/@tanstack/ai@795

      @tanstack/ai-angular

      npm i https://pkg.pr.new/@tanstack/ai-angular@795

      @tanstack/ai-anthropic

      npm i https://pkg.pr.new/@tanstack/ai-anthropic@795

      @tanstack/ai-client

      npm i https://pkg.pr.new/@tanstack/ai-client@795

      @tanstack/ai-code-mode

      npm i https://pkg.pr.new/@tanstack/ai-code-mode@795

      @tanstack/ai-code-mode-skills

      npm i https://pkg.pr.new/@tanstack/ai-code-mode-skills@795

      @tanstack/ai-devtools-core

      npm i https://pkg.pr.new/@tanstack/ai-devtools-core@795

      @tanstack/ai-elevenlabs

      npm i https://pkg.pr.new/@tanstack/ai-elevenlabs@795

      @tanstack/ai-event-client

      npm i https://pkg.pr.new/@tanstack/ai-event-client@795

      @tanstack/ai-fal

      npm i https://pkg.pr.new/@tanstack/ai-fal@795

      @tanstack/ai-gemini

      npm i https://pkg.pr.new/@tanstack/ai-gemini@795

      @tanstack/ai-grok

      npm i https://pkg.pr.new/@tanstack/ai-grok@795

      @tanstack/ai-groq

      npm i https://pkg.pr.new/@tanstack/ai-groq@795

      @tanstack/ai-isolate-cloudflare

      npm i https://pkg.pr.new/@tanstack/ai-isolate-cloudflare@795

      @tanstack/ai-isolate-node

      npm i https://pkg.pr.new/@tanstack/ai-isolate-node@795

      @tanstack/ai-isolate-quickjs

      npm i https://pkg.pr.new/@tanstack/ai-isolate-quickjs@795

      @tanstack/ai-mcp

      npm i https://pkg.pr.new/@tanstack/ai-mcp@795

      @tanstack/ai-ollama

      npm i https://pkg.pr.new/@tanstack/ai-ollama@795

      @tanstack/ai-openai

      npm i https://pkg.pr.new/@tanstack/ai-openai@795

      @tanstack/ai-openrouter

      npm i https://pkg.pr.new/@tanstack/ai-openrouter@795

      @tanstack/ai-preact

      npm i https://pkg.pr.new/@tanstack/ai-preact@795

      @tanstack/ai-react

      npm i https://pkg.pr.new/@tanstack/ai-react@795

      @tanstack/ai-react-ui

      npm i https://pkg.pr.new/@tanstack/ai-react-ui@795

      @tanstack/ai-solid

      npm i https://pkg.pr.new/@tanstack/ai-solid@795

      @tanstack/ai-solid-ui

      npm i https://pkg.pr.new/@tanstack/ai-solid-ui@795

      @tanstack/ai-svelte

      npm i https://pkg.pr.new/@tanstack/ai-svelte@795

      @tanstack/ai-utils

      npm i https://pkg.pr.new/@tanstack/ai-utils@795

      @tanstack/ai-vue

      npm i https://pkg.pr.new/@tanstack/ai-vue@795

      @tanstack/ai-vue-ui

      npm i https://pkg.pr.new/@tanstack/ai-vue-ui@795

      @tanstack/openai-base

      npm i https://pkg.pr.new/@tanstack/openai-base@795

      @tanstack/preact-ai-devtools

      npm i https://pkg.pr.new/@tanstack/preact-ai-devtools@795

      @tanstack/react-ai-devtools

      npm i https://pkg.pr.new/@tanstack/react-ai-devtools@795

      @tanstack/solid-ai-devtools

      npm i https://pkg.pr.new/@tanstack/solid-ai-devtools@795

      commit: 522ead5

    7. AlemTuzlak merged this21720dd

    8. AlemTuzlak closed this

Sign in to join this conversation.