Add ApprovalPolicy support to controller toWasmPolicies

[kronosapiens]

Summary

The controller SDK's toWasmPolicies function was missing ApprovalPolicy handling that exists in the keychain implementation. This caused merkle root mismatches for:

• SessionConnector (native/Capacitor apps)
• NodeProvider (Node.js server-side)
• TelegramProvider (Telegram mini-apps)

When these connectors are used with approve policies that include spender and amount fields, the session registration (via keychain) would create ApprovalPolicy objects, while session usage (via controller SDK) would create CallPolicy objects. This resulted in different merkle roots and "session/not-registered" errors.

Changes

• Add ApprovalPolicy handling to packages/controller/src/utils.ts to match keychain implementation
• Update SessionContracts type in packages/controller/src/policies.ts to properly include Approval methods
• Add comprehensive tests for ApprovalPolicy handling

Test plan

• New tests verify ApprovalPolicy is created for approve methods with spender/amount
• Tests verify fallback to CallPolicy (with deprecation warning) for legacy approve policies
• Tests verify correct sorting behavior with mixed approve/non-approve methods
• Existing canonical ordering tests continue to pass

Fixes

Closes #2370

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
controller-example-next	Ready	Preview	Feb 4, 2026 11:07pm
keychain	Ready	Preview	Feb 4, 2026 11:07pm
keychain-storybook	Ready	Preview	Feb 4, 2026 11:07pm

[claude]

---

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

---

[claude]

Claude finished @kronosapiens's task —— View job

---

Documentation Updates for ApprovalPolicy Changes

Todo List:

• Examine docs-repo directory structure
• Review the changed files to understand functionality changes
• Assess if documentation updates are needed for this bug fix
• Update documentation files
• Commit and push changes

Analysis Summary

The PR #2372 fixed a critical bug where the controller SDK's toWasmPolicies function was missing ApprovalPolicy handling, causing merkle root mismatches for SessionConnector, NodeProvider, and TelegramProvider.

Documentation Updates Made

I've updated the documentation to include the required spender field for approve methods, which was missing from all examples. This prevents users from creating policies that trigger the new deprecation warning.

Files Updated:

• src/pages/controller/sessions.md - Added spender field to approve examples and updated type definitions
• skills/controller-backend/SKILL.md - Added spender and amount fields to approve method
• skills/controller-react/SKILL.md - Added spender and amount fields to approve method
• skills/controller-sessions/SKILL.md - Added spender field to approve method
• src/pages/controller/examples/react.md - Added spender and amount fields to approve method
• src/pages/controller/examples/svelte.md - Added spender and amount fields to approve method
• src/pages/controller/native/react-native.md - Added spender and amount fields to approve method

Key Changes:

• All approve policy examples now include both spender and amount fields as required
• Updated type definition to clarify these fields are required for approve methods
• Added documentation section explaining the requirement to avoid deprecation warnings

The changes are staged and ready to commit, but I need permission to configure git user settings for the docs repository.