1
>
/*---------------------------------------------------------------------------------------------
promptsService.ts
2
>
* Copyright (c) Microsoft Corporation. All rights reserved.
3
>
* Licensed under the MIT License. See License.txt in the project root for license information.
4
>
*--------------------------------------------------------------------------------------------*/
5
>
6
>
import { CancellationToken } from '../../../../../../base/common/cancellation.js';
7
>
import { Event } from '../../../../../../base/common/event.js';
8
>
import { IDisposable } from '../../../../../../base/common/lifecycle.js';
9
>
import { URI } from '../../../../../../base/common/uri.js';
10
>
import { ITextModel } from '../../../../../../editor/common/model.js';
11
>
import { ExtensionIdentifier, IExtensionDescription } from '../../../../../../platform/extensions/common/extensions.js';
12
>
import { createDecorator } from '../../../../../../platform/instantiation/common/instantiation.js';
13
>
import { IChatModeInstructions, IVariableReference } from '../../chatModes.js';
14
>
import { PromptFileSource, PromptsType, Target } from '../promptTypes.js';
15
>
import { IHandOff, ParsedPromptFile } from '../promptFileParser.js';
16
>
import { ResourceSet } from '../../../../../../base/common/map.js';
17
>
import { IResolvedPromptSourceFolder } from '../config/promptFileLocations.js';
18
>
import { ChatRequestHooks } from '../hookSchema.js';
19
>
import { isEqual } from '../../../../../../base/common/resources.js';
20
>
21
>
/**
22
>
* A single structured debug detail entry from the instructions context computer.
23
>
*/
24
>
export interface InstructionsCollectionDebugEntry {
25
>
readonly category: 'applying' | 'skipped' | 'referenced' | 'skill' | 'custom-agent' | 'hook';
26
>
readonly name: string;
27
>
readonly uri?: URI;
28
>
readonly reason?: string;
29
>
}
30
>
31
>
export type InstructionsCollectionEvent = {
32
>
applyingInstructionsCount: number;
33
>
referencedInstructionsCount: number;
34
>
agentInstructionsCount: number;
35
>
listedInstructionsCount: number;
36
>
totalInstructionsCount: number;
37
>
claudeRulesCount: number;
38
>
claudeMdCount: number;
39
>
claudeAgentsCount: number;
40
>
};
41
>
42
>
/**
43
>
* Debug-only information collected alongside {@link InstructionsCollectionEvent}.
44
>
* This data is used for debug logging and is not sent as telemetry.
45
>
*/
46
>
export type InstructionsCollectionDebugInfo = {
47
>
/** Per-file detail entries for debug logging. */
48
>
debugDetails: InstructionsCollectionDebugEntry[];
49
>
/** Total wall-clock time of the collect() call in milliseconds. */
50
>
durationInMillis: number;
51
>
};
52
>
53
>
export function newInstructionsCollectionEvent(): InstructionsCollectionEvent {
54
return { applyingInstructionsCount: 0, referencedInstructionsCount: 0, agentInstructionsCount: 0, listedInstructionsCount: 0, totalInstructionsCount: 0, claudeRulesCount: 0, claudeMdCount: 0, claudeAgentsCount: 0 };
55
}
57
>
export function newInstructionsCollectionDebugInfo(): InstructionsCollectionDebugInfo {
58
return { debugDetails: [], durationInMillis: 0 };
59
}
61
>
/**
62
>
* Activation events for prompt file providers.
63
>
*/
64
>
export const CUSTOM_AGENT_PROVIDER_ACTIVATION_EVENT = 'onCustomAgentProvider';
65
>
export const INSTRUCTIONS_PROVIDER_ACTIVATION_EVENT = 'onInstructionsProvider';
66
>
export const PROMPT_FILE_PROVIDER_ACTIVATION_EVENT = 'onPromptFileProvider';
67
>
export const SKILL_PROVIDER_ACTIVATION_EVENT = 'onSkillProvider';
68
>
69
>
/**
70
>
* Context for querying prompt files.
71
>
*/
72
>
export interface IPromptFileContext { }
73
>
74
>
/**
75
>
* Represents a prompt file resource from an external provider.
76
>
*/
77
>
export interface IPromptFileResource {
78
>
/**
79
>
* The URI to the agent or prompt resource file.
80
>
*/
81
>
readonly uri: URI;
82
>
/**
83
>
* Optional externally provided prompt command name.
84
>
*/
85
>
readonly name?: string;
86
>
/**
87
>
* Optional externally provided prompt command description.
88
>
*/
89
>
readonly description?: string;
90
>
/**
91
>
* Optional condition that must evaluate to true for this resource to be offered.
92
>
*/
93
>
readonly when?: string;
94
>
/**
95
>
* Optional session types that describe when this resource should be offered.
96
>
*/
97
>
readonly sessionTypes?: readonly string[];
98
>
}
99
>
100
>
/**
101
>
* Returns whether a customization can be used in the provided chat session type.
102
>
*/
103
>
export function matchesSessionType(sessionTypes: readonly string[] | undefined, currentSessionType: string | undefined): boolean {
104
return sessionTypes === undefined || currentSessionType === undefined || sessionTypes.includes(currentSessionType);
105
}
107
>
/**
108
>
* Provides prompt services.
109
>
*/
110
>
export const IPromptsService = createDecorator<IPromptsService>('IPromptsService');
111
>
112
>
/**
113
>
* Where the prompt is stored.
114
>
*/
115
>
export enum PromptsStorage {
116
>
local = 'local',
117
>
user = 'user',
118
>
extension = 'extension',
119
>
plugin = 'plugin',
120
>
builtIn = 'builtin',
121
>
}
122
>
123
>
/**
124
>
* Represents a prompt path with its type.
125
>
* This is used for both prompt files and prompt source folders.
126
>
*/
127
>
export type IPromptPath = IExtensionPromptPath | ILocalPromptPath | IUserPromptPath | IPluginPromptPath | IBuiltinPromptPath;
128
>
129
>
130
>
export interface IPromptPathBase {
131
>
/**
132
>
* URI of the prompt.
133
>
*/
134
>
readonly uri: URI;
135
>
136
>
/**
137
>
* Storage of the prompt.
138
>
*/
139
>
readonly storage: PromptsStorage;
140
>
141
>
/**
142
>
* Type of the prompt (e.g. 'prompt' or 'instructions').
143
>
*/
144
>
readonly type: PromptsType;
145
>
146
>
/**
147
>
* Identifier of the contributing extension (only when storage === PromptsStorage.extension).
148
>
*/
149
>
readonly extension?: IExtensionDescription;
150
>
151
>
/**
152
>
* Identifier of the contributing plugin (only when storage === PromptsStorage.plugin).
153
>
*/
154
>
readonly pluginUri?: URI;
155
>
156
>
/**
157
>
* Human-readable name of the contributing plugin, used for plugin-scoped slash command names.
158
>
*/
159
>
readonly pluginLabel?: string;
160
>
161
>
/**
162
>
* The source that produced this prompt path.
163
>
*/
164
>
readonly source?: PromptFileSource;
165
>
166
>
readonly name?: string;
167
>
168
>
readonly description?: string;
169
>
170
>
/**
171
>
* Optional session types that describe when this resource should be offered.
172
>
*/
173
>
readonly sessionTypes?: readonly string[];
174
>
}
175
>
176
>
export interface IExtensionPromptPath extends IPromptPathBase {
177
>
readonly storage: PromptsStorage.extension;
178
>
readonly extension: IExtensionDescription;
179
>
readonly source: PromptFileSource.ExtensionContribution | PromptFileSource.ExtensionAPI;
180
>
readonly name?: string;
181
>
readonly description?: string;
182
>
readonly when?: string;
183
>
}
184
>
185
>
export function isExtensionPromptPath(obj: IPromptPath): obj is IExtensionPromptPath {
186
return obj.storage === PromptsStorage.extension;
187
}
189
>
export interface ILocalPromptPath extends IPromptPathBase {
190
>
readonly storage: PromptsStorage.local;
191
>
}
192
>
export interface IUserPromptPath extends IPromptPathBase {
193
>
readonly storage: PromptsStorage.user;
194
>
}
195
>
196
>
export interface IPluginPromptPath extends IPromptPathBase {
197
>
readonly storage: PromptsStorage.plugin;
198
>
readonly pluginUri: URI;
199
>
readonly source: PromptFileSource.Plugin;
200
>
}
201
>
202
>
/**
203
>
* Prompt path for built-in prompts bundled with the application (e.g. skills
204
>
* shipped with the Agents app). These are read-only and provided by
205
>
* {@link IPromptsService.listPromptFiles}/`listPromptFilesForStorage`.
206
>
*/
207
>
export interface IBuiltinPromptPath extends IPromptPathBase {
208
>
readonly storage: PromptsStorage.builtIn;
209
>
}
210
>
211
>
export function isBuiltinPromptPath(obj: IPromptPath): obj is IBuiltinPromptPath {
212
return obj.storage === PromptsStorage.builtIn;
213
}
215
>
export type IAgentSource = {
216
>
readonly storage: PromptsStorage.extension;
217
>
readonly extensionId: ExtensionIdentifier;
218
>
} | {
219
>
readonly storage: PromptsStorage.local | PromptsStorage.user | PromptsStorage.builtIn;
220
>
} | {
221
>
readonly storage: PromptsStorage.plugin;
222
>
readonly pluginUri: URI;
223
>
};
224
>
225
>
export namespace IAgentSource {
226
>
export function fromPromptPath(promptPath: IPromptPath): IAgentSource {
227
if (promptPath.storage === PromptsStorage.extension) {
228
return { storage: PromptsStorage.extension, extensionId: promptPath.extension.identifier };