feat(skillPlugin): enhance skill loading and selection capabilities with new utility functions and type definitions

Author: gene9831

packages/kit/src/index.ts

@@ -5,3 +5,12 @@ export * from './storage'
 export * from './types'
 export { extractTextFromResponse, formatMessages, handleSSEStream, sseStreamToGenerator } from './utils'
 export * from './vue'
+export { loadSkill, loadSkillWithDetails } from './skills/loader'
+export type {
+  BrowserSkillLoadOptions,
+  GithubSkillLoadOptions,
+  SkillLoadJob,
+  SkillLoadOptions,
+  SkillLoadResult,
+} from './skills/loader'
+export type { SkillCandidate, SkillDefinition } from './skills/types'

packages/kit/src/message/plugins/skillPlugin.ts

@@ -146,11 +146,15 @@ interface SkillPluginHooks extends MessageEnginePlugin {
 
 type SelectionInput<T extends SkillSelection> = T | ((context: BasePluginContext) => MaybePromise<T>)
 
-export type SkillPluginOptions<S extends SkillSelection = SkillSelection> = SkillPluginHooks &
-  RequireResolver<S> &
-  RequireCandidateProvider<S> & {
-    selection: SelectionInput<S>
-  }
+type SkillPluginOptionsFor<S extends SkillSelection> = S extends SkillSelection
+  ? SkillPluginHooks &
+      RequireResolver<S> &
+      RequireCandidateProvider<S> & {
+        selection: SelectionInput<S>
+      }
+  : never
+
+export type SkillPluginOptions<S extends SkillSelection = SkillSelection> = SkillPluginOptionsFor<S>
 
 const skillPluginContextKey = '__tiny_robot_skill'
 
@@ -186,6 +190,18 @@ const createResolvedSkillInstructions = (skills: SkillDefinition[]): string[] =>
   return instructions
 }
 
+const normalizeSkills = (skills: SkillDefinition[]) => {
+  const skillMap = new Map<string, SkillDefinition>()
+
+  for (const skill of skills) {
+    if (!skillMap.has(skill.name)) {
+      skillMap.set(skill.name, skill)
+    }
+  }
+
+  return [...skillMap.values()]
+}
+
 const normalizeCandidates = (candidates: SkillCandidate[]) => {
   const candidateMap = new Map<string, SkillCandidate>()
 
@@ -213,6 +229,16 @@ const setSkillContext = (context: BasePluginContext, skillContext: SkillRequestC
   context.setCustomContext({ [skillPluginContextKey]: skillContext })
 }
 
+const hasEnabledToolPlugin = (context: BasePluginContext) => {
+  return context.plugins.some((plugin) => {
+    if (plugin.name !== 'tool') {
+      return false
+    }
+
+    return typeof plugin.disabled === 'function' ? !plugin.disabled(context) : !plugin.disabled
+  })
+}
+
 const resolveSkillsByNames = async (
   skillNames: string[],
   getSkillByName: SkillResolver['getSkillByName'],
@@ -228,11 +254,23 @@ const resolveSkillsByNames = async (
     }),
   )
 
-  const skills = results.map((result) => result.skill).filter((skill): skill is SkillDefinition => Boolean(skill))
+  const skillMap = new Map<string, SkillDefinition>()
+  const unresolvedSkillNames: string[] = []
+
+  for (const result of results) {
+    if (result.failed || !result.skill || result.skill.name !== result.name) {
+      unresolvedSkillNames.push(result.name)
+      continue
+    }
+
+    if (!skillMap.has(result.skill.name)) {
+      skillMap.set(result.skill.name, result.skill)
+    }
+  }
 
   return {
-    skills,
-    unresolvedSkillNames: results.filter((result) => result.failed || !result.skill).map((result) => result.name),
+    skills: [...skillMap.values()],
+    unresolvedSkillNames,
   }
 }
 
@@ -346,7 +384,7 @@ export const skillPlugin = <S extends SkillSelection = SkillSelection>(
         let unresolvedSkillNames: string[]
 
         if (selectionOptions.skills) {
-          skills = selectionOptions.skills
+          skills = normalizeSkills(selectionOptions.skills)
           requestedSkillNames = skills.map((skill) => skill.name)
           unresolvedSkillNames = []
         } else {
@@ -384,6 +422,10 @@ export const skillPlugin = <S extends SkillSelection = SkillSelection>(
       }
 
       // mode: 'auto'
+      if (!hasEnabledToolPlugin(context)) {
+        throw new Error('skillPlugin auto mode requires an enabled toolPlugin')
+      }
+
       const getCandidates = getSkillCandidates
       if (!getCandidates) {
         throw new Error('getSkillCandidates is required when auto mode is enabled')

packages/kit/src/node.ts

@@ -6,3 +6,4 @@ export type {
   SkillLoadOptions,
   SkillLoadResult,
 } from './skills/loader/node'
+export type { SkillCandidate, SkillDefinition } from './skills/types'

packages/kit/src/skills/capabilities/selection.ts

@@ -6,6 +6,12 @@ import { parseToolArguments } from './utils'
 
 const skillSelectionToolName = 'select_skills'
 
+const normalizeMaxSelectedSkills = (value: number | undefined, candidateCount: number) => {
+  const integerValue = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : candidateCount
+
+  return Math.min(candidateCount, Math.max(0, integerValue))
+}
+
 export const createSkillSelectionInstructions = ({
   candidates,
   preferredSkillNames,
@@ -50,7 +56,8 @@ export function createSkillSelectionRuntimeTools(
 
   const candidateNames = candidates.map((candidate) => candidate.name)
   const candidateNameSet = new Set(candidateNames)
-  const maxSelectedSkills = Math.max(0, options.maxSelectedSkills ?? candidateNames.length)
+  const maxSelectedSkills = normalizeMaxSelectedSkills(options.maxSelectedSkills, candidateNames.length)
+  let selectionStarted = false
 
   return [
     {
@@ -105,6 +112,14 @@ export function createSkillSelectionRuntimeTools(
           }
         }
 
+        if (selectionStarted) {
+          return {
+            error: 'skill_selection_already_resolved',
+          }
+        }
+
+        selectionStarted = true
+
         const result = {
           requestedSkillNames,
         }

packages/kit/src/skills/test/publicExports.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { loadSkill as loadBrowserSkillFromRoot } from '../../index'
+import { loadSkill as loadNodeSkillFromEntry } from '../../node'
+import { loadSkill as loadBrowserSkill } from '../loader'
+import { loadSkill as loadNodeSkill } from '../loader/node'
+
+describe('skill public exports', () => {
+  it('exports environment-specific loaders from the root and node entrypoints', () => {
+    expect(loadBrowserSkillFromRoot).toBe(loadBrowserSkill)
+    expect(loadNodeSkillFromEntry).toBe(loadNodeSkill)
+  })
+})

packages/kit/src/skills/test/selectionCapability.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createSkillSelectionRuntimeTools } from '../capabilities/selection'
+
+const candidates = [{ name: 'weather', description: 'Weather skill' }]
+
+describe('skill selection capability', () => {
+  it.each([
+    [-1, 0],
+    [0, 0],
+    [0.9, 0],
+    [1.9, 1],
+    [2, 1],
+    [Number.NaN, 1],
+    [Number.POSITIVE_INFINITY, 1],
+  ])('normalizes maxSelectedSkills value %s to %s', (maxSelectedSkills, expectedMaxSelectedSkills) => {
+    const [runtimeTool] = createSkillSelectionRuntimeTools(candidates, { maxSelectedSkills })
+    const parameters = runtimeTool.tool.function.parameters as {
+      properties: { skillNames: { maxItems: number } }
+    }
+
+    expect(parameters.properties.skillNames.maxItems).toBe(expectedMaxSelectedSkills)
+  })
+
+  it('resolves only the first concurrent valid select_skills call', async () => {
+    let releaseSelection: (() => void) | undefined
+    const selectionBlocked = new Promise<void>((resolve) => {
+      releaseSelection = resolve
+    })
+    const resolveSelection = vi.fn(async () => {
+      await selectionBlocked
+      return { enabledSkillNames: ['weather'] }
+    })
+    const [runtimeTool] = createSkillSelectionRuntimeTools(candidates, { resolveSelection })
+
+    const firstResult = runtimeTool.handler(createToolCall(['weather'], 'call-1'), {} as never)
+    const secondResult = runtimeTool.handler(createToolCall(['weather'], 'call-2'), {} as never)
+
+    await Promise.resolve()
+    expect(resolveSelection).toHaveBeenCalledTimes(1)
+
+    releaseSelection?.()
+    await expect(firstResult).resolves.toMatchObject({ enabledSkillNames: ['weather'] })
+    await expect(secondResult).resolves.toEqual({ error: 'skill_selection_already_resolved' })
+  })
+})
+
+const createToolCall = (skillNames: string[], id: string) => ({
+  id,
+  type: 'function' as const,
+  function: {
+    name: 'select_skills',
+    arguments: JSON.stringify({ skillNames }),
+  },
+})

packages/kit/src/skills/test/skillPlugin.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { createNativeMessageAdapter } from '../../message/adapters/native'
 import { createMessageEngine } from '../../message/core/engine'
 import { getSkillRequestContext, lengthPlugin, skillPlugin, thinkingPlugin, toolPlugin } from '../../message/plugins'
+import type { SkillPluginOptions } from '../../message/plugins'
 import type { CreateMessageEngineOptions, MessageRequestBody, ResponseProvider } from '../../message/types'
 import { mockResponseProvider } from '../../message/test/mockResponseProvider'
 import type { SkillDefinition } from '../types'
@@ -18,7 +19,25 @@ const weatherSkill: SkillDefinition = {
   instructions: 'Use wttr.in for weather requests.',
 }
 
+const skillPluginOptionTypeChecks = [
+  { selection: { mode: 'none' } } satisfies SkillPluginOptions,
+  { selection: { mode: 'manual', skills: [weatherSkill] } } satisfies SkillPluginOptions,
+  {
+    selection: { mode: 'manual', skillNames: ['weather'] },
+    getSkillByName: async () => weatherSkill,
+  } satisfies SkillPluginOptions,
+  {
+    selection: { mode: 'auto' },
+    getSkillCandidates: async () => [weatherSkill],
+    getSkillByName: async () => weatherSkill,
+  } satisfies SkillPluginOptions,
+]
+
 describe('skillPlugin', () => {
+  it('accepts selection-specific default option types', () => {
+    expect(skillPluginOptionTypeChecks).toHaveLength(4)
+  })
+
   it('uses manual skills for instructions and runtime tools', async () => {
     const vueSkill: SkillDefinition = {
       name: 'vue-best-practices',
@@ -274,6 +293,63 @@ describe('skillPlugin', () => {
     )
   })
 
+  it('rejects mismatched resolver results and deduplicates enabled skills', async () => {
+    const onSkillsResolved = vi.fn()
+    const engine = createTestMessageEngine({
+      plugins: [
+        ...silentDefaultPlugins,
+        skillPlugin({
+          selection: {
+            mode: 'manual',
+            skillNames: ['weather', 'weather-alias'],
+          },
+          getSkillByName: async () => weatherSkill,
+          onSkillsResolved,
+        }),
+      ],
+      responseProvider: mockResponseProvider('ok'),
+    })
+
+    await engine.sendMessage('weather in London')
+
+    expect(onSkillsResolved).toHaveBeenCalledWith(
+      expect.objectContaining({
+        skills: [weatherSkill],
+        skillNames: ['weather'],
+        requestedSkillNames: ['weather', 'weather-alias'],
+        unresolvedSkillNames: ['weather-alias'],
+      }),
+      expect.any(Object),
+    )
+  })
+
+  it('deduplicates inline manual skills by name', async () => {
+    const onSkillsResolved = vi.fn()
+    const engine = createTestMessageEngine({
+      plugins: [
+        ...silentDefaultPlugins,
+        skillPlugin({
+          selection: {
+            mode: 'manual',
+            skills: [weatherSkill, weatherSkill],
+          },
+          onSkillsResolved,
+        }),
+      ],
+      responseProvider: mockResponseProvider('ok'),
+    })
+
+    await engine.sendMessage('weather in London')
+
+    expect(onSkillsResolved).toHaveBeenCalledWith(
+      expect.objectContaining({
+        skills: [weatherSkill],
+        skillNames: ['weather'],
+      }),
+      expect.any(Object),
+    )
+  })
+
   it('selects auto skills before injecting selected skill instructions', async () => {
     const instructionContents: string[] = []
     const getSkillByName = vi.fn(async (name: string) => (name === weatherSkill.name ? weatherSkill : undefined))
@@ -410,6 +486,26 @@ describe('skillPlugin', () => {
     )
   })
 
+  it('fails before requesting when auto mode is missing toolPlugin', async () => {
+    const responseProvider = vi.fn(mockResponseProvider('unexpected'))
+    const engine = createTestMessageEngine({
+      plugins: [
+        ...silentDefaultPlugins,
+        skillPlugin({
+          selection: { mode: 'auto' },
+          getSkillCandidates: async () => [weatherSkill],
+          getSkillByName: async () => weatherSkill,
+        }),
+      ],
+      responseProvider,
+    })
+
+    await expect(engine.sendMessage('weather in London')).rejects.toThrow(
+      'skillPlugin auto mode requires an enabled toolPlugin',
+    )
+    expect(responseProvider).not.toHaveBeenCalled()
+  })
+
   it('does not inject instructions or tools when selection is none', async () => {
     const responseProvider = vi.fn(mockResponseProvider('ok'))
     const onInstructionsResolved = vi.fn()