refactor(cursor): split tool-definitions into naming, schema, and guidance leaves (split S04 L1/5)

[lidge-jun]

Summary

• Pure move: src/adapters/cursor/tool-definitions.ts (777 lines) splits into three sibling leaves — tool-naming.ts (252: tool-name constants, alias/choice predicates, wire-name mapping), tool-schemas.ts (195: input/arg-normalize schemas and shell-bridge validation), tool-guidance.ts (236: generic-tool-use hint and the tool-guidance system note) — leaving a 112-line residual that builds the definitions and re-exports all 55 previously exported names. Every existing import path (13 consumers) keeps working; three formerly private helpers become leaf-internal exports and are not exposed through the facade.
• Why: 777-line file over the 400-line module limit; naming, schemas and guidance are separate concerns with a clean one-way dependency (schemas → naming, guidance → naming). Zero behavior change.
• Plan and evidence: devlog/_plan/260905_now_split_train/110_adapters_cursor_tool_definitions.md; rules 003_parent_decisions.md (PURE-MOVE-SIZE-01, TYPE-CYCLE-01).

Stack (S04 adapters-cursor; merge bottom-up):

#	PR	Branch	Base	Review focus
5	TBD	codex/split-adapters-cursor-protobuf-events	codex/split-adapters-cursor-tool-definitions	protobuf-events
4	TBD	codex/split-adapters-cursor-request-builder	codex/split-adapters-cursor-images	request-builder
3	TBD	codex/split-adapters-cursor-images	codex/split-cursor-desktop-executor-contract	images
2	TBD	codex/split-adapters-cursor-catalog	codex/split-cursor-desktop-executor-contract	catalog
1	this PR	codex/split-adapters-cursor-tool-definitions ← you are here	codex/split-cursor-desktop-executor-contract	naming / schema / guidance leaves
0	#3557	codex/split-cursor-desktop-executor-contract	dev	desktop executor type contract

Depends on #3557 (its type-contract move is what keeps the new leaves out of the old provider→desktop type cycle). Review this PR's diff only (5 files, +701/−670; non-move diff: 6 leaf import lines, 5 residual wiring lines, 3 export modifiers, 13 test lines). Move-aware view: git diff --color-moved=dimmed-zebra codex/split-cursor-desktop-executor-contract...HEAD.

Verification

• bun run typecheck → exit 0
• Focused: cursor-request-builder, cursor-structured-edit, cursor-tool-choice, cursor-tool-definitions, responses-tool-conformance → 203 pass / 0 fail
• tests/lab/core-lab-boundary.test.ts → 17 pass / 0 fail (the leaves are reached from src/server/responses/core.ts via the cursor adapter)
• Red-drives, then restored: breaking the bare-name alias predicate fails cursor-tool-definitions.test.ts:44; removing the pinned-choice escape fails :340; a Lab import in tool-naming.ts fails the transitive boundary guard with the full chain.
• bun run privacy:scan → passed
• Original-path importers: 13 files, same set as base; tool-naming.ts imports no sibling leaf.
• New test: seam identity (facade vs leaf bindings) for naming/schemas/guidance; tool-naming.ts is the DAG root.
• Full suite on the remote CI host (lidge) at this exact SHA: recorded in the devlog doc.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed (devlog unit records the layer; no user-facing change).
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults (shell-bridge validation moved byte-for-byte; guards driven red once).

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (2)

• ^dev$
• ^preview$

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: a4d152e7-5b20-4385-985f-a2a203ec6b32

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-05T01:22:09.523209Z	73672ff	PR opened

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 69 / 80

이 PR은 adapters-cursor 스플릿 열차 S04의 L1/5 칸입니다. 지금 dev HEAD(24cc558d5, package 2.43.0)의 src/adapters/cursor/tool-definitions.ts는 777줄이라 모듈 400줄 한도를 크게 넘습니다. 한 파일 안에 (1) 도구 이름·별칭·wire-name 매핑, (2) 입력/정규화 스키마와 shell-bridge 검증, (3) generic-tool-use 힌트·가이던스 시스템 노트, (4) structured-edit 합성·protobuf 정의 빌더가 섞여 있습니다. 이 변경은 앞의 세 관심사를 형제 리프로 나눕니다. tool-naming.ts(252줄)·tool-schemas.ts(195줄)·tool-guidance.ts(236줄)로 옮기고, residual tool-definitions.ts는 112줄만 남겨 structured-edit 도구 합성·encodeCursorInputSchema·buildCursorToolDefinitions·인코딩 크기 헬퍼를 담당합니다. 예전 public 이름 55개는 residual이 re-export해서 기존 import 경로(소비자 13곳)를 깨지 않습니다. 본문이 말하는 의존 방향은 schemas→naming, guidance→naming 한 방향이고, naming은 형제 리프를 가져오지 않습니다(TYPE-CYCLE-01). base는 dev가 아니라 #3557 브랜치 codex/split-cursor-desktop-executor-contract입니다. L0 타입 계약 이동이 있어야 새 리프가 예전 provider→desktop 타입 사이클에 다시 묶이지 않는다고 본문이 설명합니다. 행동 변경 없음이 목표인 PURE-MOVE-SIZE-01 층입니다. 포커스 스위트 203 pass·Lab boundary 17 pass·red-drive·privacy:scan 주장이 있고, 새 테스트는 facade와 leaf 바인딩이 같은 함수 객체인지와 naming이 from "./tool- 를 쓰지 않는지 고정합니다. Cross-platform CI는 리눅스 test 1–4/4·gates 등이 초록이고, 이 글을 쓰는 시점에 macos 잡이 아직 진행/대기 중이라 macos까지 초록 확인이 안전합니다. types/config 스플릿 무효화·close-don't-rebase 대상은 아닙니다.

src/adapters/cursor/tool-definitions.ts (residual) - 빌더·structured-edit·protobuf 인코딩만 남겼습니다. 공개 표면은 re-export 세 줄로 naming/schemas/guidance를 이어 붙입니다. 소비자 경로는 유지됩니다.

src/adapters/cursor/tool-naming.ts - DAG 루트입니다. 상수·별칭·wire-name·choice 매칭이 여기로 모입니다. 형제 리프 import가 없어야 하고, 새 테스트가 소스에 from "./tool- 없음을 검사합니다.

src/adapters/cursor/tool-schemas.ts - 입력/arg-normalize 스키마와 shell-bridge 검증이 이동합니다. naming만 의존합니다. #399 cmd→command 재작성 계약이 스키마 쪽으로 따라갑니다.

src/adapters/cursor/tool-guidance.ts - generic-tool-use 힌트와 시스템 노트가 이동합니다. naming만 의존합니다. code-mode 가이던스가 shell-bridge 가이던스와 섞이지 않게 유지하는 층입니다.

본문 “formerly private helpers become leaf-internal exports” - facade로는 안 열고 leaf 안에서만 export합니다. 의도된 시임이면 괜찮고, 공개 API 표가 커지지 않았는지만 확인하면 됩니다.

경로 S04 L0 #3557 - 이 PR의 base입니다. 아직 OPEN이라 #3557이 먼저 dev에 올라야 이 칸을 올릴 수 있습니다. L2 이후(images/catalog/request-builder/protobuf-events)도 이 브랜치 위에 쌓입니다.

tests/providers/cursor/cursor-tool-definitions.test.ts - seam identity + naming DAG 루트 검사를 추가했습니다. PURE-MOVE 회귀를 잡는 값이 있습니다.

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

• #3557을 먼저 머지한 뒤 이 PR을 dev에 올릴지, S04 여러 칸을 묶어 랜딩할지
• leaf-internal export로 연 예전 private 헬퍼를 계속 leaf 공개로 둘지
• macos CI가 끝나기 전에 exact-head 호스트 스위트 기록만으로 머지할지

너의 추천
#3557이 dev에 랜딩된 뒤, CI(특히 macos)가 초록이면 이 칸을 머지하세요. 단독으로 dev에 바로 올릴 수 없는 스택 칸입니다. 랜딩 후 S04 L2를 이 브랜치 위에 이어 붙이면 됩니다. 지금 당장 close하거나 rebase할 이유는 없습니다.

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

[Ingwannu]

Approved for the isolated stack diff at exact head fdddbd3e1516997111b201a7c191fc08a6f8d4dd.

The facade keeps the established import surface, the naming/schema/guidance leaves preserve the moved behavior, and the new seam test pins binding identity plus the intended dependency root. Focused Cursor/tool-conformance and Lab-boundary validation: 220 pass / 0 fail. Root typecheck passes, git diff --check is clean, and exact-head hosted CI is green.

Landing condition: this PR currently targets the stack branch codex/split-cursor-desktop-executor-contract, not an integration branch. Per repository policy, merge #3557 bottom-up first, then retarget/rebase this exact diff onto current dev and require fresh exact-head CI before merging. This approval is for the reviewed layer; it is not approval to land the stacked base directly.

[lidge-jun]

Superseded by aggregate PR #3668, admin-merged into dev as 6585e6a after exact-head CI and tested-tree verification. This original PR was not individually merged; its rebased content and historical records were consolidated in #3668. The original branch is preserved. Further unimplemented debt layers remain deferred.

[lidge-jun]

Landed via #3668 at 6585e6a