perf(tools): resolve tool-choice catalogs in linear time

[luvs01]

Summary

• Compile tool-choice aliases into one request-local resolver instead of rescanning the caller's complete tool catalog for every advertised tool or selector.
• Preserve wire, dotted, and unique bare-name semantics, duplicate-identity suppression, and the original candidate object identity exposed by the public lookup.
• Share the compiled resolver across Responses parsing plus Anthropic, Google, and Command Code filtering; mutable catalog changes rebuild on public lookup, while a compiled resolver rejects changed or newly inserted tool objects.

Verification

• Base: ced9a85c5a44ec13bb68f8a008bb00fe004cda20
• Head: e418f91a7af34d2dcfbb35e6a2c8bf9c5ed4c47e
• The rebased commit retains stable patch ID 68da99268d8089a5c58dba5fd8384a42a64256b3 exactly.
• Bun 1.4.0-canary.1 (9fcdea80b): the isolated performance and barrel regressions passed 21/21 with 44 assertions on the exact head.
• The performance test's temporary iterator instrumentation executes synchronously and restores the descriptor in finally; the exact-head run used --isolate.
• bun run typecheck: passed on the exact head.
• bun run privacy:scan: passed on the exact head.
• git diff --check origin/dev...HEAD: passed on the exact head.
• The patch-equivalent predecessor's actionable reviews were resolved; fresh exact-head automation is the repository review gate.
• No repository-wide suite was duplicated locally.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed. This preserves the public tool-choice contract and changes no user-facing configuration.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. Ambiguous selectors and post-compilation catalog mutation remain fail-closed.

Review readiness checklist

• All CI tests are green on my local testing.
• I pushed my PR to the latest dev commit.
• I resolved all correct Codex and CodeRabbit findings.
• My PR is ready for review.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: db54015e-a10b-431d-8383-e71ded449629

📥 Commits

Reviewing files that changed from the base of the PR and between 5255686 and f07b852.

📒 Files selected for processing (8)

• src/adapters/anthropic.ts
• src/adapters/command-code.ts
• src/adapters/google.ts
• src/responses/parser.ts
• src/types.ts
• src/types/tools.ts
• tests/tool-choice-performance.test.ts
• tests/types-barrel-identity.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Tool-choice resolution now uses a reusable indexed resolver. Adapters delegate filtering to shared predicates, response parsing uses resolver candidate counts, and tests cover ambiguous names, catalog mutations, and barrel export identity.

Changes

Tool-choice resolution

Layer / File(s)	Summary
Resolver and predicate implementation src/types/tools.ts:46-206	Adds immutable tool identity snapshots, alias indexes, reusable candidate lookup, authorization, and unique-selection operations. Existing candidate and predicate helpers use the indexed catalog.
Consumer integration and public export src/types.ts:8, src/responses/parser.ts:14,761-763, src/adapters/anthropic.ts:17,799-800, src/adapters/command-code.ts:6,159, src/adapters/google.ts:17,331-332	Adapters use toolChoiceToolPredicate for filtering. Response parsing uses createToolChoiceResolver for ambiguity checks. The types barrel re-exports the resolver.
Resolver regression coverage tests/tool-choice-performance.test.ts:1-84, tests/types-barrel-identity.test.ts:28	Tests cover ambiguous allowed_tools lookups, catalog mutations, compiled resolver behavior, and runtime export identity.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to f07b8

This PR improves tool-choice resolution performance while preserving lookup behavior and passes the listed validation checks; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: lidge-j

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 12 functions across 8 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: resolving tool-choice catalogs in linear time.

✨ 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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

✅ READY

• all PR quality gates passed; the review readiness checklist is complete.

Review readiness checklist

• ✅ All CI tests are green on my local testing.
• ✅ I pushed my PR to the latest dev commit.
• ✅ I resolved all correct Codex and CodeRabbit findings.
• ✅ My PR is ready for review.

✅ 4/4 boxes ticked.

This pull request is already Ready for Review.
The review-ready label marks this PR as ready; review automation runs independently.
Maintainers: @lidge-jun @Ingwannu

[lidge-jun]

리뷰 · 우선순위 57 / 80

설명: 이 PR은 도구 선택(tool_choice)을 검사할 때, 도구 목록을 매번 처음부터 다시 훑지 않도록 한 번 인덱스로 모아 두는 성능 개선이다. 지금 CURRENT dev HEAD는 764ef326c 이고, 직전 525568652 위에 docs-only 머지 #2336 (Cursor round-2 안정화 연구/로드맵 lock: devlog/_plan/260822_senpi_cursor_transfer/100·110·120·190)만 올라왔다. 코드 경로인 src/types/tools.ts 의 tool-choice 로직은 그 docs 머지와 무관하게 그대로다. 현재 HEAD에서는 toolChoiceCandidates/toolAllowedByChoice가 선택자마다 카탈로그를 다시 스캔하고, Anthropic/Google/Command Code 어댑터가 그 함수를 필터에 직접 쓴다. 이 PR은 createToolChoiceResolver로 요청마다 인덱스를 한 번 만들고, toolChoiceToolPredicate와 src/responses/parser.ts의 모호한 이름 검사를 그 인덱스로 돌리며, 세 어댑터도 predicate로 바꾼다. 공개 API는 유지하고, 컴파일 이후 도구 객체가 바뀌면 실패 닫힘(fail-closed)이다. Cursor #2334 라우터/#2332 H2 풀/#2329·#2330 카탈로그 버그와는 다른 층이다. 카탈로그 팁(Ox Alpha, deepseek-v4-flash-vision-exp)과 #2188 사이드카도 건드리지 않는다. types.ts는 export 한 줄만 추가한다. 베이스는 직전 HEAD 525568652라서 지금 764ef326c docs 위로는 충돌 없이 붙을 가능성이 높다. 게이트 READY, 포커스 테스트+typecheck 통과 주장. 도구가 많을 때 응답 경로가 느려지는 체감을 줄이는 쪽이라 57.

src/types/tools.ts toolChoiceCandidates/toolAllowedByChoice - 공개 함수는 호출마다 전체 인덱스를 다시 만들어, predicate/parser만 컴파일 공유가 된다
tests/tool-choice-performance.test.ts - Array.prototype의 Symbol.iterator를 잠시 바꿔서 재스캔을 세므로, 병렬 bun 테스트와 섞이면 깨질 수 있다
src/types.ts createToolChoiceResolver re-export - types.ts/config.ts 스플릿이 tools 배럴을 옮기면 리베이스 싸움 대신 닫고 다시 짜는 편이 맞다
PR base 5255686 vs HEAD 764ef32 - 작성자 체크리스트의 latest-dev는 #2336 docs 착지 전 기준이다. 코드 충돌은 거의 없지만 베이스는 한 칸 뒤다

메인테이너의 판단이 필요한 지점

• 지금 바로 머지할지, types.ts/config.ts 스플릿이 tools 배럴을 먼저 옮길 때까지 기다릴지
• 공개 toolChoiceCandidates가 호출마다 재빌드하는 호환 동작을 유지할지, 다음 PR에서 createToolChoiceResolver만 쓰도록 좁힐지
• 성능 테스트의 Array.prototype 패치를 유지할지, 카탈로그 읽기 카운트만으로 바꾸게 할지

너의 추천
현재 764ef326c 위로 fast-forward/리베이스한 뒤(docs-only라 충돌 거의 없음) 이 범위 그대로 머지한다. Cursor round-2(110 watchdog / 120 OAuth·H2 shutdown)나 카탈로그 제외(#2330)와 묶지 않는다. types/config 스플릿이 이미 tools 배럴을 옮긴 뒤에야 충돌이 보이면 리베이스하지 말고 닫고 다시 연다. 라벨은 그대로 둔다.

이 댓글은 grok-bot이 작성했습니다

[luvs01]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: e418f91a7a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".