@lleverage-ai/agent-sdk 0.0.12 → 0.0.13

package/README.md

@@ -65,7 +65,7 @@ const safeAgent = createAgent({
 });
 ```
 
-**Core tools included:** `read`, `write`, `edit`, `glob`, `grep`, `todo_write`, `bash` (requires backend with `enableBash: true`), `search_tools` (when enabled)
+**Core tools included:** `read`, `write`, `edit`, `glob`, `grep`, `todo_write`, `bash` (requires backend with `enableBash: true`), `skill` (when skills are configured), `search_tools` (when enabled), `call_tool` (proxy mode only)
 
 ### Tools
 
@@ -164,6 +164,8 @@ See [Skills Documentation](./docs/skills.md) for complete details on the skills
 
 Create dynamic, context-aware system prompts from composable components. Instead of static strings, prompts automatically include tools, skills, backend capabilities, and more.
 
+The default prompt builder is cache-friendly: it avoids per-turn dynamic context sections by default so repeated generations in the same thread can reuse provider prompt caches more effectively.
+
 **Using the default builder:**
 ```typescript
 const agent = createAgent({
@@ -354,7 +356,7 @@ export async function POST(req: Request) {
 
 - [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
+- [Tool Loading Strategies](./docs/tool-loading.md) — Eager, deferred discovery, and proxy tool loading
 - [Security & Production](./docs/security.md) — Security policies, guardrails, and secrets filtering
 - [Subagents](./docs/subagents.md) — Task delegation and background tasks
 - [MCP Integration](./docs/mcp.md) — Model Context Protocol tools and servers

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4DH,OAAO,KAAK,EACV,KAAK,EACL,YAAY,EAwBb,MAAM,YAAY,CAAC;AA6pBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CA2zFxD"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4DH,OAAO,KAAK,EACV,KAAK,EACL,YAAY,EAwBb,MAAM,YAAY,CAAC;AA6pBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CAw3FxD"}

package/dist/agent.js

@@ -791,7 +791,8 @@ export function createAgent(options) {
     const hasSubagents = allSubagents.length > 0;
     // In proxy mode, create call_tool and configure search_tools with schema disclosure
     const isProxyMode = pluginLoadingMode === "proxy" || hasProxiedTools;
-    if (isProxyMode && !options.disabledCoreTools?.includes("call_tool")) {
+    const hasProxyTargets = hasProxiedTools || mcpManager.hasExternalServers();
+    if (isProxyMode && hasProxyTargets && !options.disabledCoreTools?.includes("call_tool")) {
         coreTools.call_tool = createCallToolTool({
             mcpManager,
         });
@@ -805,8 +806,8 @@ export function createAgent(options) {
     // - Always auto-load tools when found (no manual load step) — unless proxy mode
     const shouldCreateSearchToolsForAutoThreshold = toolSearchEnabled === "auto" && totalPluginToolCount > toolSearchThreshold;
     const shouldCreateSearchTools = !options.disabledCoreTools?.includes("search_tools") &&
-        (deferredLoadingActive ||
-            isProxyMode ||
+        ((deferredLoadingActive && (totalPluginToolCount > 0 || mcpManager.hasExternalServers())) ||
+            (isProxyMode && hasProxyTargets) ||
             shouldCreateSearchToolsForAutoThreshold ||
             (mcpManager.hasExternalServers() && toolSearchEnabled !== "never"));
     if (shouldCreateSearchTools) {
@@ -919,6 +920,28 @@ export function createAgent(options) {
         // Build prompt using prompt builder
         return promptBuilder.build(context);
     };
+    const responseMessagesToModelMessages = (messages) => Array.isArray(messages) ? messages : [];
+    const appendResponseMessages = (baseMessages, responseMessages, fallbackAssistantText) => {
+        const normalized = responseMessagesToModelMessages(responseMessages);
+        if (normalized.length > 0) {
+            return [...baseMessages, ...normalized];
+        }
+        return fallbackAssistantText
+            ? [...baseMessages, { role: "assistant", content: fallbackAssistantText }]
+            : baseMessages;
+    };
+    const buildMessagesFromStepResponses = (baseMessages, steps, fallbackAssistantText) => {
+        const stepResponseMessages = steps.flatMap((step) => responseMessagesToModelMessages(step.response?.messages));
+        if (stepResponseMessages.length > 0) {
+            return [...baseMessages, ...stepResponseMessages];
+        }
+        // Fallback for providers that do not populate response.messages.
+        const lastText = steps.at(-1)?.text ?? fallbackAssistantText;
+        return [
+            ...baseMessages,
+            ...(lastText ? [{ role: "assistant", content: lastText }] : []),
+        ];
+    };
     // Runtime tools added/removed dynamically by plugins at runtime
     const runtimeTools = {};
     // Helper to get current active tools (core + runtime + MCP + dynamically loaded from registry)
@@ -1616,10 +1639,7 @@ export function createAgent(options) {
                         // cannot find the checkpoint (or finds one without messages/interrupt).
                         if (effectiveGenOptions.threadId && options.checkpointer) {
                             const checkpointThreadId = forkedSessionId ?? effectiveGenOptions.threadId;
-                            const finalMessages = [
-                                ...messages,
-                                ...(response.text ? [{ role: "assistant", content: response.text }] : []),
-                            ];
+                            const finalMessages = appendResponseMessages(messages, response.response?.messages, response.text);
                             const savedCheckpoint = await saveCheckpoint(checkpointThreadId, finalMessages, startStep + response.steps.length);
                             if (savedCheckpoint) {
                                 const withInterrupt = updateCheckpoint(savedCheckpoint, {
@@ -1687,13 +1707,7 @@ export function createAgent(options) {
                     // Save checkpoint - use forked session ID if forking, otherwise use original threadId
                     const checkpointThreadId = forkedSessionId ?? effectiveGenOptions.threadId;
                     if (checkpointThreadId && options.checkpointer) {
-                        // Build final messages including the assistant response.
-                        // Skip empty text to avoid invalid content blocks (e.g. when
-                        // the model finishes with only tool calls).
-                        const finalMessages = [
-                            ...messages,
-                            ...(response.text ? [{ role: "assistant", content: response.text }] : []),
-                        ];
+                        const finalMessages = appendResponseMessages(messages, response.response?.messages, response.text);
                         await saveCheckpoint(checkpointThreadId, finalMessages, startStep + response.steps.length);
                     }
                     // Invoke unified PostGenerate hooks
@@ -1727,12 +1741,7 @@ export function createAgent(options) {
                     let lastResult = finalResult;
                     let runningMessages = hasCheckpointing
                         ? []
-                        : [
-                            ...messages,
-                            ...(finalResult.text
-                                ? [{ role: "assistant", content: finalResult.text }]
-                                : []),
-                        ];
+                        : appendResponseMessages(messages, response.response?.messages, finalResult.text);
                     let followUpPrompt = await getNextTaskPrompt();
                     while (followUpPrompt !== null) {
                         lastResult = await agent.generate({
@@ -2034,11 +2043,12 @@ export function createAgent(options) {
                         }
                     }
                     // Get final result for hooks - need to await all properties
-                    const [text, usage, finishReason, steps] = await Promise.all([
+                    const [text, usage, finishReason, steps, responseMeta] = await Promise.all([
                         response.text,
                         response.usage,
                         response.finishReason,
                         response.steps,
+                        response.response ?? Promise.resolve(undefined),
                     ]);
                     // Only access output if an output schema was provided
                     let output;
@@ -2060,10 +2070,10 @@ export function createAgent(options) {
                     };
                     // Save checkpoint if threadId is provided
                     if (checkpointThreadId && options.checkpointer) {
-                        const finalMessages = [
-                            ...messages,
-                            ...(text ? [{ role: "assistant", content: text }] : []),
-                        ];
+                        const responseMessages = responseMessagesToModelMessages(responseMeta?.messages);
+                        const finalMessages = responseMessages.length > 0
+                            ? [...messages, ...responseMessages]
+                            : buildMessagesFromStepResponses(messages, steps, text);
                         await saveCheckpoint(checkpointThreadId, finalMessages, startStep + steps.length);
                     }
                     // Save pending interrupt to checkpoint (mirrors generate() pattern)
@@ -2111,9 +2121,12 @@ export function createAgent(options) {
                         return;
                     }
                     const hasCheckpointing = !!(effectiveGenOptions.threadId && options.checkpointer);
+                    const initialResponseMessages = responseMessagesToModelMessages(responseMeta?.messages);
                     let currentMessages = hasCheckpointing
                         ? []
-                        : [...messages, ...(text ? [{ role: "assistant", content: text }] : [])];
+                        : initialResponseMessages.length > 0
+                            ? [...messages, ...initialResponseMessages]
+                            : buildMessagesFromStepResponses(messages, steps, text);
                     let followUpPrompt = await getNextTaskPrompt();
                     while (followUpPrompt !== null) {
                         const followUpGen = agent.stream({
@@ -2213,6 +2226,7 @@ export function createAgent(options) {
                     const signalStopCondition = () => signalState.interrupt != null;
                     // Track step count for incremental checkpointing
                     let currentStepCount = 0;
+                    let streamedMessages = [...initialParams.messages];
                     // Execute streamText OUTSIDE createUIMessageStream so errors propagate
                     // to the retry loop (if streamText throws synchronously on creation,
                     // e.g. rate limit, the catch block handles retry/fallback).
@@ -2236,14 +2250,17 @@ export function createAgent(options) {
                             ? async (stepResult) => {
                                 if (effectiveGenOptions.threadId && options.checkpointer) {
                                     currentStepCount++;
-                                    // Build messages including this step's results
-                                    const stepMessages = [
-                                        ...initialParams.messages,
-                                        ...(stepResult.text
-                                            ? [{ role: "assistant", content: stepResult.text }]
-                                            : []),
-                                    ];
-                                    await saveCheckpoint(effectiveGenOptions.threadId, stepMessages, startStep + currentStepCount);
+                                    const stepResponseMessages = responseMessagesToModelMessages(stepResult.response?.messages);
+                                    streamedMessages =
+                                        stepResponseMessages.length > 0
+                                            ? [...streamedMessages, ...stepResponseMessages]
+                                            : stepResult.text
+                                                ? [
+                                                    ...streamedMessages,
+                                                    { role: "assistant", content: stepResult.text },
+                                                ]
+                                                : streamedMessages;
+                                    await saveCheckpoint(effectiveGenOptions.threadId, streamedMessages, startStep + currentStepCount);
                                 }
                             }
                             : undefined,
@@ -2258,12 +2275,7 @@ export function createAgent(options) {
                                 });
                             }
                             if (effectiveGenOptions.threadId && options.checkpointer) {
-                                const finalMessages = [
-                                    ...initialParams.messages,
-                                    ...(finishResult.text
-                                        ? [{ role: "assistant", content: finishResult.text }]
-                                        : []),
-                                ];
+                                const finalMessages = buildMessagesFromStepResponses(initialParams.messages, finishResult.steps, finishResult.text);
                                 await saveCheckpoint(effectiveGenOptions.threadId, finalMessages, startStep + finishResult.steps.length);
                             }
                             // Invoke unified PostGenerate hooks
@@ -2294,8 +2306,9 @@ export function createAgent(options) {
                         execute: async ({ writer }) => {
                             // Merge initial generation into the stream
                             writer.merge(result.toUIMessageStream());
-                            // Wait for initial generation to complete to get final text
-                            const text = await result.text;
+                            // Wait for initial generation to complete
+                            await result.text;
+                            const resultResponse = await (result.response ?? Promise.resolve(undefined));
                             // --- Background task completion loop ---
                             if (waitForBackgroundTasks) {
                                 // Track accumulated steps for checkpoint saves
@@ -2303,7 +2316,7 @@ export function createAgent(options) {
                                 let accumulatedStepCount = initialSteps.length;
                                 let currentMessages = [
                                     ...messages,
-                                    ...(text ? [{ role: "assistant", content: text }] : []),
+                                    ...responseMessagesToModelMessages(resultResponse?.messages),
                                 ];
                                 let followUpPrompt = await getNextTaskPrompt();
                                 while (followUpPrompt !== null) {
@@ -2327,12 +2340,16 @@ export function createAgent(options) {
                                     });
                                     writer.merge(followUpResult.toUIMessageStream());
                                     const followUpText = await followUpResult.text;
+                                    const followUpResponse = await (followUpResult.response ??
+                                        Promise.resolve(undefined));
                                     currentMessages = [
                                         ...currentMessages,
                                         { role: "user", content: followUpPrompt },
-                                        ...(followUpText
-                                            ? [{ role: "assistant", content: followUpText }]
-                                            : []),
+                                        ...(responseMessagesToModelMessages(followUpResponse?.messages).length > 0
+                                            ? responseMessagesToModelMessages(followUpResponse?.messages)
+                                            : followUpText
+                                                ? [{ role: "assistant", content: followUpText }]
+                                                : []),
                                     ];
                                     // --- Post-completion bookkeeping for follow-ups ---
                                     const followUpSteps = await followUpResult.steps;
@@ -2439,6 +2456,7 @@ export function createAgent(options) {
                     };
                     // Track step count for incremental checkpointing
                     let currentStepCount = 0;
+                    let streamedMessages = [...initialParams.messages];
                     // Stop condition: stop when an interrupt signal was caught, OR when
                     // the step count reaches maxSteps.
                     const signalStopCondition = () => signalState.interrupt != null;
@@ -2463,14 +2481,17 @@ export function createAgent(options) {
                             ? async (stepResult) => {
                                 if (effectiveGenOptions.threadId && options.checkpointer) {
                                     currentStepCount++;
-                                    // Build messages including this step's results
-                                    const stepMessages = [
-                                        ...initialParams.messages,
-                                        ...(stepResult.text
-                                            ? [{ role: "assistant", content: stepResult.text }]
-                                            : []),
-                                    ];
-                                    await saveCheckpoint(effectiveGenOptions.threadId, stepMessages, startStep + currentStepCount);
+                                    const stepResponseMessages = responseMessagesToModelMessages(stepResult.response?.messages);
+                                    streamedMessages =
+                                        stepResponseMessages.length > 0
+                                            ? [...streamedMessages, ...stepResponseMessages]
+                                            : stepResult.text
+                                                ? [
+                                                    ...streamedMessages,
+                                                    { role: "assistant", content: stepResult.text },
+                                                ]
+                                                : streamedMessages;
+                                    await saveCheckpoint(effectiveGenOptions.threadId, streamedMessages, startStep + currentStepCount);
                                 }
                             }
                             : undefined,
@@ -2485,12 +2506,7 @@ export function createAgent(options) {
                                 });
                             }
                             if (effectiveGenOptions.threadId && options.checkpointer) {
-                                const finalMessages = [
-                                    ...initialParams.messages,
-                                    ...(finishResult.text
-                                        ? [{ role: "assistant", content: finishResult.text }]
-                                        : []),
-                                ];
+                                const finalMessages = buildMessagesFromStepResponses(initialParams.messages, finishResult.steps, finishResult.text);
                                 await saveCheckpoint(effectiveGenOptions.threadId, finalMessages, startStep + finishResult.steps.length);
                             }
                             // Invoke unified PostGenerate hooks
@@ -2600,6 +2616,7 @@ export function createAgent(options) {
                             };
                             // Track step count for incremental checkpointing
                             let currentStepCount = 0;
+                            let streamedMessages = [...initialParams.messages];
                             // Stop condition: stop when a flow-control signal was caught, OR when
                             // the step count reaches maxSteps.
                             const signalStopCondition = () => signalState.interrupt != null;
@@ -2624,15 +2641,17 @@ export function createAgent(options) {
                                     ? async (stepResult) => {
                                         if (effectiveGenOptions.threadId && options.checkpointer) {
                                             currentStepCount++;
-                                            // Build messages including this step's results
-                                            const stepMessages = [
-                                                ...initialParams.messages,
-                                                {
-                                                    role: "assistant",
-                                                    content: stepResult.text,
-                                                },
-                                            ];
-                                            await saveCheckpoint(effectiveGenOptions.threadId, stepMessages, startStep + currentStepCount);
+                                            const stepResponseMessages = responseMessagesToModelMessages(stepResult.response?.messages);
+                                            streamedMessages =
+                                                stepResponseMessages.length > 0
+                                                    ? [...streamedMessages, ...stepResponseMessages]
+                                                    : stepResult.text
+                                                        ? [
+                                                            ...streamedMessages,
+                                                            { role: "assistant", content: stepResult.text },
+                                                        ]
+                                                        : streamedMessages;
+                                            await saveCheckpoint(effectiveGenOptions.threadId, streamedMessages, startStep + currentStepCount);
                                         }
                                     }
                                     : undefined,
@@ -2647,13 +2666,7 @@ export function createAgent(options) {
                                         });
                                     }
                                     if (effectiveGenOptions.threadId && options.checkpointer) {
-                                        const finalMessages = [
-                                            ...initialParams.messages,
-                                            {
-                                                role: "assistant",
-                                                content: finishResult.text,
-                                            },
-                                        ];
+                                        const finalMessages = buildMessagesFromStepResponses(initialParams.messages, finishResult.steps, finishResult.text);
                                         await saveCheckpoint(effectiveGenOptions.threadId, finalMessages, startStep + finishResult.steps.length);
                                     }
                                     // Invoke unified PostGenerate hooks
@@ -2681,8 +2694,9 @@ export function createAgent(options) {
                             });
                             // Merge the streamText output into the UI message stream
                             writer.merge(result.toUIMessageStream());
-                            // Wait for initial generation to complete to get final text
-                            const text = await result.text;
+                            // Wait for initial generation to complete
+                            await result.text;
+                            const resultResponse = await (result.response ?? Promise.resolve(undefined));
                             // Save pending interrupt to checkpoint (mirrors stream() pattern)
                             if (signalState.interrupt && effectiveGenOptions.threadId && options.checkpointer) {
                                 const interrupt = signalState.interrupt.interrupt;
@@ -2717,7 +2731,7 @@ export function createAgent(options) {
                                 let accumulatedStepCount = initialSteps.length;
                                 let currentMessages = [
                                     ...messages,
-                                    ...(text ? [{ role: "assistant", content: text }] : []),
+                                    ...responseMessagesToModelMessages(resultResponse?.messages),
                                 ];
                                 let followUpPrompt = await getNextTaskPrompt();
                                 while (followUpPrompt !== null) {
@@ -2741,12 +2755,16 @@ export function createAgent(options) {
                                     });
                                     writer.merge(followUpResult.toUIMessageStream());
                                     const followUpText = await followUpResult.text;
+                                    const followUpResponse = await (followUpResult.response ??
+                                        Promise.resolve(undefined));
                                     currentMessages = [
                                         ...currentMessages,
                                         { role: "user", content: followUpPrompt },
-                                        ...(followUpText
-                                            ? [{ role: "assistant", content: followUpText }]
-                                            : []),
+                                        ...(responseMessagesToModelMessages(followUpResponse?.messages).length > 0
+                                            ? responseMessagesToModelMessages(followUpResponse?.messages)
+                                            : followUpText
+                                                ? [{ role: "assistant", content: followUpText }]
+                                                : []),
                                     ];
                                     // --- Post-completion bookkeeping for follow-ups ---
                                     const followUpSteps = await followUpResult.steps;