@lleverage-ai/agent-sdk 0.0.1

package/dist/tools/skills.d.ts

@@ -0,0 +1,354 @@
+/**
+ * Skill tool for progressive disclosure of capabilities.
+ *
+ * The skill tool allows agents to load skills (tools + prompts) on-demand
+ * based on conversation context. This keeps the initial context small and
+ * focused, expanding capabilities only as needed.
+ *
+ * @packageDocumentation
+ */
+import type { ToolSet } from "ai";
+import type { MCPManager } from "../mcp/manager.js";
+/**
+ * Definition of a loadable skill for progressive disclosure.
+ *
+ * Skills bundle tools and prompts that are loaded dynamically by the agent.
+ * This extends the basic `SkillDefinition` with support for MCP tools and
+ * dependencies, enabling on-demand capability expansion.
+ *
+ * @example
+ * ```typescript
+ * const gitSkill: LoadableSkillDefinition = {
+ *   name: "git",
+ *   description: "Git version control operations",
+ *   tools: {
+ *     git_status: tool({ ... }),
+ *     git_commit: tool({ ... }),
+ *   },
+ *   prompt: "You now have access to Git tools. Use them to manage version control.",
+ * };
+ * ```
+ *
+ * @category Tools
+ */
+export interface LoadableSkillDefinition {
+    /** Unique identifier for the skill */
+    name: string;
+    /** Description for the agent to decide when to invoke this skill */
+    description: string;
+    /** Tools this skill provides (inline tools) */
+    tools: ToolSet;
+    /**
+     * MCP tool names to load when this skill is activated.
+     *
+     * These are tool names from the MCPManager (e.g., "mcp__github__list_issues").
+     * They will be loaded via MCPManager.loadTools() when the skill is activated.
+     *
+     * @example
+     * ```typescript
+     * const githubSkill: LoadableSkillDefinition = {
+     *   name: "github",
+     *   description: "GitHub operations",
+     *   tools: {},  // No inline tools
+     *   mcpTools: [
+     *     "mcp__github__list_issues",
+     *     "mcp__github__create_pr",
+     *   ],
+     *   prompt: "You can now work with GitHub issues and PRs.",
+     * };
+     * ```
+     */
+    mcpTools?: string[];
+    /**
+     * Prompt to inject when the skill is loaded.
+     * Can be a string or a function that receives optional arguments.
+     */
+    prompt: string | ((args?: string) => string);
+    /**
+     * Optional skills this skill depends on.
+     * Dependencies are loaded first when this skill is loaded.
+     */
+    dependencies?: string[];
+}
+/**
+ * Result from attempting to load a skill.
+ *
+ * @category Tools
+ */
+export interface SkillLoadResult {
+    /** Whether the skill was loaded successfully */
+    success: boolean;
+    /** Tools provided by the loaded skill (empty if failed) */
+    tools: ToolSet;
+    /** Prompt from the loaded skill (empty if failed) */
+    prompt: string;
+    /** Error message if loading failed */
+    error?: string;
+    /** Skills that were loaded as dependencies */
+    loadedDependencies?: string[];
+    /** MCP tools that were loaded (via MCPManager) */
+    loadedMcpTools?: string[];
+    /** MCP tools that were requested but not found */
+    notFoundMcpTools?: string[];
+}
+/**
+ * Options for creating a skill registry.
+ *
+ * @category Tools
+ */
+export interface SkillRegistryOptions {
+    /**
+     * Initial skills to register.
+     */
+    skills?: LoadableSkillDefinition[];
+    /**
+     * MCP manager for loading MCP tools referenced by skills.
+     *
+     * When provided, skills can specify `mcpTools` to load MCP tools
+     * when the skill is activated.
+     */
+    mcpManager?: MCPManager;
+    /**
+     * Callback when a skill is loaded.
+     */
+    onSkillLoaded?: (skillName: string, result: SkillLoadResult) => void;
+}
+/**
+ * Registry for managing loadable skills.
+ *
+ * The registry tracks available skills and which ones have been loaded.
+ * Skills are loaded on-demand by the agent using the skill tool.
+ *
+ * @example
+ * ```typescript
+ * const registry = new SkillRegistry({
+ *   skills: [gitSkill, dockerSkill],
+ * });
+ *
+ * // Register more skills later
+ * registry.register(kubernetesSkill);
+ *
+ * // Check available skills
+ * const available = registry.listAvailable();
+ *
+ * // Load a skill
+ * const result = registry.load("git");
+ * ```
+ *
+ * @category Tools
+ */
+export declare class SkillRegistry {
+    /** All registered skills */
+    private skills;
+    /** Currently loaded skills */
+    private loadedSkills;
+    /** Callback for skill load events */
+    private onSkillLoaded?;
+    /** MCP manager for loading MCP tools */
+    private mcpManager?;
+    /**
+     * Creates a new skill registry.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: SkillRegistryOptions);
+    /**
+     * Register a skill with the registry.
+     *
+     * @param skill - The skill definition to register
+     * @throws Error if a skill with the same name is already registered
+     *
+     * @example
+     * ```typescript
+     * registry.register({
+     *   name: "aws",
+     *   description: "AWS cloud operations",
+     *   tools: { ... },
+     *   prompt: "You now have access to AWS tools.",
+     * });
+     * ```
+     */
+    register(skill: LoadableSkillDefinition): void;
+    /**
+     * Unregister a skill from the registry.
+     *
+     * @param name - The name of the skill to unregister
+     * @returns True if the skill was found and removed
+     */
+    unregister(name: string): boolean;
+    /**
+     * Check if a skill is registered.
+     *
+     * @param name - The name of the skill to check
+     * @returns True if the skill is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Check if a skill is currently loaded.
+     *
+     * @param name - The name of the skill to check
+     * @returns True if the skill is loaded
+     */
+    isLoaded(name: string): boolean;
+    /**
+     * Get a registered skill definition.
+     *
+     * @param name - The name of the skill
+     * @returns The skill definition or undefined if not found
+     */
+    get(name: string): LoadableSkillDefinition | undefined;
+    /**
+     * Load a skill, making its tools and prompt available.
+     *
+     * This method handles dependencies, loading them first if specified.
+     * Already-loaded skills are skipped (no duplicate loading).
+     *
+     * @param name - The name of the skill to load
+     * @param args - Optional arguments to pass to the skill's prompt function
+     * @returns The load result with tools, prompt, and status
+     *
+     * @example
+     * ```typescript
+     * const result = registry.load("git");
+     * if (result.success) {
+     *   // Inject result.tools into agent
+     *   // Inject result.prompt into context
+     * }
+     * ```
+     */
+    load(name: string, args?: string): SkillLoadResult;
+    /**
+     * List skills that are available but not yet loaded.
+     *
+     * @returns Array of skill summaries (name and description)
+     */
+    listAvailable(): Array<{
+        name: string;
+        description: string;
+    }>;
+    /**
+     * List all loaded skills.
+     *
+     * @returns Array of loaded skill names
+     */
+    listLoaded(): string[];
+    /**
+     * List all registered skills (loaded and available).
+     *
+     * @returns Array of all skill summaries
+     */
+    listAll(): Array<{
+        name: string;
+        description: string;
+        loaded: boolean;
+    }>;
+    /**
+     * Reset the registry, marking all skills as unloaded.
+     *
+     * This does not unregister skills, only resets the loaded state.
+     */
+    reset(): void;
+    /**
+     * Get the number of registered skills.
+     */
+    get size(): number;
+    /**
+     * Get the number of loaded skills.
+     */
+    get loadedCount(): number;
+}
+/**
+ * Options for creating the skill loading tool.
+ *
+ * @category Tools
+ */
+export interface SkillToolOptions {
+    /** The skill registry to use */
+    registry: SkillRegistry;
+    /**
+     * Custom name for the tool.
+     * @defaultValue "load_skill"
+     */
+    name?: string;
+    /**
+     * Custom description prefix for the tool.
+     * The list of available skills is appended automatically.
+     */
+    descriptionPrefix?: string;
+}
+/**
+ * Creates a tool that allows agents to load skills on-demand.
+ *
+ * The tool's description dynamically lists available (not yet loaded) skills,
+ * so the agent can decide which skill to load based on the conversation.
+ *
+ * @param options - Configuration options
+ * @returns An AI SDK compatible tool for loading skills
+ *
+ * @example
+ * ```typescript
+ * import { createSkillTool, SkillRegistry } from "@lleverage-ai/agent-sdk";
+ *
+ * const registry = new SkillRegistry({
+ *   skills: [gitSkill, dockerSkill],
+ * });
+ *
+ * const skillTool = createSkillTool({ registry });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   tools: { load_skill: skillTool },
+ * });
+ *
+ * // Agent can now invoke load_skill to gain new capabilities
+ * ```
+ *
+ * @category Tools
+ */
+export declare function createSkillTool(options: SkillToolOptions): import("ai").Tool<{
+    skill_name: string;
+    args?: string | undefined;
+}, Record<string, unknown>>;
+/**
+ * Creates a new skill registry with the given skills.
+ *
+ * This is a convenience function for creating a SkillRegistry instance.
+ *
+ * @param skills - Initial skills to register
+ * @param options - Additional options
+ * @returns A new SkillRegistry instance
+ *
+ * @example
+ * ```typescript
+ * const registry = createSkillRegistry([gitSkill, dockerSkill]);
+ * ```
+ *
+ * @category Tools
+ */
+export declare function createSkillRegistry(skills: LoadableSkillDefinition[], options?: Omit<SkillRegistryOptions, "skills">): SkillRegistry;
+/**
+ * Creates a skill definition.
+ *
+ * This is a helper function for creating LoadableSkillDefinition objects
+ * with proper typing.
+ *
+ * @param options - Skill configuration
+ * @returns A LoadableSkillDefinition object
+ *
+ * @example
+ * ```typescript
+ * const gitSkill = defineLoadableSkill({
+ *   name: "git",
+ *   description: "Git version control operations",
+ *   tools: {
+ *     git_status: tool({ ... }),
+ *     git_commit: tool({ ... }),
+ *   },
+ *   prompt: "You now have access to Git tools.",
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export declare function defineLoadableSkill(options: LoadableSkillDefinition): LoadableSkillDefinition;
+//# sourceMappingURL=skills.d.ts.map

package/dist/tools/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/tools/skills.ts"],"names":[],"mappings":"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"}