feat(sdk): add anthropic-compat subpath for drop-in claude SDK migration - #241
Merged
Conversation
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (4)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Contributor
Code Coverage Summary
CLI Package - Full Text ReportCore Package - Full Text ReportFor detailed HTML reports, please see the 'coverage-reports-22.x-ubuntu-latest' artifact from the main CI run. |
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The protoCLI SDK is API-shaped slightly differently than
@anthropic-ai/claude-agent-sdk: field renames (maxTurns→maxSessionTurns,allowedTools→coreTools), permission mode (bypassPermissions→yolo), and a meaningfully different hook callback shape (Claude's structured{ hook_event_name, tool_name, tool_input }input vs proto's(input: unknown, toolUseId)signature).For consumers migrating from Claude SDK these differences add up to non-trivial diffs — particularly the hook shape, which is typically the largest surface in any Claude SDK integration. This PR adds a subpath export,
@protolabsai/sdk/anthropic-compat, that mirrors Claude SDK's exact API shape and translates internally to proto's native shapes. Migration becomes a one-line import path change:What's translated
maxTurnsmaxSessionTurnsallowedToolscoreToolsdisallowedToolsexcludeToolspathToClaudeCodeExecutablepathToQwenExecutablepermissionMode: 'bypassPermissions'permissionMode: 'yolo'hooks: { PreToolUse: [{ hooks: [fn] }] }matcher arrayshookCallbacks: { PreToolUse: [wrappedFn] }flat record{ decision: 'block', reason }{ shouldSkip: true, message: reason }input.hook_event_name+tool_name+tool_input(input: unknown, toolUseId)— wrapper synthesizeshook_event_name, structured payload already arrives via CLI transportWhat's accepted but silently dropped (Claude-specific, no proto equivalent)
settingSources,resume,agents,maxThinkingTokens,allowDangerouslySkipPermissions,outputFormat. Listed explicitly inOptionsso consumers get source compatibility, but a typecheck against the proto-native API surfaces them as migration points rather than catching all and silently losing data.Files
packages/sdk-typescript/src/anthropic-compat.ts— the runtime layer. ~400 lines, mostly type definitions and atranslateOptions()+translateHooks()+wrapClaudeHookCallback()adapter chain. Delegates to proto's nativequery()after translation.packages/sdk-typescript/src/anthropic-compat.d.ts.template— hand-rolled.d.tsfor the compat subpath. Hand-rolled becausedts-bundle-generatortransitively pulls in proto'stypes/types.tswhenever the compat module references any proto type (even throughParameters<typeof protoQuery>indirection), and that file declaresHookCallback/HookCallbackResult/CanUseToolunder the same names this module exports — yielding duplicate-export errors in the generated bundle. The template is copied todist/anthropic-compat.d.tsduring build.packages/sdk-typescript/scripts/build.js— emitsdist/anthropic-compat.{mjs,cjs}via esbuild and copies the template.d.tsintodist/.packages/sdk-typescript/package.json— adds./anthropic-compatto theexportsmap.Validation
npm run typecheckcleannpm test— 196 passed, 4 skipped (existing tests unchanged)npm run buildsucceeds, emitsdist/anthropic-compat.{mjs,cjs,d.ts}@protolabsai/sdk/anthropic-compatexposes 10 expected runtime symbols (query,tool,createSdkMcpServer,AbortError,isAbortError, 5 SDK message guards).tsfile usingOptions,HookCallback,HookCallbackMatcher,PreToolUseHookInput,PostToolUseHookInput,CanUseTool,SDKUserMessage,AbortError,isAbortErrortypechecks under strict modeUse case driving this
protoMaker (https://github.com/protoLabsAI/protoMaker) has ~1850 lines of consumer code across
apps/server/src/providers/claude-provider.tsandapps/server/src/lib/sdk-options.tswritten against@anthropic-ai/claude-agent-sdk. With this compat subpath the migration drops from ~1000-line surgery to a mechanical import-path swap. After protoMaker burns in the compat path, it'll drop the Anthropic SDK dep entirely.