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

package/README.md

@@ -126,8 +126,9 @@ const agent = createAgent({
 
 ### Skills
 
-Skills provide contextual instructions that guide agent behavior. They can bundle tool guidance, provide instructions-only, or enable progressive disclosure of tools.
+Skills provide contextual instructions that guide agent behavior following the [Agent Skills specification](https://agentskills.io/specification). They support both programmatic (TypeScript) and file-based (SKILL.md) formats.
 
+**Programmatic skills:**
 ```typescript
 import { defineSkill } from "@lleverage-ai/agent-sdk";
 
@@ -138,7 +139,7 @@ const dataPlugin = definePlugin({
     defineSkill({
       name: "data-exploration",
       description: "Query and visualize data",
-      prompt: `You have access to data exploration tools.
+      instructions: `You have access to data exploration tools.
 Available tables: products, users, sales.
 Always use getSchema first to see column types.`,
     }),
@@ -146,24 +147,93 @@ Always use getSchema first to see column types.`,
 });
 ```
 
+**File-based skills:**
+```typescript
+import { loadSkillsFromDirectories } from "@lleverage-ai/agent-sdk";
+
+// Load skills from SKILL.md files
+const { skills } = await loadSkillsFromDirectories(["/path/to/skills"]);
+
+// Agent auto-creates registry and skill tool
+const agent = createAgent({ model, skills });
+```
+
+See [Skills Documentation](./docs/skills.md) for complete details on the skills system and Agent Skills spec compliance.
+
+### Prompt Builder
+
+Create dynamic, context-aware system prompts from composable components. Instead of static strings, prompts automatically include tools, skills, backend capabilities, and more.
+
+**Using the default builder:**
+```typescript
+const agent = createAgent({
+  model,
+  // No systemPrompt = uses default prompt builder
+  tools: { read, write, bash },
+});
+// Automatically generates:
+// "You are a helpful AI assistant.
+//
+// # Available Tools
+// - **read**: Read files
+// - **write**: Write files
+// - **bash**: Execute commands
+//
+// # Capabilities
+// - Execute shell commands (bash)
+// - Read and write files to the filesystem"
+```
+
+**Customizing the prompt:**
+```typescript
+import { createDefaultPromptBuilder } from "@lleverage-ai/agent-sdk";
+
+const builder = createDefaultPromptBuilder()
+  .register({
+    name: "project-context",
+    priority: 95,
+    render: () => "You are working on a TypeScript project.",
+  });
+
+const agent = createAgent({
+  model,
+  promptBuilder: builder,
+  tools,
+});
+```
+
+**Static prompts still work:**
+```typescript
+const agent = createAgent({
+  model,
+  systemPrompt: "You are a helpful assistant.",
+  tools,
+});
+```
+
+See [Prompt Builder Documentation](./docs/prompt-builder.md) for complete details on dynamic prompts, components, and customization.
+
 ### Hooks
 
 Hooks allow you to observe and react to agent lifecycle events:
 
 ```typescript
+import { createAgent, createToolHook } from "@lleverage-ai/agent-sdk";
+
 const agent = createAgent({
   model,
   hooks: {
+    // Simple observation hook (void return is fine)
     PreGenerate: [async ({ options }) => {
       console.log("Starting generation...");
-      return {};
     }],
-    PostToolUse: [{
-      hooks: [async ({ tool_name, tool_response }) => {
+
+    // Use createToolHook helper for tool-specific hooks
+    PostToolUse: [
+      createToolHook(async ({ tool_name, tool_response }) => {
         console.log("Tool completed:", tool_name);
-        return {};
-      }],
-    }],
+      }, { matcher: "search_*" }), // Only match tools starting with "search_"
+    ],
   },
 });
 ```
@@ -173,7 +243,7 @@ const agent = createAgent({
 - `PreToolUse`, `PostToolUse`, `PostToolUseFailure` — Tool execution lifecycle
 - `MCPConnectionFailed`, `MCPConnectionRestored` — MCP server connection lifecycle
 
-**Hook utilities:** `createRetryHooks`, `createRateLimitHooks`, `createLoggingHooks`, `createGuardrailsHooks`, `createSecretsFilterHooks`
+**Hook utilities:** `createRetryHooks`, `createRateLimitHooks`, `createLoggingHooks`, `createGuardrailsHooks`, `createSecretsFilterHooks`, `createToolHook`
 
 ### Streaming
 
@@ -195,6 +265,8 @@ export async function POST(req: Request) {
 
 ## Documentation
 
+- [Prompt Builder](./docs/prompt-builder.md) — Dynamic, context-aware system prompts
+- [Skills System](./docs/skills.md) — Progressive disclosure with Agent Skills spec compliance
 - [Tool Loading Strategies](./docs/tool-loading.md) — Eager, lazy, and dynamic tool loading
 - [Security & Production](./docs/security.md) — Security policies, guardrails, and secrets filtering
 - [Subagents](./docs/subagents.md) — Task delegation and background tasks

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAuDH,OAAO,KAAK,EACV,KAAK,EACL,YAAY,EA0Bb,MAAM,YAAY,CAAC;AA8lBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CAg/DxD"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0DH,OAAO,KAAK,EACV,KAAK,EACL,YAAY,EAyBb,MAAM,YAAY,CAAC;AA8lBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CAgoExD"}

package/dist/agent.js

@@ -13,6 +13,7 @@ import { createRetryLoopState, handleGenerationError, invokePreGenerateHooks, no
 import { aggregatePermissionDecisions, extractUpdatedInput, extractUpdatedResult, invokeHooksWithTimeout, invokeMatchingHooks, } from "./hooks.js";
 import { MCPManager } from "./mcp/manager.js";
 import { applyMiddleware, mergeHooks, setupMiddleware } from "./middleware/index.js";
+import { createDefaultPromptBuilder } from "./prompt-builder/components.js";
 import { ACCEPT_EDITS_BLOCKED_PATTERNS } from "./security/index.js";
 import { TaskManager } from "./task-manager.js";
 import { coreToolsToToolSet, createCoreTools, createSearchToolsTool, createTaskOutputTool, createTaskTool, } from "./tools/factory.js";
@@ -527,6 +528,16 @@ function isBackendFactory(value) {
  */
 export function createAgent(options) {
     const id = `agent-${++agentIdCounter}`;
+    // Validate mutually exclusive prompt options
+    if (options.systemPrompt !== undefined && options.promptBuilder) {
+        throw new Error("Cannot specify both systemPrompt and promptBuilder - they are mutually exclusive");
+    }
+    // Determine prompt mode
+    // - 'static': Use systemPrompt string directly
+    // - 'builder': Use PromptBuilder to generate dynamic prompts
+    const promptMode = options.systemPrompt !== undefined ? "static" : "builder";
+    // Get or create prompt builder
+    const promptBuilder = options.promptBuilder ?? (promptMode === "builder" ? createDefaultPromptBuilder() : undefined);
     // Process middleware to get hooks (middleware hooks come before explicit hooks)
     const middleware = options.middleware ?? [];
     const middlewareHooks = applyMiddleware(middleware);
@@ -562,6 +573,8 @@ export function createAgent(options) {
     // Initialize task manager for background task tracking
     const taskManager = new TaskManager();
     // Determine plugin loading mode
+    // Track whether it was explicitly set to distinguish from default
+    const explicitPluginLoading = options.pluginLoading !== undefined;
     const pluginLoadingMode = options.pluginLoading ?? "eager";
     const preloadPlugins = new Set(options.preloadPlugins ?? []);
     // Initialize tool registry for lazy/explicit loading modes
@@ -674,20 +687,21 @@ export function createAgent(options) {
         }
     }
     // Determine if we should use deferred loading based on tool search settings
-    // Note: "auto" mode enables deferred loading when tool count exceeds threshold
+    // Note: Only activate deferred loading if explicitly requested, not based on auto threshold
+    // The auto threshold should only affect whether search_tools is created, not loading behavior
     if (toolSearchEnabled === "always") {
         deferredLoadingActive = true;
     }
-    else if (toolSearchEnabled === "auto" && totalPluginToolCount > toolSearchThreshold) {
-        deferredLoadingActive = true;
-    }
+    // Removed: auto threshold no longer forces deferred loading
+    // The default eager loading should be respected
     // Auto-create core tools (unless user provides explicit tools)
-    // Note: search_tools is created separately with proper configuration
+    // Note: search_tools is created separately below based on loading mode
     const { tools: autoCreatedCoreTools } = createCoreTools({
         backend: effectiveBackend,
         state,
         taskManager,
-        mcpManager: deferredLoadingActive ? undefined : mcpManager, // Only pass if not deferred
+        // Don't pass mcpManager here - we create search_tools manually below
+        mcpManager: undefined,
         disabled: options.disabledCoreTools,
         skills,
     });
@@ -705,31 +719,64 @@ export function createAgent(options) {
         // getActiveToolSetWithStreaming() and are not registered here
         if (plugin.tools && typeof plugin.tools !== "function") {
             const shouldPreload = preloadPlugins.has(plugin.name);
-            if (pluginLoadingMode === "lazy" && toolRegistry) {
+            // Priority order:
+            // 1. Explicit mode - don't register
+            // 2. Preload - always load immediately
+            // 3. Explicit eager - always load immediately
+            // 4. Lazy mode - register with tool registry
+            // 5. Deferred loading - register but don't load
+            // 6. Default eager - load immediately
+            if (pluginLoadingMode === "explicit") {
+                // Explicit mode: don't auto-register, user must do it manually
+                // Skip registration entirely
+            }
+            else if (shouldPreload) {
+                // Preloaded plugins: always load immediately, regardless of other settings
+                mcpManager.registerPluginTools(plugin.name, plugin.tools, {
+                    autoLoad: true,
+                });
+            }
+            else if (explicitPluginLoading && pluginLoadingMode === "eager") {
+                // Explicit eager mode: always load immediately, regardless of toolSearch settings
+                mcpManager.registerPluginTools(plugin.name, plugin.tools, {
+                    autoLoad: true,
+                });
+            }
+            else if (pluginLoadingMode === "lazy" && toolRegistry) {
                 // Lazy mode: register with registry for on-demand loading
                 toolRegistry.registerPlugin(plugin.name, plugin.tools);
             }
-            else if (deferredLoadingActive && !shouldPreload) {
-                // Deferred loading: register tools but don't load them initially
+            else if (deferredLoadingActive) {
+                // Deferred loading (auto threshold or always enabled): register tools but don't load them initially
                 mcpManager.registerPluginTools(plugin.name, plugin.tools, {
                     autoLoad: false,
                 });
             }
-            else if (pluginLoadingMode === "eager" || shouldPreload) {
-                // Eager mode or preloaded: register and load immediately
+            else {
+                // Default eager mode: load immediately
                 mcpManager.registerPluginTools(plugin.name, plugin.tools, {
                     autoLoad: true,
                 });
             }
-            // explicit mode: don't register, user must do it manually
         }
     }
-    // Create search_tools with load capability when deferred loading is active
-    if (deferredLoadingActive && !options.disabledCoreTools?.includes("search_tools")) {
+    // Create search_tools for MCP tool discovery and/or plugin loading
+    // New behavior:
+    // - Create when auto threshold is exceeded (for lazy discovery)
+    // - Create when deferred loading is active (explicitly requested)
+    // - Create when external MCP servers exist (for MCP tool search)
+    // - Always auto-load tools when found (no manual load step)
+    const shouldCreateSearchToolsForAutoThreshold = toolSearchEnabled === "auto" && totalPluginToolCount > toolSearchThreshold;
+    const shouldCreateSearchTools = !options.disabledCoreTools?.includes("search_tools") &&
+        (deferredLoadingActive ||
+            shouldCreateSearchToolsForAutoThreshold ||
+            (mcpManager.hasExternalServers() && toolSearchEnabled !== "never"));
+    if (shouldCreateSearchTools) {
         coreTools.search_tools = createSearchToolsTool({
             manager: mcpManager,
             maxResults: toolSearchMaxResults,
-            enableLoad: true,
+            enableLoad: true, // Always enable auto-loading
+            autoLoad: true, // NEW: Auto-load tools after searching
             onToolsLoaded: (toolNames) => {
                 // Tools are now loaded in MCPManager and will be included in getActiveToolSet()
                 // This callback can be used for logging/notifications
@@ -775,6 +822,62 @@ export function createAgent(options) {
         }
         return filtered;
     };
+    // Helper to build prompt context from current agent state
+    const buildPromptContext = (messages, threadId) => {
+        // Get filtered tools (respecting allowedTools/disallowedTools) so the prompt
+        // only advertises tools the agent will actually expose
+        const filteredTools = filterToolsByAllowed((() => {
+            const allTools = { ...coreTools };
+            Object.assign(allTools, mcpManager.getToolSet());
+            if (toolRegistry) {
+                Object.assign(allTools, toolRegistry.getLoadedTools());
+            }
+            return allTools;
+        })());
+        // Extract tool metadata for context
+        const toolsMetadata = Object.entries(filteredTools).map(([name, tool]) => ({
+            name,
+            description: tool.description ?? "",
+        }));
+        // Extract skills metadata from the skills array
+        const skillsMetadata = skills.map((skill) => ({
+            name: skill.name,
+            description: skill.description,
+        }));
+        // Extract plugins metadata
+        const pluginsMetadata = (options.plugins ?? []).map((plugin) => ({
+            name: plugin.name,
+            description: plugin.description ?? "",
+        }));
+        // Build backend info
+        const backendInfo = {
+            type: backend.constructor.name.toLowerCase().replace("backend", "") || "unknown",
+            hasExecuteCapability: hasExecuteCapability(backend),
+            rootDir: "rootDir" in backend ? backend.rootDir : undefined,
+        };
+        return {
+            tools: toolsMetadata.length > 0 ? toolsMetadata : undefined,
+            skills: skillsMetadata.length > 0 ? skillsMetadata : undefined,
+            plugins: pluginsMetadata.length > 0 ? pluginsMetadata : undefined,
+            backend: backendInfo,
+            state,
+            // Model ID extraction is not reliable across all LanguageModel types
+            // Users can access the full model via their custom context if needed
+            model: undefined,
+            maxSteps: options.maxSteps,
+            permissionMode,
+            currentMessages: messages,
+            threadId,
+        };
+    };
+    // Helper to get system prompt (either static or built from context)
+    const getSystemPrompt = (context) => {
+        if (promptMode === "static") {
+            return options.systemPrompt;
+        }
+        // Build prompt using prompt builder
+        return promptBuilder.build(context);
+    };
     // Helper to get current active tools (core + MCP + dynamically loaded from registry)
     const getActiveToolSet = (threadId) => {
         // Start with core tools
@@ -1151,8 +1254,11 @@ export function createAgent(options) {
                     // Build initial params - use active tools (core + dynamically loaded + task)
                     // Apply hooks AFTER adding task tool so task tool is also wrapped
                     const activeTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    // Build prompt context and generate system prompt
+                    const promptContext = buildPromptContext(messages, effectiveGenOptions.threadId);
+                    const systemPrompt = getSystemPrompt(promptContext);
                     const initialParams = {
-                        system: options.systemPrompt,
+                        system: systemPrompt,
                         messages,
                         tools: activeTools,
                         maxTokens: effectiveGenOptions.maxTokens,
@@ -1418,8 +1524,11 @@ export function createAgent(options) {
                     // Build initial params - use active tools (core + dynamically loaded + task)
                     // Apply hooks AFTER adding task tool so task tool is also wrapped
                     const activeTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    // Build prompt context and generate system prompt
+                    const promptContext = buildPromptContext(messages, effectiveGenOptions.threadId);
+                    const systemPrompt = getSystemPrompt(promptContext);
                     const initialParams = {
-                        system: options.systemPrompt,
+                        system: systemPrompt,
                         messages,
                         tools: activeTools,
                         maxTokens: effectiveGenOptions.maxTokens,
@@ -1576,8 +1685,11 @@ export function createAgent(options) {
                     // Build initial params - use active tools (core + dynamically loaded + task)
                     // Apply hooks AFTER adding task tool so task tool is also wrapped
                     const activeTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    // Build prompt context and generate system prompt
+                    const promptContext = buildPromptContext(messages, effectiveGenOptions.threadId);
+                    const systemPrompt = getSystemPrompt(promptContext);
                     const initialParams = {
-                        system: options.systemPrompt,
+                        system: systemPrompt,
                         messages,
                         tools: activeTools,
                         maxTokens: effectiveGenOptions.maxTokens,
@@ -1707,8 +1819,11 @@ export function createAgent(options) {
                     // Build initial params - use active tools (core + dynamically loaded + task)
                     // Apply hooks AFTER adding task tool so task tool is also wrapped
                     const activeTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    // Build prompt context and generate system prompt
+                    const promptContext = buildPromptContext(messages, effectiveGenOptions.threadId);
+                    const systemPrompt = getSystemPrompt(promptContext);
                     const initialParams = {
-                        system: options.systemPrompt,
+                        system: systemPrompt,
                         messages,
                         tools: activeTools,
                         maxTokens: effectiveGenOptions.maxTokens,
@@ -1856,9 +1971,12 @@ export function createAgent(options) {
                             // Build tools with streaming context and task tool
                             // Apply hooks AFTER adding task tool so task tool is also wrapped
                             const streamingTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSetWithStreaming(streamingContext, effectiveGenOptions.threadId), streamingContext), effectiveGenOptions.threadId);
+                            // Build prompt context and generate system prompt
+                            const promptContext = buildPromptContext(messages, effectiveGenOptions.threadId);
+                            const systemPrompt = getSystemPrompt(promptContext);
                             // Build initial params with streaming-aware tools
                             const initialParams = {
-                                system: options.systemPrompt,
+                                system: systemPrompt,
                                 messages,
                                 tools: streamingTools,
                                 maxTokens: effectiveGenOptions.maxTokens,