@defai.digital/ability-domain 13.0.3

package/src/manager.ts

@@ -0,0 +1,184 @@
+/**
+ * Ability Manager
+ *
+ * Coordinates ability loading and injection into agent contexts.
+ */
+
+import type { Ability, AbilityInjectionResult } from '@defai.digital/contracts';
+import type {
+  AbilityRegistry,
+  AbilityManager,
+  AbilityInjectionOptions,
+  AbilityDomainConfig,
+} from './types.js';
+import { DEFAULT_ABILITY_DOMAIN_CONFIG } from './types.js';
+
+/**
+ * Default ability manager implementation
+ */
+export class DefaultAbilityManager implements AbilityManager {
+  constructor(
+    private readonly registry: AbilityRegistry,
+    private readonly config: AbilityDomainConfig = DEFAULT_ABILITY_DOMAIN_CONFIG
+  ) {}
+
+  /**
+   * Get abilities for an agent based on task keywords
+   */
+  async getAbilitiesForTask(
+    agentId: string,
+    task: string,
+    coreAbilities?: string[],
+    maxAbilities?: number
+  ): Promise<Ability[]> {
+    const max = maxAbilities ?? this.config.maxAbilitiesPerAgent;
+    const taskLower = task.toLowerCase();
+    const taskWords = this.extractKeywords(taskLower);
+
+    // Get all applicable abilities
+    const applicable = await this.getApplicableAbilities(agentId);
+
+    // Score abilities by relevance to task
+    const scored = applicable.map((ability) => ({
+      ability,
+      score: this.scoreAbility(ability, taskWords, coreAbilities ?? []),
+    }));
+
+    // Sort by score descending
+    scored.sort((a, b) => b.score - a.score);
+
+    // Return top N abilities
+    return scored.slice(0, max).map((s) => s.ability);
+  }
+
+  /**
+   * Inject abilities into agent context
+   */
+  async injectAbilities(
+    agentId: string,
+    task: string,
+    coreAbilities?: string[],
+    options?: AbilityInjectionOptions
+  ): Promise<AbilityInjectionResult> {
+    const maxAbilities = options?.maxAbilities ?? this.config.maxAbilitiesPerAgent;
+    const maxTokens = options?.maxTokens ?? this.config.maxTokensPerInjection;
+
+    // Get relevant abilities
+    const abilities = await this.getAbilitiesForTask(
+      agentId,
+      task,
+      coreAbilities,
+      maxAbilities
+    );
+
+    // Build combined content
+    const injectedAbilities: string[] = [];
+    const contentParts: string[] = [];
+    let currentTokens = 0;
+    let truncated = false;
+
+    for (const ability of abilities) {
+      const abilityTokens = this.estimateTokens(ability.content);
+
+      if (currentTokens + abilityTokens > maxTokens) {
+        truncated = true;
+        break;
+      }
+
+      const header = options?.includeMetadata
+        ? `## ${ability.displayName ?? ability.abilityId}\n\n`
+        : '';
+
+      contentParts.push(header + ability.content);
+      injectedAbilities.push(ability.abilityId);
+      currentTokens += abilityTokens;
+    }
+
+    return {
+      agentId,
+      injectedAbilities,
+      combinedContent: contentParts.join('\n\n---\n\n'),
+      tokenCount: currentTokens,
+      truncated,
+    };
+  }
+
+  /**
+   * Get all abilities applicable to an agent
+   */
+  async getApplicableAbilities(agentId: string): Promise<Ability[]> {
+    return this.registry.list({
+      enabled: true,
+      applicableTo: agentId,
+    });
+  }
+
+  /**
+   * Score an ability's relevance to a task
+   */
+  private scoreAbility(
+    ability: Ability,
+    taskWords: string[],
+    coreAbilities: string[]
+  ): number {
+    let score = 0;
+
+    // Core ability bonus
+    if (coreAbilities.includes(ability.abilityId)) {
+      score += 100;
+    }
+
+    // Tag matches
+    for (const tag of ability.tags ?? []) {
+      if (taskWords.includes(tag.toLowerCase())) {
+        score += 10;
+      }
+    }
+
+    // Category match
+    if (ability.category && taskWords.includes(ability.category.toLowerCase())) {
+      score += 15;
+    }
+
+    // Content keyword matches (limited)
+    const contentWords = this.extractKeywords(ability.content.toLowerCase());
+    const contentMatches = taskWords.filter((w) => contentWords.includes(w)).length;
+    score += Math.min(contentMatches * 2, 20);
+
+    // Priority bonus
+    score += (ability.priority ?? 50) / 10;
+
+    return score;
+  }
+
+  /**
+   * Extract keywords from text
+   */
+  private extractKeywords(text: string): string[] {
+    return text
+      .split(/[\s\-_,./]+/)
+      .filter((w) => w.length > 2)
+      .map((w) => w.toLowerCase());
+  }
+
+  /**
+   * Estimate token count (rough approximation)
+   */
+  private estimateTokens(text: string): number {
+    // Rough estimate: ~4 characters per token
+    return Math.ceil(text.length / 4);
+  }
+}
+
+/**
+ * Creates an ability manager
+ */
+export function createAbilityManager(
+  registry: AbilityRegistry,
+  config?: Partial<AbilityDomainConfig>
+): AbilityManager {
+  return new DefaultAbilityManager(registry, {
+    ...DEFAULT_ABILITY_DOMAIN_CONFIG,
+    ...config,
+  });
+}

package/src/registry.ts

@@ -0,0 +1,84 @@
+/**
+ * Ability Registry
+ *
+ * In-memory storage for abilities with filtering support.
+ */
+
+import type { Ability } from '@defai.digital/contracts';
+import type { AbilityRegistry, AbilityFilter } from './types.js';
+
+/**
+ * In-memory ability registry implementation
+ */
+export class InMemoryAbilityRegistry implements AbilityRegistry {
+  private abilities = new Map<string, Ability>();
+
+  async register(ability: Ability): Promise<void> {
+    this.abilities.set(ability.abilityId, ability);
+  }
+
+  async get(abilityId: string): Promise<Ability | undefined> {
+    return this.abilities.get(abilityId);
+  }
+
+  async list(filter?: AbilityFilter): Promise<Ability[]> {
+    let results = Array.from(this.abilities.values());
+
+    if (filter) {
+      if (filter.category !== undefined) {
+        results = results.filter((a) => a.category === filter.category);
+      }
+
+      if (filter.tags !== undefined && filter.tags.length > 0) {
+        results = results.filter((a) =>
+          filter.tags!.some((tag) => a.tags?.includes(tag))
+        );
+      }
+
+      if (filter.enabled !== undefined) {
+        results = results.filter((a) => a.enabled === filter.enabled);
+      }
+
+      if (filter.applicableTo !== undefined) {
+        results = results.filter((a) => {
+          // Check if excluded
+          if (a.excludeFrom?.includes(filter.applicableTo!)) {
+            return false;
+          }
+          // Check if applicable (empty means all)
+          if (!a.applicableTo || a.applicableTo.length === 0) {
+            return true;
+          }
+          return (
+            a.applicableTo.includes('*') ||
+            a.applicableTo.includes(filter.applicableTo!)
+          );
+        });
+      }
+    }
+
+    // Sort by priority (higher first)
+    results.sort((a, b) => (b.priority ?? 50) - (a.priority ?? 50));
+
+    return results;
+  }
+
+  async remove(abilityId: string): Promise<void> {
+    this.abilities.delete(abilityId);
+  }
+
+  async exists(abilityId: string): Promise<boolean> {
+    return this.abilities.has(abilityId);
+  }
+
+  async clear(): Promise<void> {
+    this.abilities.clear();
+  }
+}
+
+/**
+ * Creates an in-memory ability registry
+ */
+export function createAbilityRegistry(): AbilityRegistry {
+  return new InMemoryAbilityRegistry();
+}

package/src/types.ts

@@ -0,0 +1,149 @@
+/**
+ * Ability Domain Types
+ */
+
+import {
+  type Ability,
+  type AbilityInjectionResult,
+  LIMIT_ABILITY_TOKENS,
+  LIMIT_ABILITIES_INJECT,
+} from '@defai.digital/contracts';
+
+/**
+ * Ability registry interface
+ */
+export interface AbilityRegistry {
+  /**
+   * Register an ability
+   */
+  register(ability: Ability): Promise<void>;
+
+  /**
+   * Get an ability by ID
+   */
+  get(abilityId: string): Promise<Ability | undefined>;
+
+  /**
+   * List all abilities
+   */
+  list(filter?: AbilityFilter): Promise<Ability[]>;
+
+  /**
+   * Remove an ability
+   */
+  remove(abilityId: string): Promise<void>;
+
+  /**
+   * Check if ability exists
+   */
+  exists(abilityId: string): Promise<boolean>;
+
+  /**
+   * Clear all abilities
+   */
+  clear(): Promise<void>;
+}
+
+/**
+ * Filter for listing abilities
+ */
+export interface AbilityFilter {
+  category?: string;
+  tags?: string[];
+  enabled?: boolean;
+  applicableTo?: string;
+}
+
+/**
+ * Ability loader interface
+ */
+export interface AbilityLoader {
+  /**
+   * Load an ability by ID
+   */
+  load(abilityId: string): Promise<Ability | undefined>;
+
+  /**
+   * Load all abilities from the source
+   */
+  loadAll(): Promise<Ability[]>;
+
+  /**
+   * Check if ability exists
+   */
+  exists(abilityId: string): Promise<boolean>;
+
+  /**
+   * Reload abilities from source
+   */
+  reload(): Promise<void>;
+}
+
+/**
+ * Ability loader configuration
+ */
+export interface AbilityLoaderConfig {
+  /** Directory to load abilities from */
+  abilitiesDir: string;
+  /** File extensions to load */
+  extensions?: string[];
+}
+
+/**
+ * Ability manager interface - coordinates loading and injection
+ */
+export interface AbilityManager {
+  /**
+   * Get abilities for an agent based on task
+   */
+  getAbilitiesForTask(
+    agentId: string,
+    task: string,
+    coreAbilities?: string[],
+    maxAbilities?: number
+  ): Promise<Ability[]>;
+
+  /**
+   * Inject abilities into agent context
+   */
+  injectAbilities(
+    agentId: string,
+    task: string,
+    coreAbilities?: string[],
+    options?: AbilityInjectionOptions
+  ): Promise<AbilityInjectionResult>;
+
+  /**
+   * Get all abilities applicable to an agent
+   */
+  getApplicableAbilities(agentId: string): Promise<Ability[]>;
+}
+
+/**
+ * Options for ability injection
+ */
+export interface AbilityInjectionOptions {
+  maxAbilities?: number;
+  maxTokens?: number;
+  includeMetadata?: boolean;
+}
+
+/**
+ * Ability domain configuration
+ */
+export interface AbilityDomainConfig {
+  abilitiesDir: string;
+  maxAbilitiesPerAgent: number;
+  maxTokensPerInjection: number;
+  cacheEnabled: boolean;
+}
+
+/**
+ * Default ability domain configuration
+ */
+export const DEFAULT_ABILITY_DOMAIN_CONFIG: AbilityDomainConfig = {
+  abilitiesDir: 'examples/abilities',
+  maxAbilitiesPerAgent: LIMIT_ABILITIES_INJECT,
+  maxTokensPerInjection: LIMIT_ABILITY_TOKENS,
+  cacheEnabled: true,
+};