illuma-agents 1.0.65 → 1.0.67

package/src/graphs/Graph.ts

@@ -731,7 +731,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     const {
       name = 'StructuredResponse',
       mode = 'auto',
-      includeRaw = false,
+      includeRaw: _includeRaw = false,
       handleErrors = true,
       maxRetries = 2,
     } = structuredOutputConfig;
@@ -793,7 +793,6 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         
         // Debug: log what we got back
         console.log('[Graph] Structured output raw result type:', typeof result);
-        console.log('[Graph] Structured output result keys:', result ? Object.keys(result) : 'null');
         if (result?.raw) {
           const rawMsg = result.raw;
           console.log('[Graph] Raw message content type:', typeof rawMsg?.content);
@@ -801,31 +800,17 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           if (rawMsg?.content && typeof rawMsg.content === 'string' && rawMsg.content.length > 0) {
             console.log('[Graph] Raw message text content (first 200):', rawMsg.content.substring(0, 200));
           }
-          // Log the parsed result if available
-          if (result?.parsed) {
-            console.log('[Graph] Parsed result keys:', Object.keys(result.parsed));
-          }
         }
 
         // Handle response - we always use includeRaw internally
         if (result?.raw && result?.parsed !== undefined) {
-          console.log('[Graph] Using parsed result from structured output');
           return {
             structuredResponse: result.parsed as Record<string, unknown>,
             rawMessage: result.raw as AIMessageChunk,
           };
         }
 
-        // Fallback: If result itself is the parsed object (no raw wrapper)
-        if (result && typeof result === 'object' && !result.raw && !result.parsed) {
-          console.log('[Graph] Result is the structured object directly');
-          return {
-            structuredResponse: result as Record<string, unknown>,
-          };
-        }
-
         // Fallback for models that don't support includeRaw
-        console.log('[Graph] Using fallback - treating result as structured response');
         return {
           structuredResponse: result as Record<string, unknown>,
         };
@@ -1151,17 +1136,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       );
 
       // Check if structured output mode is enabled
-      // IMPORTANT: If tools are available, we need to let the model use them first.
-      // Only use structured output when:
-      // 1. No tools are configured, OR
-      // 2. The model has already used tools and is ready to give final response
-      const hasTools = agentContext.tools && agentContext.tools.length > 0;
-      const shouldUseStructuredOutputNow = 
+      if (
         agentContext.isStructuredOutputMode &&
-        agentContext.structuredOutput &&
-        !hasTools; // Only use structured output immediately if no tools
-
-      if (shouldUseStructuredOutputNow) {
+        agentContext.structuredOutput
+      ) {
         const schema = agentContext.getStructuredOutputSchema();
         if (!schema) {
           throw new Error('Structured output schema is not configured');
@@ -1206,16 +1184,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             clientOptions: structuredClientOptions,
           });
 
-          // For no-tools case, we pass the original messages directly
-          // There shouldn't be thinking blocks since this is the first invocation
-
           const { structuredResponse, rawMessage } =
             await this.attemptStructuredInvoke(
               {
                 currentModel: structuredModel,
                 finalMessages,
                 schema,
-                structuredOutputConfig: agentContext.structuredOutput!,
+                structuredOutputConfig: agentContext.structuredOutput,
                 provider: agentContext.provider,
               },
               config
@@ -1488,136 +1463,6 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
       if (!result) {
         throw new Error('No result after model invocation');
       }
-
-      // Check if we need to apply structured output for the final response
-      // This handles the case where tools were used, and now the model is giving its final answer
-      const resultMessage = result.messages?.[0] as AIMessageChunk | undefined;
-      const hasToolCalls = (resultMessage?.tool_calls?.length ?? 0) > 0;
-      
-      if (
-        agentContext.isStructuredOutputMode &&
-        agentContext.structuredOutput &&
-        !hasToolCalls && // Model is giving final response (no tool calls)
-        hasTools // We skipped structured output earlier because tools were available
-      ) {
-        const schema = agentContext.getStructuredOutputSchema();
-        if (schema) {
-          try {
-            console.log('[Graph] Applying structured output for final response after tool execution');
-            
-            // Get a fresh model for structured output
-            const structuredClientOptions = { ...agentContext.clientOptions } as t.ClientOptions;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            (structuredClientOptions as any).streaming = false;
-
-            // Remove thinking configuration
-            if (agentContext.provider === Providers.BEDROCK) {
-              const bedrockOpts = structuredClientOptions as t.BedrockAnthropicClientOptions;
-              if (bedrockOpts.additionalModelRequestFields) {
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                const additionalFields = Object.assign({}, bedrockOpts.additionalModelRequestFields) as any;
-                delete additionalFields.thinking;
-                delete additionalFields.budgetTokens;
-                bedrockOpts.additionalModelRequestFields = additionalFields;
-              }
-            }
-            if (agentContext.provider === Providers.ANTHROPIC) {
-              const anthropicOpts = structuredClientOptions as t.AnthropicClientOptions;
-              if (anthropicOpts.thinking) {
-                delete anthropicOpts.thinking;
-              }
-            }
-
-            const structuredModel = this.getNewModel({
-              provider: agentContext.provider,
-              clientOptions: structuredClientOptions,
-            });
-
-            // Following LangGraph's Option 2 pattern:
-            // Instead of passing the full conversation (which has thinking blocks),
-            // just pass the model's final response text as a HumanMessage asking for structured output.
-            // This avoids issues with thinking blocks and is more token-efficient.
-            let responseContent = '';
-            if (resultMessage) {
-              if (typeof resultMessage.content === 'string') {
-                responseContent = resultMessage.content;
-              } else if (Array.isArray(resultMessage.content)) {
-                // Extract text parts only (skip thinking blocks, tool_use, etc.)
-                responseContent = resultMessage.content
-                  .filter((c): c is { type: string; text: string } => 
-                    typeof c === 'object' && c !== null && 
-                    (c as { type?: string }).type === 'text' && 
-                    typeof (c as { text?: string }).text === 'string'
-                  )
-                  .map(c => c.text)
-                  .join('\n');
-              }
-            }
-
-            if (!responseContent) {
-              console.log('[Graph] No response content to structure, skipping');
-              throw new Error('No response content available for structured output');
-            }
-
-            console.log('[Graph] Structuring response content (first 200 chars):', responseContent.substring(0, 200));
-
-            // Create a simple message asking to structure the response
-            const structuredMessages: BaseMessage[] = [
-              new HumanMessage({
-                content: `Based on the following response, extract and return the data in the required structured format:\n\n${responseContent}`,
-              }),
-            ];
-
-            const { structuredResponse, rawMessage } =
-              await this.attemptStructuredInvoke(
-                {
-                  currentModel: structuredModel,
-                  finalMessages: structuredMessages,
-                  schema,
-                  structuredOutputConfig: agentContext.structuredOutput!,
-                  provider: agentContext.provider,
-                },
-                config
-              );
-
-            // Emit structured output event
-            await safeDispatchCustomEvent(
-              GraphEvents.ON_STRUCTURED_OUTPUT,
-              {
-                structuredResponse,
-                schema,
-                raw: rawMessage,
-              },
-              config
-            );
-
-            agentContext.currentUsage = rawMessage
-              ? this.getUsageMetadata(rawMessage)
-              : undefined;
-            this.cleanupSignalListener();
-
-            // Return clean message without tool_calls
-            let cleanMessage: AIMessageChunk | undefined;
-            if (rawMessage) {
-              cleanMessage = new AIMessageChunk({
-                content: JSON.stringify(structuredResponse, null, 2),
-                id: rawMessage.id,
-                response_metadata: rawMessage.response_metadata,
-                usage_metadata: rawMessage.usage_metadata,
-              });
-            }
-
-            return {
-              messages: cleanMessage ? [cleanMessage] : [],
-              structuredResponse,
-            };
-          } catch (structuredError) {
-            console.error('[Graph] Structured output failed after tool execution:', structuredError);
-            // Fall through to return normal result
-          }
-        }
-      }
-
       agentContext.currentUsage = this.getUsageMetadata(result.messages?.[0]);
       this.cleanupSignalListener();
       return result;

package/src/index.ts

@@ -14,11 +14,15 @@ export * from './tools/CodeExecutor';
 export * from './tools/BrowserTools';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/ToolSearch';
+export * from './tools/TaskProgress';
 export * from './tools/ToolNode';
 export * from './tools/schema';
 export * from './tools/handlers';
 export * from './tools/search';
 
+/* Prompts */
+export * from './prompts';
+
 /* Schemas */
 export * from './schemas';
 

package/src/messages/format.ts

@@ -934,63 +934,3 @@ export function ensureThinkingBlockInMessages(
 
   return result;
 }
-
-/**
- * Strips thinking blocks from messages for structured output invocation.
- * When switching from thinking-enabled mode to structured output (which requires thinking disabled),
- * we need to remove thinking/reasoning blocks from the conversation to avoid Bedrock errors.
- *
- * @param messages - Array of messages to process
- * @returns The messages array with thinking blocks stripped from AI messages
- */
-export function stripThinkingBlocksFromMessages(
-  messages: BaseMessage[]
-): BaseMessage[] {
-  return messages.map((msg) => {
-    const isAI = msg instanceof AIMessage || msg instanceof AIMessageChunk;
-    
-    if (!isAI) {
-      return msg;
-    }
-    
-    const aiMsg = msg as AIMessage | AIMessageChunk;
-    const content = aiMsg.content;
-    
-    // If content is not an array, nothing to strip
-    if (!Array.isArray(content)) {
-      return msg;
-    }
-    
-    // Filter out thinking/reasoning blocks
-    const filteredContent = content.filter((c) => {
-      if (typeof c !== 'object' || c === null) {
-        return true;
-      }
-      const type = (c as ExtendedMessageContent).type;
-      return (
-        type !== ContentTypes.THINKING &&
-        type !== ContentTypes.REASONING_CONTENT &&
-        type !== ContentTypes.REASONING &&
-        type !== 'thinking' &&
-        type !== 'redacted_thinking'
-      );
-    });
-    
-    // If no content left after filtering, add a placeholder
-    if (filteredContent.length === 0) {
-      filteredContent.push({
-        type: 'text',
-        text: '(previous response)',
-      });
-    }
-    
-    // Create a new AI message with the filtered content
-    return new AIMessageChunk({
-      content: filteredContent,
-      id: aiMsg.id,
-      response_metadata: aiMsg.response_metadata,
-      usage_metadata: aiMsg.usage_metadata,
-      // Don't include tool_calls - we're stripping those for structured output context
-    });
-  });
-}

package/src/prompts/index.ts

@@ -1,2 +1,3 @@
 export * from './collab';
-export * from './taskmanager';
+export * from './taskmanager';
+export * from './taskplanning';

package/src/prompts/taskplanning.ts

@@ -0,0 +1,96 @@
+// src/prompts/taskplanning.ts
+
+/**
+ * System prompt fragment for task planning capabilities.
+ *
+ * Include this in the agent's system prompt when:
+ * - Agent is ephemeral (not a persistent workflow)
+ * - Agent handles complex, multi-step research or coding tasks
+ * - You want visible progress tracking for the user
+ *
+ * Do NOT include for:
+ * - Simple tool-calling agents
+ * - Workflow/builder agents with predefined steps
+ * - Agents with fixed execution patterns
+ */
+export const taskPlanningPrompt = `## Task Planning & Progress
+
+You have access to a \`manage_todo_list\` tool for tracking complex tasks.
+
+### When to Use Task Planning
+- **USE** for complex work requiring 3+ steps (research, multi-file changes, analysis)
+- **SKIP** for simple requests (single file edit, quick lookup, conversational responses)
+
+### Task Workflow
+1. **Plan First**: Before starting complex work, create a todo list with 3-6 clear, actionable items
+2. **One at a Time**: Mark ONE task as "in-progress" before starting work on it
+3. **Multiple Tool Calls OK**: A single task may require multiple tool calls (searches, reads, writes)
+4. **Complete Immediately**: Mark task "completed" right after finishing, don't batch updates
+5. **Iterate**: Move to next task, repeat until done
+
+### Task Best Practices
+- Keep titles short and action-oriented (3-7 words): "Research API options", "Implement auth flow"
+- Group related work into single tasks rather than micro-tasks
+- Update status promptly so user sees real-time progress
+- For simple 1-2 step work, just do it directly without creating todos
+
+### Example Task Breakdown
+For "Add user authentication to the app":
+1. Review existing auth code and dependencies
+2. Implement login endpoint
+3. Add session management
+4. Create protected route middleware
+5. Test authentication flow
+
+Each task above might involve multiple file reads, code writes, and searches - that's expected.
+`;
+
+/**
+ * Short version of task planning prompt for constrained context
+ */
+export const taskPlanningPromptShort = `## Task Tracking
+Use \`manage_todo_list\` for complex multi-step work (3+ steps).
+- Create 3-6 actionable todos before starting
+- Mark one "in-progress" at a time
+- Mark "completed" immediately after finishing
+- Skip for simple 1-2 step tasks
+`;
+
+/**
+ * Function description for structured output agents
+ */
+export const manageTodoListFunctionDescription =
+  'Manage a todo list for tracking progress on complex multi-step tasks. Create todos before starting work, mark in-progress while working, mark completed when done.';
+
+/**
+ * Function parameters schema (for agents using function calling format)
+ */
+export const manageTodoListFunctionParameters = {
+  type: 'object',
+  properties: {
+    todoList: {
+      type: 'array',
+      description: 'Complete array of all todo items (existing and new)',
+      items: {
+        type: 'object',
+        properties: {
+          id: {
+            type: 'number',
+            description: 'Sequential ID starting from 1',
+          },
+          title: {
+            type: 'string',
+            description: 'Short action-oriented title (3-7 words)',
+          },
+          status: {
+            type: 'string',
+            enum: ['not-started', 'in-progress', 'completed'],
+            description: 'Current task status',
+          },
+        },
+        required: ['id', 'title', 'status'],
+      },
+    },
+  },
+  required: ['todoList'],
+};