SDK Bundle Plugin Version Check Inheritance Mechanism in Magnitude

The plugin version check inheritance mechanism in Magnitude SDK bundles works by embedding the private @magnitudedev/sdk package directly into plugins, which automatically carries the exact RPC version validation logic from the protocol layer without requiring plugin authors to implement their own compatibility checks.

SDK bundles in the magnitudedev/magnitude repository provide a zero-configuration compatibility safeguard for plugin-to-daemon communication. When a plugin package bundles the private SDK, it inherits the exact RPC version check that validates protocol compatibility before every remote procedure call. This design centralizes version management in the SDK while ensuring plugin authors cannot accidentally break protocol compatibility.

How Plugin Version Check Inheritance Works

The inheritance mechanism operates across four architectural layers in the Magnitude codebase. Each layer contributes specific functionality that culminates in automatic version validation for bundled plugins.

1. Protocol Layer RPC Declarations

The acn-protocol package defines RPC contracts with embedded version metadata. In packages/acn-protocol/src/boundary/, each RPC is declared using Rpc.make with explicit replay policies and protocol versioning.

// packages/acn-protocol/src/boundary/daemon.ts (conceptual structure)
import { Rpc } from '../rpc.js';

export const getStatus = Rpc.make('daemon.getStatus', {
  request: Rpc.Schema.empty,
  response: Rpc.Schema.struct({
    ok: Rpc.Schema.boolean,
    version: Rpc.Schema.string,
  }),
  // Exact RPC version and replay policy encoded at declaration time
});

The Rpc.make function captures the exact RPC version at build time, baking compatibility requirements into the generated client code.

2. SDK Client Code Generation

The SDK package consumes protocol declarations and generates a type-safe client. This generated client in packages/sdk/src/client.ts implements the version validation logic that compares the daemon's advertised protocol version against the version embedded during code generation.

// Conceptual generated SDK client behavior
class SdkClient {
  private readonly expectedRpcVersion: string;
  
  constructor() {
    // Version baked in at SDK build time from protocol declarations
    this.expectedRpcVersion = __RPC_VERSION_HASH__;
  }
  
  async executeRpc<T>(rpcName: string, payload: unknown): Promise<T> {
    // Automatic version check inherited by all SDK consumers
    const daemonVersion = await this.getDaemonProtocolVersion();
    if (daemonVersion !== this.expectedRpcVersion) {
      throw new VersionMismatchError(
        `Expected RPC version ${this.expectedRpcVersion}, got ${daemonVersion}`
      );
    }
    return this.transport.call(rpcName, payload);
  }
}

3. Plugin Bundle Integration

Plugin packages add @magnitudedev/sdk as a dependency. The bundler (Rollup or Webpack specified in the plugin's build configuration) embeds the SDK client code directly into the plugin artifact.

// Example plugin implementation that inherits version checks automatically
import { ModelCatalog } from '@magnitudedev/sdk';

export async function initializePlugin() {
  // No explicit version validation required—the SDK performs this internally
  const availableModels = await ModelCatalog.list();
  
  // Every SDK method call triggers the inherited exact RPC version check
  return {
    models: availableModels,
    ready: true
  };
}

The bundling process transitively includes all SDK dependencies, ensuring the version check logic is present in the final plugin artifact without additional configuration.

4. Runtime Validation Execution

At runtime, the plugin's bundled SDK client performs the version handshake automatically. The daemon exposes its protocol version through a handshake RPC, and the SDK client validates this against its embedded expected version before executing any subsequent calls.

Key Files in the Version Check Inheritance System

• packages/acn-protocol/src/boundary/ — RPC declarations with version metadata via Rpc.make
• packages/sdk/src/client.ts — Generated client implementing exact RPC version validation
• packages/client-common/src/operations/ — Higher-level operations that rely on inherited SDK checks
• AGENTS.md — Architectural documentation describing the inheritance mechanism

Architectural Documentation Reference

The Magnitude project explicitly documents this design in AGENTS.md (line 29):

"Plugin packages bundle the private SDK and inherit its exact RPC-version check."

This single sentence captures the core principle: version compatibility is not the plugin author's responsibility. By bundling the SDK, plugins automatically receive protocol validation that evolve with SDK updates.

Practical Implications for Plugin Development

Understanding this inheritance mechanism affects how developers approach Magnitude plugin architecture:

• No manual version checks — Plugin code should not implement secondary version validation
• SDK version determines compatibility — Updating the SDK dependency changes the expected protocol version
• Build-time embedding — The exact check is locked at plugin build time, not runtime discovery

// ❌ Anti-pattern: Plugin implementing redundant version check
async function redundantCheck() {
  const status = await Daemon.getStatus();
  if (status.version !== '1.2.3') {  // Don't do this
    throw new Error('Version mismatch');
  }
}

// ✅ Correct pattern: Trust the inherited SDK check
async function correctPattern() {
  // SDK throws VersionMismatchError automatically if needed
  const models = await ModelCatalog.list();
  return models;
}

Summary

• Plugin version check inheritance occurs through SDK bundling, not runtime configuration
• Exact RPC version validation is embedded in generated SDK client code from Rpc.make declarations
• Plugin authors require zero version-checking code — the SDK handles all protocol compatibility
• Centralized updates — Protocol version changes propagate automatically when plugins update their SDK dependency
• Source of truth — AGENTS.md documents the inheritance rule; packages/acn-protocol and packages/sdk implement it

Frequently Asked Questions

How does a Magnitude plugin inherit the exact RPC version check?

Plugin packages inherit the exact RPC version check by bundling the private @magnitudedev/sdk package as a dependency. The SDK contains generated client code that validates protocol compatibility before every RPC call. When the plugin is built, this validation logic is embedded directly into the plugin artifact, making it automatically active without explicit configuration.

What happens if the daemon's protocol version doesn't match the plugin's expected version?

The SDK client throws a VersionMismatchError before executing the RPC call. This error originates in packages/sdk/src/client.ts and prevents any incompatible communication from occurring. The plugin receives a clear error message indicating the version discrepancy, and no partial or corrupted state can result from version skew.

Why don't plugin authors need to implement their own version checking?

According to the magnitudedev/magnitude architecture as documented in AGENTS.md, version validation is intentionally centralized in the SDK to eliminate duplicate logic and human error. Plugin authors import SDK methods and use them directly; the safety mechanism is inherited transparently through the bundling process.

Where is the exact RPC version embedded in the plugin bundle?

The exact RPC version is embedded in the generated SDK client code at build time, originating from Rpc.make declarations in packages/acn-protocol/src/boundary/. The bundler (Rollup/Webpack) includes this generated code when processing the plugin's dependency on @magnitudedev/sdk, making the version check part of the plugin's runtime without separate configuration files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}