feat(schema): add plugin asset version requirements

Amp-Thread-ID: https://ampcode.com/threads/T-019f8a17-1cf9-744d-8aeb-c429c20f97f8

Author: AprilNEA

packages/foundation/schema/src/model/__tests__/plugin.test.ts

@@ -62,7 +62,7 @@ describe('PluginSchema', () => {
         availability: 'available',
         installations: [],
         components: [{ kind: 'skill', name: 'latex', enabled: true }],
-        assets: ['tool:tectonic'],
+        assets: [{ id: 'tool:tectonic', versionRange: '>=0.16.0 <0.17.0' }],
         managementCapabilities: {
           install: true,
           uninstall: true,
@@ -74,7 +74,7 @@ describe('PluginSchema', () => {
     ).toMatchObject({
       provider: 'codex',
       installations: [],
-      assets: ['tool:tectonic'],
+      assets: [{ id: 'tool:tectonic', versionRange: '>=0.16.0 <0.17.0' }],
     });
   });
 
@@ -109,7 +109,51 @@ describe('PluginSchema', () => {
         availability: 'available',
         installations: [],
         components: [],
-        assets: ['agent:codex'],
+        assets: [{ id: 'agent:codex' }],
+        managementCapabilities: {
+          install: true,
+          uninstall: true,
+          update: false,
+          enable: false,
+          disable: false,
+        },
+      }).success,
+    ).toBe(false);
+  });
+
+  it('rejects the former string shorthand for tool requirements', () => {
+    expect(
+      PluginSchema.safeParse({
+        provider: 'codex',
+        id: 'legacy@openai',
+        name: 'legacy',
+        keywords: [],
+        availability: 'available',
+        installations: [],
+        components: [],
+        assets: ['tool:tectonic'],
+        managementCapabilities: {
+          install: true,
+          uninstall: true,
+          update: false,
+          enable: false,
+          disable: false,
+        },
+      }).success,
+    ).toBe(false);
+  });
+
+  it('rejects an empty version compatibility range', () => {
+    expect(
+      PluginSchema.safeParse({
+        provider: 'codex',
+        id: 'invalid-range@openai',
+        name: 'invalid-range',
+        keywords: [],
+        availability: 'available',
+        installations: [],
+        components: [],
+        assets: [{ id: 'tool:tectonic', versionRange: '' }],
         managementCapabilities: {
           install: true,
           uninstall: true,

packages/foundation/schema/src/model/plugin.ts

@@ -111,6 +111,16 @@ export const PluginLinksSchema = z.object({
 });
 export type PluginLinks = z.infer<typeof PluginLinksSchema>;
 
+/**
+ * A plugin's compatibility requirement on a trusted managed tool. The host selects the exact
+ * version; `versionRange` only gates compatibility and never instructs the host what to download.
+ */
+export const PluginAssetRequirementSchema = z.object({
+  id: ManagedToolAssetIdSchema,
+  versionRange: z.string().min(1).optional(),
+});
+export type PluginAssetRequirement = z.infer<typeof PluginAssetRequirementSchema>;
+
 const pluginFields = {
   /** Opaque provider-native id; pair with `provider` for identity. */
   id: z.string().min(1),
@@ -130,10 +140,10 @@ const pluginFields = {
   installations: z.array(PluginInstallationSchema),
   components: z.array(PluginComponentSchema),
   /**
-   * Managed runtime dependencies required by this plugin (for example `tool:tectonic`). Plugins
-   * declare only trusted catalog ids; download URLs, versions, and integrity stay host-owned.
+   * Managed runtime dependencies required by this plugin. Plugins declare trusted catalog ids and
+   * optional compatibility ranges; exact versions, download URLs, and integrity stay host-owned.
    */
-  assets: z.array(ManagedToolAssetIdSchema),
+  assets: z.array(PluginAssetRequirementSchema),
   managementCapabilities: PluginManagementCapabilitiesSchema,
 } as const;