/**
 * AgentSkills plugin for integrating Agent Skills into Strands agents.
 *
 * This module provides the AgentSkills class that implements the Plugin
 * interface to add Agent Skills support. The plugin registers a tool for
 * activating skills and injects skill metadata into the system prompt.
 */
import { Skill } from './skill.js';
import type { Plugin } from '../../plugins/plugin.js';
import type { LocalAgent } from '../../types/agent.js';
import type { Tool } from '../../tools/tool.js';
/** A single skill source: filesystem path string, HTTPS URL string, or Skill instance. */
export type SkillSource = string | Skill;
/** Configuration for the AgentSkills plugin. */
export interface AgentSkillsConfig {
    /**
     * One or more skill sources. Each element can be:
     * - A `Skill` instance
     * - A path to a skill directory (containing SKILL.md)
     * - A path to a parent directory (containing skill subdirectories)
     * - An `https://` URL pointing directly to raw SKILL.md content
     */
    skills: SkillSource[];
    /** Maximum number of resource files to list in skill responses. Defaults to 20. */
    maxResourceFiles?: number | undefined;
    /** If true, throw on skill validation issues. If false (default), warn and load anyway. */
    strict?: boolean | undefined;
    /** Custom key for storing plugin state in `agent.appState`. Defaults to `'agent_skills'`. */
    stateKey?: string | undefined;
}
/**
 * Plugin that integrates Agent Skills into a Strands agent.
 *
 * Provides:
 * 1. A `skills` tool that allows the agent to activate skills on demand
 * 2. System prompt injection of available skill metadata before each invocation
 * 3. Session persistence of activated skill state via `agent.appState`
 *
 * Skills can be provided as filesystem paths (to individual skill directories or
 * parent directories containing multiple skills), HTTPS URLs pointing to raw
 * SKILL.md content, or as pre-built `Skill` instances.
 *
 * @example
 * ```typescript
 * import { Agent } from '@strands-agents/sdk'
 * import { Skill, AgentSkills } from '@strands-agents/sdk/vended-plugins/skills'
 *
 * // Load from filesystem
 * const plugin = new AgentSkills({
 *   skills: ['./skills/pdf-processing', './skills/'],
 * })
 *
 * // Or provide Skill instances directly
 * const skill = new Skill({ name: 'my-skill', description: 'A custom skill', instructions: 'Do the thing' })
 * const plugin = new AgentSkills({ skills: [skill] })
 *
 * const agent = new Agent({ model, plugins: [plugin] })
 * ```
 */
export declare class AgentSkills implements Plugin {
    readonly name = "strands:agent-skills";
    private _skills;
    /**
     * Filesystem path sources. Loaded at initAgent (not construction) so they read from
     * the agent's sandbox — host or container — exactly once, from the correct filesystem.
     */
    private _skillPaths;
    private readonly _maxResourceFiles;
    /** When true, skill validation errors throw instead of logging warnings. */
    private readonly _strict;
    private readonly _stateKey;
    /** Resolves when all async skill sources (URLs) have been loaded. */
    private _ready;
    private _agentSkills;
    constructor(config: AgentSkillsConfig);
    /**
     * Initialize the plugin with the agent instance.
     *
     * Waits for any async skill sources (e.g. URLs) to finish loading, then
     * registers a BeforeInvocationEvent hook that injects skill metadata
     * into the system prompt before each invocation.
     */
    initAgent(agent: LocalAgent): Promise<void>;
    /**
     * Returns the skills activation tool for auto-registration with the agent.
     */
    getTools(): Tool[];
    /**
     * Get the list of available skills. When called with an agent, returns that agent's
     * full skill set (base + path-loaded from its sandbox). Without an agent, returns
     * the base skills only (Skill instances and URLs).
     */
    getAvailableSkills(agent?: LocalAgent): Promise<readonly Skill[]>;
    /**
     * Replace all available skills.
     *
     * Each element can be a `Skill` instance, a path to a skill directory
     * (containing SKILL.md), a path to a parent directory containing skill
     * subdirectories, or an `https://` URL pointing directly to raw SKILL.md
     * content.
     *
     * Note: this does not persist state or deactivate skills on any agent.
     * Active skill state is managed per-agent and will be reconciled on the
     * next tool call or invocation.
     */
    setAvailableSkills(skills: SkillSource[]): void;
    /**
     * Get the list of skills activated by the given agent.
     * Returns skill names in activation order (most recent last).
     */
    getActivatedSkills(agent: LocalAgent): readonly string[];
    /**
     * Resolve a list of skill sources into Skill instances.
     *
     * Each source can be a Skill instance, a path to a skill directory,
     * a path to a parent directory containing multiple skills, or an
     * HTTPS URL pointing to a SKILL.md file.
     *
     * Skill instances are resolved immediately into the returned map. Async sources
     * (URLs) are resolved in the background; the returned `ready` promise resolves when
     * all URL fetches have completed. Filesystem paths are returned in `skillPaths` to be
     * loaded at initAgent, where they read from the agent's sandbox.
     */
    private _resolveSkills;
    /**
     * Load the deferred path sources through the sandbox, mirroring `Skill.fromFile`/
     * `Skill.fromDirectory`: a path may be a SKILL.md file, a skill directory, or a parent
     * directory of skill subdirectories. Per-path failures are logged and skipped.
     */
    private _loadSkillPaths;
    /**
     * Create the skills activation tool using the tool() factory with Zod schema.
     */
    private _createSkillsTool;
    /**
     * Handle skill activation from the tool callback.
     */
    private _activateSkill;
    /**
     * Record a skill activation in agent state.
     * Maintains an ordered list of activated skill names (most recent last), without duplicates.
     */
    private _trackActivatedSkill;
    /**
     * Get a field from the plugin's per-agent state dict.
     */
    private _getStateField;
    /**
     * Set a single field in the plugin's per-agent state dict.
     */
    private _setStateField;
    /**
     * Inject skill metadata into the agent's system prompt.
     *
     * Removes the previously injected XML block (if any) via exact string
     * replacement, then appends a fresh one. Uses agent state to track the
     * injected XML per-agent, so a single plugin instance can be shared
     * across multiple agents safely.
     */
    private _injectSkillsXml;
    /**
     * Generate the XML block listing available skills for the system prompt.
     *
     * @example Output with skills:
     * ```xml
     * <available_skills>
     * <skill>
     * <name>pdf-processing</name>
     * <description>Extract text and tables from PDF files</description>
     * <location>/path/to/pdf-processing/SKILL.md</location>
     * </skill>
     * </available_skills>
     * ```
     */
    private _generateSkillsXml;
    /**
     * Format the tool response when a skill is activated.
     *
     * Includes the full instructions along with relevant metadata fields
     * and a listing of available resource files.
     */
    private _formatSkillResponse;
    /**
     * List resource files in a skill's optional directories.
     *
     * Scans `scripts/`, `references/`, and `assets/` subdirectories for files,
     * returning relative paths. Results are capped at maxResourceFiles.
     */
    private _listSkillResources;
}
//# sourceMappingURL=agent-skills.d.ts.map