@lleverage-ai/agent-sdk 0.0.2-alpha.6 → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +81 -9
  2. package/dist/agent.d.ts.map +1 -1
  3. package/dist/agent.js +138 -20
  4. package/dist/agent.js.map +1 -1
  5. package/dist/hooks.d.ts +66 -0
  6. package/dist/hooks.d.ts.map +1 -1
  7. package/dist/hooks.js +63 -1
  8. package/dist/hooks.js.map +1 -1
  9. package/dist/index.d.ts +8 -4
  10. package/dist/index.d.ts.map +1 -1
  11. package/dist/index.js +7 -2
  12. package/dist/index.js.map +1 -1
  13. package/dist/mcp/manager.d.ts +16 -0
  14. package/dist/mcp/manager.d.ts.map +1 -1
  15. package/dist/mcp/manager.js +20 -0
  16. package/dist/mcp/manager.js.map +1 -1
  17. package/dist/prompt-builder/components.d.ts +149 -0
  18. package/dist/prompt-builder/components.d.ts.map +1 -0
  19. package/dist/prompt-builder/components.js +252 -0
  20. package/dist/prompt-builder/components.js.map +1 -0
  21. package/dist/prompt-builder/index.d.ts +248 -0
  22. package/dist/prompt-builder/index.d.ts.map +1 -0
  23. package/dist/prompt-builder/index.js +165 -0
  24. package/dist/prompt-builder/index.js.map +1 -0
  25. package/dist/skills/loader.d.ts +152 -0
  26. package/dist/skills/loader.d.ts.map +1 -0
  27. package/dist/skills/loader.js +411 -0
  28. package/dist/skills/loader.js.map +1 -0
  29. package/dist/testing/mock-agent.d.ts +2 -1
  30. package/dist/testing/mock-agent.d.ts.map +1 -1
  31. package/dist/tools/factory.d.ts +3 -3
  32. package/dist/tools/factory.d.ts.map +1 -1
  33. package/dist/tools/factory.js +1 -1
  34. package/dist/tools/factory.js.map +1 -1
  35. package/dist/tools/index.d.ts +2 -2
  36. package/dist/tools/index.d.ts.map +1 -1
  37. package/dist/tools/index.js +1 -1
  38. package/dist/tools/index.js.map +1 -1
  39. package/dist/tools/search.d.ts +11 -1
  40. package/dist/tools/search.d.ts.map +1 -1
  41. package/dist/tools/search.js +25 -10
  42. package/dist/tools/search.js.map +1 -1
  43. package/dist/tools/skills.d.ts +125 -84
  44. package/dist/tools/skills.d.ts.map +1 -1
  45. package/dist/tools/skills.js +16 -89
  46. package/dist/tools/skills.js.map +1 -1
  47. package/dist/tools.d.ts +5 -4
  48. package/dist/tools.d.ts.map +1 -1
  49. package/dist/tools.js +7 -4
  50. package/dist/tools.js.map +1 -1
  51. package/dist/types.d.ts +143 -45
  52. package/dist/types.d.ts.map +1 -1
  53. package/dist/types.js.map +1 -1
  54. package/package.json +1 -1
@@ -0,0 +1,248 @@
1
+ /**
2
+ * Prompt builder system for creating dynamic, context-aware system prompts.
3
+ *
4
+ * @packageDocumentation
5
+ */
6
+ import type { ModelMessage } from "ai";
7
+ import type { AgentState } from "../backends/state.js";
8
+ import type { PermissionMode } from "../types.js";
9
+ /**
10
+ * Context available to prompt components when building prompts.
11
+ * Contains all relevant agent state and configuration.
12
+ *
13
+ * @category Prompt Builder
14
+ */
15
+ export interface PromptContext {
16
+ /**
17
+ * Tools available to the agent.
18
+ * Each entry includes the tool name and description.
19
+ */
20
+ tools?: Array<{
21
+ name: string;
22
+ description: string;
23
+ }>;
24
+ /**
25
+ * Skills available to the agent.
26
+ * Each entry includes the skill name and description.
27
+ */
28
+ skills?: Array<{
29
+ name: string;
30
+ description: string;
31
+ }>;
32
+ /**
33
+ * Plugins loaded by the agent.
34
+ * Each entry includes the plugin name and description.
35
+ */
36
+ plugins?: Array<{
37
+ name: string;
38
+ description: string;
39
+ }>;
40
+ /**
41
+ * Information about the backend being used.
42
+ */
43
+ backend?: {
44
+ /** Type of backend (e.g., 'filesystem', 'state') */
45
+ type: string;
46
+ /** Whether the backend supports command execution */
47
+ hasExecuteCapability: boolean;
48
+ /** Root directory for filesystem backends */
49
+ rootDir?: string;
50
+ };
51
+ /**
52
+ * Agent state for accessing todos and other state.
53
+ */
54
+ state?: AgentState;
55
+ /**
56
+ * Model identifier being used.
57
+ */
58
+ model?: string;
59
+ /**
60
+ * Maximum number of tool call steps allowed.
61
+ */
62
+ maxSteps?: number;
63
+ /**
64
+ * Permission mode for the agent.
65
+ */
66
+ permissionMode?: PermissionMode;
67
+ /**
68
+ * Current conversation messages (available during generation).
69
+ */
70
+ currentMessages?: ModelMessage[];
71
+ /**
72
+ * Thread ID for the current conversation (if any).
73
+ */
74
+ threadId?: string;
75
+ /**
76
+ * Custom user-defined data that can be passed to components.
77
+ */
78
+ custom?: Record<string, unknown>;
79
+ }
80
+ /**
81
+ * A component that contributes to the system prompt.
82
+ *
83
+ * Components are sorted by priority (higher = rendered earlier in prompt)
84
+ * and can conditionally include themselves based on context.
85
+ *
86
+ * @example
87
+ * ```typescript
88
+ * const toolsComponent: PromptComponent = {
89
+ * name: 'tools-listing',
90
+ * priority: 70,
91
+ * condition: (ctx) => ctx.tools !== undefined && ctx.tools.length > 0,
92
+ * render: (ctx) => {
93
+ * const toolLines = ctx.tools!.map((t) => `- **${t.name}**: ${t.description}`);
94
+ * return `# Available Tools\n\n${toolLines.join('\n')}`;
95
+ * },
96
+ * };
97
+ * ```
98
+ *
99
+ * @category Prompt Builder
100
+ */
101
+ export interface PromptComponent {
102
+ /**
103
+ * Unique identifier for this component.
104
+ * Used for unregistering components.
105
+ */
106
+ name: string;
107
+ /**
108
+ * Priority for ordering components in the final prompt.
109
+ * Higher priority components are rendered first.
110
+ * @defaultValue 50
111
+ */
112
+ priority?: number;
113
+ /**
114
+ * Optional condition to determine if this component should be included.
115
+ * If not provided or returns true, the component is included.
116
+ * @param ctx - The prompt context
117
+ * @returns true to include this component, false to skip it
118
+ */
119
+ condition?: (ctx: PromptContext) => boolean;
120
+ /**
121
+ * Render the component's contribution to the prompt.
122
+ * @param ctx - The prompt context
123
+ * @returns The text to include in the system prompt
124
+ */
125
+ render: (ctx: PromptContext) => string;
126
+ }
127
+ /**
128
+ * Builder for constructing dynamic system prompts from components.
129
+ *
130
+ * The PromptBuilder manages a collection of components that are combined
131
+ * to create the final system prompt. Components are sorted by priority
132
+ * and can conditionally include themselves.
133
+ *
134
+ * @example
135
+ * ```typescript
136
+ * const builder = new PromptBuilder()
137
+ * .register({
138
+ * name: 'identity',
139
+ * priority: 100,
140
+ * render: () => 'You are a helpful assistant.',
141
+ * })
142
+ * .register({
143
+ * name: 'tools',
144
+ * priority: 70,
145
+ * condition: (ctx) => ctx.tools && ctx.tools.length > 0,
146
+ * render: (ctx) => `Tools: ${ctx.tools!.map(t => t.name).join(', ')}`,
147
+ * });
148
+ *
149
+ * const prompt = builder.build({ tools: [{ name: 'read', description: 'Read files' }] });
150
+ * ```
151
+ *
152
+ * @category Prompt Builder
153
+ */
154
+ export declare class PromptBuilder {
155
+ private components;
156
+ /**
157
+ * Register a single component.
158
+ *
159
+ * If a component with the same name already exists, it will be replaced.
160
+ *
161
+ * @param component - The component to register
162
+ * @returns This builder for chaining
163
+ *
164
+ * @example
165
+ * ```typescript
166
+ * builder.register({
167
+ * name: 'custom',
168
+ * priority: 80,
169
+ * render: () => 'Custom instructions',
170
+ * });
171
+ * ```
172
+ */
173
+ register(component: PromptComponent): this;
174
+ /**
175
+ * Register multiple components at once.
176
+ *
177
+ * @param components - Array of components to register
178
+ * @returns This builder for chaining
179
+ *
180
+ * @example
181
+ * ```typescript
182
+ * builder.registerMany([
183
+ * identityComponent,
184
+ * toolsComponent,
185
+ * skillsComponent,
186
+ * ]);
187
+ * ```
188
+ */
189
+ registerMany(components: PromptComponent[]): this;
190
+ /**
191
+ * Remove a component by name.
192
+ *
193
+ * @param name - The name of the component to remove
194
+ * @returns This builder for chaining
195
+ *
196
+ * @example
197
+ * ```typescript
198
+ * builder.unregister('identity');
199
+ * ```
200
+ */
201
+ unregister(name: string): this;
202
+ /**
203
+ * Build the final prompt from the registered components.
204
+ *
205
+ * Components are:
206
+ * 1. Filtered by their condition functions (if present)
207
+ * 2. Sorted by priority (higher priority first)
208
+ * 3. Rendered and joined with double newlines
209
+ *
210
+ * @param context - The context to pass to components
211
+ * @returns The final system prompt string
212
+ *
213
+ * @example
214
+ * ```typescript
215
+ * const context: PromptContext = {
216
+ * tools: [{ name: 'read', description: 'Read files' }],
217
+ * model: 'claude-3-5-sonnet-20241022',
218
+ * };
219
+ * const prompt = builder.build(context);
220
+ * ```
221
+ */
222
+ build(context: PromptContext): string;
223
+ /**
224
+ * Clone this builder with all its registered components.
225
+ *
226
+ * Useful for creating variants of a base builder.
227
+ *
228
+ * @returns A new PromptBuilder with the same components
229
+ *
230
+ * @example
231
+ * ```typescript
232
+ * const base = createDefaultPromptBuilder();
233
+ * const custom = base.clone().register({
234
+ * name: 'custom',
235
+ * render: () => 'Additional instructions',
236
+ * });
237
+ * ```
238
+ */
239
+ clone(): PromptBuilder;
240
+ /**
241
+ * Get all registered component names.
242
+ * Useful for debugging and introspection.
243
+ *
244
+ * @returns Array of component names
245
+ */
246
+ getComponentNames(): string[];
247
+ }
248
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompt-builder/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAErD;;;OAGG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEtD;;;OAGG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEvD;;OAEG;IACH,OAAO,CAAC,EAAE;QACR,oDAAoD;QACpD,IAAI,EAAE,MAAM,CAAC;QACb,qDAAqD;QACrD,oBAAoB,EAAE,OAAO,CAAC;QAC9B,6CAA6C;QAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF;;OAEG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;OAEG;IACH,eAAe,CAAC,EAAE,YAAY,EAAE,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC;IAE5C;;;;OAIG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,MAAM,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAAyB;IAE3C;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI;IAQ1C;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,IAAI;IAOjD;;;;;;;;;;OAUG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM;IAuBrC;;;;;;;;;;;;;;;OAeG;IACH,KAAK,IAAI,aAAa;IAMtB;;;;;OAKG;IACH,iBAAiB,IAAI,MAAM,EAAE;CAG9B"}
@@ -0,0 +1,165 @@
1
+ /**
2
+ * Prompt builder system for creating dynamic, context-aware system prompts.
3
+ *
4
+ * @packageDocumentation
5
+ */
6
+ /**
7
+ * Builder for constructing dynamic system prompts from components.
8
+ *
9
+ * The PromptBuilder manages a collection of components that are combined
10
+ * to create the final system prompt. Components are sorted by priority
11
+ * and can conditionally include themselves.
12
+ *
13
+ * @example
14
+ * ```typescript
15
+ * const builder = new PromptBuilder()
16
+ * .register({
17
+ * name: 'identity',
18
+ * priority: 100,
19
+ * render: () => 'You are a helpful assistant.',
20
+ * })
21
+ * .register({
22
+ * name: 'tools',
23
+ * priority: 70,
24
+ * condition: (ctx) => ctx.tools && ctx.tools.length > 0,
25
+ * render: (ctx) => `Tools: ${ctx.tools!.map(t => t.name).join(', ')}`,
26
+ * });
27
+ *
28
+ * const prompt = builder.build({ tools: [{ name: 'read', description: 'Read files' }] });
29
+ * ```
30
+ *
31
+ * @category Prompt Builder
32
+ */
33
+ export class PromptBuilder {
34
+ components = [];
35
+ /**
36
+ * Register a single component.
37
+ *
38
+ * If a component with the same name already exists, it will be replaced.
39
+ *
40
+ * @param component - The component to register
41
+ * @returns This builder for chaining
42
+ *
43
+ * @example
44
+ * ```typescript
45
+ * builder.register({
46
+ * name: 'custom',
47
+ * priority: 80,
48
+ * render: () => 'Custom instructions',
49
+ * });
50
+ * ```
51
+ */
52
+ register(component) {
53
+ // Remove existing component with same name
54
+ this.components = this.components.filter((c) => c.name !== component.name);
55
+ // Add new component
56
+ this.components.push(component);
57
+ return this;
58
+ }
59
+ /**
60
+ * Register multiple components at once.
61
+ *
62
+ * @param components - Array of components to register
63
+ * @returns This builder for chaining
64
+ *
65
+ * @example
66
+ * ```typescript
67
+ * builder.registerMany([
68
+ * identityComponent,
69
+ * toolsComponent,
70
+ * skillsComponent,
71
+ * ]);
72
+ * ```
73
+ */
74
+ registerMany(components) {
75
+ for (const component of components) {
76
+ this.register(component);
77
+ }
78
+ return this;
79
+ }
80
+ /**
81
+ * Remove a component by name.
82
+ *
83
+ * @param name - The name of the component to remove
84
+ * @returns This builder for chaining
85
+ *
86
+ * @example
87
+ * ```typescript
88
+ * builder.unregister('identity');
89
+ * ```
90
+ */
91
+ unregister(name) {
92
+ this.components = this.components.filter((c) => c.name !== name);
93
+ return this;
94
+ }
95
+ /**
96
+ * Build the final prompt from the registered components.
97
+ *
98
+ * Components are:
99
+ * 1. Filtered by their condition functions (if present)
100
+ * 2. Sorted by priority (higher priority first)
101
+ * 3. Rendered and joined with double newlines
102
+ *
103
+ * @param context - The context to pass to components
104
+ * @returns The final system prompt string
105
+ *
106
+ * @example
107
+ * ```typescript
108
+ * const context: PromptContext = {
109
+ * tools: [{ name: 'read', description: 'Read files' }],
110
+ * model: 'claude-3-5-sonnet-20241022',
111
+ * };
112
+ * const prompt = builder.build(context);
113
+ * ```
114
+ */
115
+ build(context) {
116
+ // Filter components by condition
117
+ const activeComponents = this.components.filter((component) => {
118
+ if (component.condition) {
119
+ return component.condition(context);
120
+ }
121
+ return true;
122
+ });
123
+ // Sort by priority (higher first)
124
+ activeComponents.sort((a, b) => {
125
+ const aPriority = a.priority ?? 50;
126
+ const bPriority = b.priority ?? 50;
127
+ return bPriority - aPriority;
128
+ });
129
+ // Render and join
130
+ const parts = activeComponents.map((component) => component.render(context));
131
+ // Filter out empty strings and join with double newlines
132
+ return parts.filter((part) => part.trim().length > 0).join("\n\n");
133
+ }
134
+ /**
135
+ * Clone this builder with all its registered components.
136
+ *
137
+ * Useful for creating variants of a base builder.
138
+ *
139
+ * @returns A new PromptBuilder with the same components
140
+ *
141
+ * @example
142
+ * ```typescript
143
+ * const base = createDefaultPromptBuilder();
144
+ * const custom = base.clone().register({
145
+ * name: 'custom',
146
+ * render: () => 'Additional instructions',
147
+ * });
148
+ * ```
149
+ */
150
+ clone() {
151
+ const cloned = new PromptBuilder();
152
+ cloned.components = [...this.components];
153
+ return cloned;
154
+ }
155
+ /**
156
+ * Get all registered component names.
157
+ * Useful for debugging and introspection.
158
+ *
159
+ * @returns Array of component names
160
+ */
161
+ getComponentNames() {
162
+ return this.components.map((c) => c.name);
163
+ }
164
+ }
165
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompt-builder/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkIH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAO,aAAa;IAChB,UAAU,GAAsB,EAAE,CAAC;IAE3C;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAA0B;QACjC,2CAA2C;QAC3C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC;QAC3E,oBAAoB;QACpB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,UAA6B;QACxC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;OAUG;IACH,UAAU,CAAC,IAAY;QACrB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QACjE,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,OAAsB;QAC1B,iCAAiC;QACjC,MAAM,gBAAgB,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE;YAC5D,IAAI,SAAS,CAAC,SAAS,EAAE,CAAC;gBACxB,OAAO,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YACtC,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;QAEH,kCAAkC;QAClC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YAC7B,MAAM,SAAS,GAAG,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC;YACnC,MAAM,SAAS,GAAG,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC;YACnC,OAAO,SAAS,GAAG,SAAS,CAAC;QAC/B,CAAC,CAAC,CAAC;QAEH,kBAAkB;QAClB,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QAE7E,yDAAyD;QACzD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrE,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK;QACH,MAAM,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QACnC,MAAM,CAAC,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QACzC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,iBAAiB;QACf,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5C,CAAC;CACF"}
@@ -0,0 +1,152 @@
1
+ /**
2
+ * File-based skill loader for Agent Skills specification.
3
+ *
4
+ * Loads skills from directories containing SKILL.md files according to the
5
+ * Agent Skills specification (https://agentskills.io/specification).
6
+ *
7
+ * @packageDocumentation
8
+ */
9
+ import type { SkillDefinition } from "../tools/skills.js";
10
+ /**
11
+ * Error that occurred while loading a skill.
12
+ *
13
+ * @category Skills
14
+ */
15
+ export interface SkillLoadError {
16
+ /** Path to the skill directory that failed to load */
17
+ path: string;
18
+ /** Error message describing what went wrong */
19
+ error: string;
20
+ /** Optional details for debugging */
21
+ details?: string;
22
+ }
23
+ /**
24
+ * Result from loading skills from directories.
25
+ *
26
+ * @category Skills
27
+ */
28
+ export interface SkillLoadResult {
29
+ /** Successfully loaded skills */
30
+ skills: SkillDefinition[];
31
+ /** Errors encountered during loading */
32
+ errors: SkillLoadError[];
33
+ }
34
+ /**
35
+ * Options for loading skills.
36
+ *
37
+ * @category Skills
38
+ */
39
+ export interface LoadSkillsOptions {
40
+ /**
41
+ * Whether to validate skill metadata against the spec.
42
+ * @defaultValue true
43
+ */
44
+ validate?: boolean;
45
+ /**
46
+ * Whether to include hidden directories (starting with .)
47
+ * @defaultValue false
48
+ */
49
+ includeHidden?: boolean;
50
+ }
51
+ /**
52
+ * Load skills from multiple directories.
53
+ *
54
+ * Scans the given directories for subdirectories containing SKILL.md files.
55
+ * Each subdirectory with a SKILL.md is treated as a skill.
56
+ *
57
+ * @param directories - Array of directory paths to scan
58
+ * @param options - Loading options
59
+ * @returns Promise resolving to loaded skills and any errors
60
+ *
61
+ * @example
62
+ * ```typescript
63
+ * const result = await loadSkillsFromDirectories([
64
+ * "/path/to/skills",
65
+ * "/home/user/.skills",
66
+ * ]);
67
+ *
68
+ * console.log(`Loaded ${result.skills.length} skills`);
69
+ * for (const error of result.errors) {
70
+ * console.error(`Failed to load ${error.path}: ${error.error}`);
71
+ * }
72
+ * ```
73
+ *
74
+ * @category Skills
75
+ */
76
+ export declare function loadSkillsFromDirectories(directories: string[], options?: LoadSkillsOptions): Promise<SkillLoadResult>;
77
+ /**
78
+ * Load a single skill from a directory.
79
+ *
80
+ * The directory must contain a SKILL.md file with valid frontmatter.
81
+ *
82
+ * @param directory - Path to skill directory
83
+ * @param options - Loading options
84
+ * @returns Promise resolving to the loaded skill
85
+ * @throws Error if SKILL.md is missing or invalid
86
+ *
87
+ * @example
88
+ * ```typescript
89
+ * const skill = await loadSkillFromDirectory("/path/to/skills/git");
90
+ *
91
+ * console.log(`Loaded skill: ${skill.name}`);
92
+ * console.log(`Instructions: ${skill.instructions}`);
93
+ * console.log(`Scripts: ${skill.scripts?.join(", ")}`);
94
+ * ```
95
+ *
96
+ * @category Skills
97
+ */
98
+ export declare function loadSkillFromDirectory(directory: string, options?: LoadSkillsOptions): Promise<SkillDefinition>;
99
+ /**
100
+ * Get list of scripts from a loaded skill.
101
+ *
102
+ * @param skill - Loaded skill definition
103
+ * @returns Array of script filenames
104
+ *
105
+ * @example
106
+ * ```typescript
107
+ * const skill = await loadSkillFromDirectory("/path/to/git");
108
+ * const scripts = getSkillScripts(skill);
109
+ * // ["status.sh", "commit.py"]
110
+ * ```
111
+ *
112
+ * @category Skills
113
+ */
114
+ export declare function getSkillScripts(skill: SkillDefinition): string[];
115
+ /**
116
+ * Get list of references from a loaded skill.
117
+ *
118
+ * @param skill - Loaded skill definition
119
+ * @returns Array of reference filenames
120
+ *
121
+ * @category Skills
122
+ */
123
+ export declare function getSkillReferences(skill: SkillDefinition): string[];
124
+ /**
125
+ * Get list of assets from a loaded skill.
126
+ *
127
+ * @param skill - Loaded skill definition
128
+ * @returns Array of asset filenames
129
+ *
130
+ * @category Skills
131
+ */
132
+ export declare function getSkillAssets(skill: SkillDefinition): string[];
133
+ /**
134
+ * Get full path to a skill resource.
135
+ *
136
+ * @param skill - Loaded skill definition
137
+ * @param type - Resource type (scripts, references, assets)
138
+ * @param filename - Filename within the resource directory
139
+ * @returns Full path to the resource
140
+ * @throws Error if skill doesn't have a skillPath
141
+ *
142
+ * @example
143
+ * ```typescript
144
+ * const skill = await loadSkillFromDirectory("/path/to/git");
145
+ * const scriptPath = getSkillResourcePath(skill, "scripts", "status.sh");
146
+ * // "/path/to/git/scripts/status.sh"
147
+ * ```
148
+ *
149
+ * @category Skills
150
+ */
151
+ export declare function getSkillResourcePath(skill: SkillDefinition, type: "scripts" | "references" | "assets", filename: string): string;
152
+ //# sourceMappingURL=loader.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/skills/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAM1D;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,wCAAwC;IACxC,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAeD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,CAkD1B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,CAkE1B;AA4ND;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE,CAGhE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE,CAGnE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE,CAG/D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,QAAQ,EACzC,QAAQ,EAAE,MAAM,GACf,MAAM,CAKR"}