@lleverage-ai/agent-sdk 0.0.2 → 0.0.3

package/dist/prompt-builder/components.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Default prompt components for common use cases.
+ *
+ * @packageDocumentation
+ */
+import type { PromptComponent } from "./index.js";
+import { PromptBuilder } from "./index.js";
+/**
+ * Default identity component providing a basic agent identity.
+ *
+ * Priority: 100 (highest)
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(identityComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export declare const identityComponent: PromptComponent;
+/**
+ * Lists available tools in the system prompt.
+ *
+ * Only included if tools are available.
+ * Priority: 70
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(toolsComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export declare const toolsComponent: PromptComponent;
+/**
+ * Lists available skills in the system prompt.
+ *
+ * Only included if skills are available.
+ * Priority: 65
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(skillsComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export declare const skillsComponent: PromptComponent;
+/**
+ * Lists agent capabilities based on backend and configuration.
+ *
+ * Priority: 60
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(capabilitiesComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export declare const capabilitiesComponent: PromptComponent;
+/**
+ * Provides context about the current conversation.
+ *
+ * Only included if thread ID or messages are available.
+ * Priority: 50
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(contextComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export declare const contextComponent: PromptComponent;
+/**
+ * Lists loaded plugins.
+ *
+ * Only included if plugins are available.
+ * Priority: 68
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(pluginsComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export declare const pluginsComponent: PromptComponent;
+/**
+ * Provides information about permission mode.
+ *
+ * Only included if permission mode is set.
+ * Priority: 55
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(permissionModeComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export declare const permissionModeComponent: PromptComponent;
+/**
+ * Creates a prompt builder with sensible defaults.
+ *
+ * Includes the following components by default:
+ * - `identity`: Basic agent identity
+ * - `tools-listing`: Available tools
+ * - `skills-listing`: Available skills
+ * - `plugins-listing`: Loaded plugins
+ * - `capabilities`: Backend capabilities
+ * - `permission-mode`: Permission mode info
+ * - `context`: Conversation context
+ *
+ * You can customize by cloning and modifying:
+ *
+ * @example
+ * ```typescript
+ * // Use defaults
+ * const agent = createAgent({
+ *   model,
+ *   // No systemPrompt = uses default builder automatically
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Customize defaults
+ * const builder = createDefaultPromptBuilder()
+ *   .unregister('identity')
+ *   .register({
+ *     name: 'custom-identity',
+ *     priority: 100,
+ *     render: () => 'You are a specialized coding assistant.',
+ *   });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   promptBuilder: builder,
+ * });
+ * ```
+ *
+ * @returns A PromptBuilder with default components registered
+ *
+ * @category Prompt Builder
+ */
+export declare function createDefaultPromptBuilder(): PromptBuilder;
+//# sourceMappingURL=components.d.ts.map

package/dist/prompt-builder/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/prompt-builder/components.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,EAAE,eAI/B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,EAAE,eAQ5B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,EAAE,eAQ7B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,EAAE,eA6BnC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAqB9B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAQ9B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAsBrC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,0BAA0B,IAAI,aAAa,CAU1D"}

package/dist/prompt-builder/components.js

@@ -0,0 +1,252 @@
+/**
+ * Default prompt components for common use cases.
+ *
+ * @packageDocumentation
+ */
+import { PromptBuilder } from "./index.js";
+/**
+ * Default identity component providing a basic agent identity.
+ *
+ * Priority: 100 (highest)
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(identityComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export const identityComponent = {
+    name: "identity",
+    priority: 100,
+    render: () => "You are a helpful AI assistant.",
+};
+/**
+ * Lists available tools in the system prompt.
+ *
+ * Only included if tools are available.
+ * Priority: 70
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(toolsComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export const toolsComponent = {
+    name: "tools-listing",
+    priority: 70,
+    condition: (ctx) => ctx.tools !== undefined && ctx.tools.length > 0,
+    render: (ctx) => {
+        const toolLines = ctx.tools.map((t) => `- **${t.name}**: ${t.description}`);
+        return `# Available Tools\n\nYou have access to the following tools:\n${toolLines.join("\n")}`;
+    },
+};
+/**
+ * Lists available skills in the system prompt.
+ *
+ * Only included if skills are available.
+ * Priority: 65
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(skillsComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export const skillsComponent = {
+    name: "skills-listing",
+    priority: 65,
+    condition: (ctx) => ctx.skills !== undefined && ctx.skills.length > 0,
+    render: (ctx) => {
+        const skillLines = ctx.skills.map((s) => `- **${s.name}**: ${s.description}`);
+        return `# Available Skills\n\nYou can activate these skills on-demand:\n${skillLines.join("\n")}`;
+    },
+};
+/**
+ * Lists agent capabilities based on backend and configuration.
+ *
+ * Priority: 60
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(capabilitiesComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export const capabilitiesComponent = {
+    name: "capabilities",
+    priority: 60,
+    render: (ctx) => {
+        const capabilities = [];
+        if (ctx.backend?.hasExecuteCapability) {
+            capabilities.push("- Execute shell commands (bash)");
+        }
+        if (ctx.backend?.type === "filesystem") {
+            capabilities.push("- Read and write files to the filesystem");
+            if (ctx.backend.rootDir) {
+                capabilities.push(`- Working directory: ${ctx.backend.rootDir}`);
+            }
+        }
+        else if (ctx.backend?.type === "state") {
+            capabilities.push("- In-memory file operations (sandboxed)");
+        }
+        if (ctx.state?.todos && ctx.state.todos.length > 0) {
+            capabilities.push(`- ${ctx.state.todos.length} active task(s) in the task list`);
+        }
+        if (capabilities.length === 0) {
+            return "";
+        }
+        return `# Capabilities\n\n${capabilities.join("\n")}`;
+    },
+};
+/**
+ * Provides context about the current conversation.
+ *
+ * Only included if thread ID or messages are available.
+ * Priority: 50
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(contextComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export const contextComponent = {
+    name: "context",
+    priority: 50,
+    condition: (ctx) => !!ctx.threadId || !!(ctx.currentMessages && ctx.currentMessages.length > 0),
+    render: (ctx) => {
+        const parts = [];
+        if (ctx.threadId) {
+            parts.push(`- Thread ID: ${ctx.threadId}`);
+        }
+        if (ctx.currentMessages && ctx.currentMessages.length > 0) {
+            parts.push(`- Conversation history: ${ctx.currentMessages.length} message(s)`);
+        }
+        if (parts.length === 0) {
+            return "";
+        }
+        return `# Context\n\n${parts.join("\n")}`;
+    },
+};
+/**
+ * Lists loaded plugins.
+ *
+ * Only included if plugins are available.
+ * Priority: 68
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(pluginsComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export const pluginsComponent = {
+    name: "plugins-listing",
+    priority: 68,
+    condition: (ctx) => ctx.plugins !== undefined && ctx.plugins.length > 0,
+    render: (ctx) => {
+        const pluginLines = ctx.plugins.map((p) => `- **${p.name}**: ${p.description}`);
+        return `# Loaded Plugins\n\n${pluginLines.join("\n")}`;
+    },
+};
+/**
+ * Provides information about permission mode.
+ *
+ * Only included if permission mode is set.
+ * Priority: 55
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder().register(permissionModeComponent);
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export const permissionModeComponent = {
+    name: "permission-mode",
+    priority: 55,
+    condition: (ctx) => !!ctx.permissionMode,
+    render: (ctx) => {
+        const mode = ctx.permissionMode;
+        let description = "";
+        if (mode === "default") {
+            description = "Default permission mode: tools may require approval based on safety rules.";
+        }
+        else if (mode === "acceptEdits") {
+            description = "File editing tools are auto-approved; other tools may require approval.";
+        }
+        else if (mode === "bypassPermissions") {
+            description = "All tools are auto-approved without permission checks.";
+        }
+        else if (mode === "plan") {
+            description = "Plan mode: tool use is planned but not executed.";
+        }
+        else {
+            description = `Permission mode: ${String(mode)}`;
+        }
+        return `# Permission Mode\n\n${description}`;
+    },
+};
+/**
+ * Creates a prompt builder with sensible defaults.
+ *
+ * Includes the following components by default:
+ * - `identity`: Basic agent identity
+ * - `tools-listing`: Available tools
+ * - `skills-listing`: Available skills
+ * - `plugins-listing`: Loaded plugins
+ * - `capabilities`: Backend capabilities
+ * - `permission-mode`: Permission mode info
+ * - `context`: Conversation context
+ *
+ * You can customize by cloning and modifying:
+ *
+ * @example
+ * ```typescript
+ * // Use defaults
+ * const agent = createAgent({
+ *   model,
+ *   // No systemPrompt = uses default builder automatically
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Customize defaults
+ * const builder = createDefaultPromptBuilder()
+ *   .unregister('identity')
+ *   .register({
+ *     name: 'custom-identity',
+ *     priority: 100,
+ *     render: () => 'You are a specialized coding assistant.',
+ *   });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   promptBuilder: builder,
+ * });
+ * ```
+ *
+ * @returns A PromptBuilder with default components registered
+ *
+ * @category Prompt Builder
+ */
+export function createDefaultPromptBuilder() {
+    return new PromptBuilder().registerMany([
+        identityComponent,
+        toolsComponent,
+        skillsComponent,
+        pluginsComponent,
+        capabilitiesComponent,
+        permissionModeComponent,
+        contextComponent,
+    ]);
+}
+//# sourceMappingURL=components.js.map

package/dist/prompt-builder/components.js.map

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

package/dist/prompt-builder/index.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Prompt builder system for creating dynamic, context-aware system prompts.
+ *
+ * @packageDocumentation
+ */
+import type { ModelMessage } from "ai";
+import type { AgentState } from "../backends/state.js";
+import type { PermissionMode } from "../types.js";
+/**
+ * Context available to prompt components when building prompts.
+ * Contains all relevant agent state and configuration.
+ *
+ * @category Prompt Builder
+ */
+export interface PromptContext {
+    /**
+     * Tools available to the agent.
+     * Each entry includes the tool name and description.
+     */
+    tools?: Array<{
+        name: string;
+        description: string;
+    }>;
+    /**
+     * Skills available to the agent.
+     * Each entry includes the skill name and description.
+     */
+    skills?: Array<{
+        name: string;
+        description: string;
+    }>;
+    /**
+     * Plugins loaded by the agent.
+     * Each entry includes the plugin name and description.
+     */
+    plugins?: Array<{
+        name: string;
+        description: string;
+    }>;
+    /**
+     * Information about the backend being used.
+     */
+    backend?: {
+        /** Type of backend (e.g., 'filesystem', 'state') */
+        type: string;
+        /** Whether the backend supports command execution */
+        hasExecuteCapability: boolean;
+        /** Root directory for filesystem backends */
+        rootDir?: string;
+    };
+    /**
+     * Agent state for accessing todos and other state.
+     */
+    state?: AgentState;
+    /**
+     * Model identifier being used.
+     */
+    model?: string;
+    /**
+     * Maximum number of tool call steps allowed.
+     */
+    maxSteps?: number;
+    /**
+     * Permission mode for the agent.
+     */
+    permissionMode?: PermissionMode;
+    /**
+     * Current conversation messages (available during generation).
+     */
+    currentMessages?: ModelMessage[];
+    /**
+     * Thread ID for the current conversation (if any).
+     */
+    threadId?: string;
+    /**
+     * Custom user-defined data that can be passed to components.
+     */
+    custom?: Record<string, unknown>;
+}
+/**
+ * A component that contributes to the system prompt.
+ *
+ * Components are sorted by priority (higher = rendered earlier in prompt)
+ * and can conditionally include themselves based on context.
+ *
+ * @example
+ * ```typescript
+ * const toolsComponent: PromptComponent = {
+ *   name: 'tools-listing',
+ *   priority: 70,
+ *   condition: (ctx) => ctx.tools !== undefined && ctx.tools.length > 0,
+ *   render: (ctx) => {
+ *     const toolLines = ctx.tools!.map((t) => `- **${t.name}**: ${t.description}`);
+ *     return `# Available Tools\n\n${toolLines.join('\n')}`;
+ *   },
+ * };
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export interface PromptComponent {
+    /**
+     * Unique identifier for this component.
+     * Used for unregistering components.
+     */
+    name: string;
+    /**
+     * Priority for ordering components in the final prompt.
+     * Higher priority components are rendered first.
+     * @defaultValue 50
+     */
+    priority?: number;
+    /**
+     * Optional condition to determine if this component should be included.
+     * If not provided or returns true, the component is included.
+     * @param ctx - The prompt context
+     * @returns true to include this component, false to skip it
+     */
+    condition?: (ctx: PromptContext) => boolean;
+    /**
+     * Render the component's contribution to the prompt.
+     * @param ctx - The prompt context
+     * @returns The text to include in the system prompt
+     */
+    render: (ctx: PromptContext) => string;
+}
+/**
+ * Builder for constructing dynamic system prompts from components.
+ *
+ * The PromptBuilder manages a collection of components that are combined
+ * to create the final system prompt. Components are sorted by priority
+ * and can conditionally include themselves.
+ *
+ * @example
+ * ```typescript
+ * const builder = new PromptBuilder()
+ *   .register({
+ *     name: 'identity',
+ *     priority: 100,
+ *     render: () => 'You are a helpful assistant.',
+ *   })
+ *   .register({
+ *     name: 'tools',
+ *     priority: 70,
+ *     condition: (ctx) => ctx.tools && ctx.tools.length > 0,
+ *     render: (ctx) => `Tools: ${ctx.tools!.map(t => t.name).join(', ')}`,
+ *   });
+ *
+ * const prompt = builder.build({ tools: [{ name: 'read', description: 'Read files' }] });
+ * ```
+ *
+ * @category Prompt Builder
+ */
+export declare class PromptBuilder {
+    private components;
+    /**
+     * Register a single component.
+     *
+     * If a component with the same name already exists, it will be replaced.
+     *
+     * @param component - The component to register
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.register({
+     *   name: 'custom',
+     *   priority: 80,
+     *   render: () => 'Custom instructions',
+     * });
+     * ```
+     */
+    register(component: PromptComponent): this;
+    /**
+     * Register multiple components at once.
+     *
+     * @param components - Array of components to register
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.registerMany([
+     *   identityComponent,
+     *   toolsComponent,
+     *   skillsComponent,
+     * ]);
+     * ```
+     */
+    registerMany(components: PromptComponent[]): this;
+    /**
+     * Remove a component by name.
+     *
+     * @param name - The name of the component to remove
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.unregister('identity');
+     * ```
+     */
+    unregister(name: string): this;
+    /**
+     * Build the final prompt from the registered components.
+     *
+     * Components are:
+     * 1. Filtered by their condition functions (if present)
+     * 2. Sorted by priority (higher priority first)
+     * 3. Rendered and joined with double newlines
+     *
+     * @param context - The context to pass to components
+     * @returns The final system prompt string
+     *
+     * @example
+     * ```typescript
+     * const context: PromptContext = {
+     *   tools: [{ name: 'read', description: 'Read files' }],
+     *   model: 'claude-3-5-sonnet-20241022',
+     * };
+     * const prompt = builder.build(context);
+     * ```
+     */
+    build(context: PromptContext): string;
+    /**
+     * Clone this builder with all its registered components.
+     *
+     * Useful for creating variants of a base builder.
+     *
+     * @returns A new PromptBuilder with the same components
+     *
+     * @example
+     * ```typescript
+     * const base = createDefaultPromptBuilder();
+     * const custom = base.clone().register({
+     *   name: 'custom',
+     *   render: () => 'Additional instructions',
+     * });
+     * ```
+     */
+    clone(): PromptBuilder;
+    /**
+     * Get all registered component names.
+     * Useful for debugging and introspection.
+     *
+     * @returns Array of component names
+     */
+    getComponentNames(): string[];
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/prompt-builder/index.d.ts.map

@@ -0,0 +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"}