P0.4: Canonical Agent SDK

[Mehd1b]

Summary

Introduces the kernel-sdk crate providing the canonical interface for zkVM agent development, along with significant hardening to kernel-core.

kernel-sdk (new crate)

• AgentContext: Execution context with version checking, snapshot helpers
• Action constructors: echo, open_position, close_position, adjust_position, swap
• Payload decode helpers with structural validation
• Math module: checked/saturating arithmetic, basis points, drawdown calculations
• Bytes module: fixed-offset and cursor-style readers/writers
• Prelude with common exports (Vec but NOT vec! macro to discourage unbounded allocations)
• Reference echo_agent example with comprehensive tests

kernel-core hardening

• no_std support with extern crate alloc
• Codec refactor: encode_into/encoded_len trait methods to avoid per-action allocation
• Fixed get_var_bytes offset rewind footgun, uses checked_add throughout
• Version validation in encode_into (prevents encoding invalid structures)
• MAX_AGENT_OUTPUT_BYTES enforcement on encode/decode
• sha256() canonical helper with thin wrapper commitment functions
• debug_assert checks for encoded_len/encode_into consistency

Documentation

• spec/sdk.md: Complete SDK specification (690 lines)
• docs/P0.4_DOCUMENTATION.md: Comprehensive usage guide (1117 lines)

Feature hygiene

• kernel-sdk: default-features = false, no_std
• kernel-core: default-features = false for sha2, std feature for host tooling
• kernel-guest: default-features = false for kernel-core
• host-tests: features = ["std"] for kernel-core

Test plan

• cargo test - All 159 tests pass
• cargo build - No warnings
• Verified no_std compatibility via clippy lints

[claude]

Claude finished @Mehd1b's task —— View job

---

PR Review: P0.4 Canonical Agent SDK

I've completed a comprehensive review of this substantial PR introducing the kernel-sdk crate and hardening kernel-core. Overall, this is high-quality code with excellent design principles and documentation. Here are my findings:

Review Checklist:

• Analyze new kernel-sdk crate structure and API design
• Review kernel-core hardening changes
• Check code quality and best practices
• Identify potential bugs or issues
• Assess performance considerations
• Evaluate security concerns
• Review test coverage and documentation

✅ Strengths

Architecture & Design

• Excellent SDK design: The kernel-sdk provides a clean, minimal interface that properly isolates agent code from kernel internals
• Strong security boundaries: #![no_std], #![forbid(unsafe_code)], and clippy lints enforce safe zkVM execution
• Well-designed API: Prelude exports are carefully curated - notably excluding vec![] macro to discourage unbounded allocations
• Proper versioning: SDK version checking ensures compatibility between agent and kernel versions

Code Quality

• Comprehensive documentation: Both inline docs and standalone specification files (spec/sdk.md, docs/P0.4_DOCUMENTATION.md) are excellent
• Consistent patterns: Math operations use checked arithmetic, byte operations have proper bounds checking
• Good error handling: Functions return Option or Result instead of panicking in most cases
• Reference implementation: The echo_agent.rs example demonstrates proper usage patterns

Security

• No unsafe code: All crates properly forbid unsafe operations
• Input validation: Payload size limits enforced (MAX_ACTION_PAYLOAD_BYTES, MAX_AGENT_OUTPUT_BYTES)
• Deterministic operations: All math uses integer arithmetic with explicit overflow handling
• Replay protection: Execution nonce field provides proper replay protection

Performance

• Zero-allocation design: Many operations use pre-allocated buffers and avoid unnecessary allocations
• Efficient encoding: encode_into method allows reusing buffers instead of per-action allocation
• Bounded execution: Size limits prevent runaway memory usage

⚠️ Areas for Improvement

Minor Issues

1. Test-only unwrap() usage (crates/kernel-sdk/src/types.rs:466, src/bytes.rs:432):

   • These are in test code, which is acceptable, but could use .expect() with descriptive messages for better debugging

2. Potential payload truncation edge case (echo_agent.rs:64-70):

   • The example truncates inputs to MAX_ACTION_PAYLOAD_BYTES but doesn't indicate to the caller that truncation occurred
   • Consider adding a flag or separate action type for truncated payloads

3. Missing validation in action constructors:

   • open_position_action() has a debug assert for direction validation but no runtime validation
   • Invalid directions will be caught by constraint engine but earlier validation could provide better error messages

Documentation Enhancements

1. Error handling patterns: While individual functions are well-documented, a guide on error handling patterns for agent developers would be helpful

2. Performance guidelines: Consider adding guidance on memory usage patterns and allocation limits for agent developers

Minor Code Quality

1. Consistent error types: Some functions return Option while others return Result - consider standardizing on Result with descriptive error types for better debugging

2. Dead code in examples: The echo_agent.rs has #[allow(dead_code)] functions that could be moved to separate example files

🎯 Recommendations

1. Consider runtime validation: Add optional runtime validation for action parameters (e.g., direction bounds) with feature flags

2. Error context: Consider adding error context to codec operations for better debugging experience

3. Integration testing: While unit tests are comprehensive, consider adding integration tests that exercise the full agent lifecycle

4. Fuzzing targets: The codec operations would benefit from fuzzing tests to ensure robust parsing

📊 Test Coverage Assessment

• Unit tests: Excellent coverage across all modules with meaningful test cases
• Example code: Reference implementation provides practical usage examples
• Edge cases: Good coverage of boundary conditions and error paths
• Documentation tests: Code examples in docs are properly tested

🔒 Security Assessment

This code demonstrates excellent security practices:

• No unsafe operations or potential memory safety issues
• Proper input validation and bounds checking
• Deterministic execution suitable for zkVM environments
• Clear separation between trusted kernel and untrusted agent code

Overall Assessment

This is a well-architected, secure, and thoroughly documented addition to the codebase. The SDK provides exactly the right level of abstraction for zkVM agent development while maintaining strong security guarantees. The code quality is high and the design principles are sound.

Recommendation: ✅ Approve - This PR significantly improves the codebase and provides a solid foundation for agent development.