Skip to content

kelvin-core-sdk.md

Latest commit

 

History

History
154 lines (102 loc) · 4.55 KB

kelvin-core-sdk.md

File metadata and controls

154 lines (102 loc) · 4.55 KB

Kelvin Core SDK

Kelvin Core is the extension SDK for KelvinClaw. It keeps the runtime minimal while allowing pluggable implementations behind stable interfaces.

1. SDK Identity

  • Canonical SDK name: Kelvin Core
  • Core SDK API version constant: KELVIN_CORE_API_VERSION
  • Source: crates/kelvin-core/src/sdk.rs

2. Stable Contracts

Extension boundaries remain trait-first:

  • ModelProvider
  • MemorySearchManager
  • Tool
  • SessionStore
  • EventSink
  • CoreRuntime / RunRegistry for deterministic run lifecycle semantics

Source: crates/kelvin-core/src/*.rs

3. Plugin Manifest Schema

PluginManifest defines extension metadata:

  • id, name, version, api_version
  • capabilities
  • compatibility bounds (min_core_version, max_core_version)
  • experimental flag

Source: crates/kelvin-core/src/sdk.rs

4. Capability and Permission Model

PluginCapability captures required powers:

  • interface capabilities (model/memory/tool/session/event)
  • privileged capabilities (fs_read, fs_write, network_egress, command_execution)

PluginSecurityPolicy controls what is allowed at registration time.

Source: crates/kelvin-core/src/sdk.rs

5. Compatibility Gate

check_plugin_compatibility(...) validates:

  • manifest schema correctness
  • API major-version compatibility
  • core-version range matching
  • security policy compliance

Source: crates/kelvin-core/src/sdk.rs

6. Registry and Composition

PluginFactory exposes concrete implementations without coupling core to vendor crates.

PluginRegistry and InMemoryPluginRegistry provide:

  • plugin registration with compatibility checks
  • lookup by plugin id
  • manifest inventory

SdkToolRegistry provides:

  • fail-fast projection from plugin metadata to runtime ToolRegistry
  • duplicate-tool-name rejection
  • capability/implementation consistency checks (tool_provider capability must match actual tool export)

SdkModelProviderRegistry provides:

  • fail-fast projection from plugin metadata to runtime ModelProvider wiring
  • duplicate provider_name::model_name rejection
  • capability/implementation consistency checks (model_provider capability must match actual provider export)

Source: crates/kelvin-core/src/sdk.rs

6.1 First-Party Tool Pack (SDK Plugin Lane)

kelvin-sdk ships a first-party default tool pack registered through the SDK plugin path:

  • fs_safe_read
  • fs_safe_write
  • web_fetch_safe
  • schedule_cron
  • session_tools

Sensitive operations require explicit per-call approvals and are bounded by scope/allowlist policy.

Source: crates/kelvin-sdk/src/toolpack.rs

7. Conformance Tests

Current SDK tests cover:

  • manifest validation failures
  • policy-based capability rejection
  • compatibility acceptance
  • registry registration/get/list
  • duplicate registration rejection
  • core-version range rejection
  • SdkToolRegistry build success for registered tool plugins
  • rejection of missing tool implementation when tool_provider is declared
  • rejection of duplicate tool names across plugins

Source: crates/kelvin-core/src/sdk.rs (#[cfg(test)])

8. Governance and Adoption

SDK operation is governed by:

This keeps Kelvin small and stable while making plugin development predictable and safe.

Detailed security/stability test coverage matrix:

SDK certification command:

cargo test -p kelvin-sdk

9. Installed Plugin Runtime (SDK Path)

kelvin-brain now includes an installed-plugin loader that keeps plugin execution on the SDK path:

  • package discovery from plugin home (<plugin_id>/<version>/plugin.json)
  • manifest integrity checks (entrypoint_sha256) and optional mandatory signatures (plugin.sig)
  • publisher trust policy (PublisherTrustPolicy) with Ed25519 keys
  • publisher revocation checks and plugin->publisher pinning checks
  • runtime capability scopes for filesystem/network access
  • per-tool operational controls (timeout, retries, rate limit, circuit breaker)

Primary API:

  • InstalledPluginLoaderConfig
  • load_installed_plugins(...)
  • load_installed_plugins_default(...)
  • load_installed_tool_plugins(...)
  • load_installed_tool_plugins_default(...)
  • default_plugin_home()
  • default_trust_policy_path()

Source: crates/kelvin-brain/src/installed_plugins.rs