[ARCHITECTURE/DOC] Improve Task Execution Model and Documentation

[darielnoel]

Context

Based on user feedback (from Saro), we've identified critical gaps in both our architecture and documentation regarding task execution and state management. The user attempted to implement pre/post processing hooks through a non-existent execute() function, highlighting several important issues:

1. Missing Extension Points

   • Users are looking for clear ways to hook into task lifecycle
   • No obvious way to add pre/post processing around task execution
   • Lack of clear extension points for customizing agent behavior

2. Architecture Visibility

   • The current task execution model (workOnTask, agenticLoop) is not clearly exposed
   • State management through the store system isn't immediately obvious
   • Task lifecycle events and hooks aren't discoverable

3. Mental Model Mismatch

   • Users expect familiar patterns (like React's hooks) for extending functionality
   • The framework's actual architecture (store-based state management, task lifecycle) isn't intuitive
   • Gap between user expectations and framework design

Impact

These issues are causing:

• Users to attempt implementing features in ways that won't work
• Confusion about how to properly extend the framework
• Missed opportunities to use built-in features
• Extra development effort trying to work around framework limitations

Proposed Solutions

1. Architecture Enhancements

// Example of potential new extension points
class Agent extends BaseAgent {
// Clear lifecycle hooks
onTaskStart?: (task: Task) => Promise<void>;
onTaskComplete?: (task: Task, result: any) => Promise<void>;
// Pre/post processing hooks
beforeThinking?: (context: TaskContext) => Promise<void>;
afterThinking?: (context: TaskContext, result: any) => Promise<void>;
// Tool execution hooks
beforeToolExecution?: (tool: Tool, input: any) => Promise<void>;
afterToolExecution?: (tool: Tool, result: any) => Promise<void>;
}

2. Documentation Improvements

   • Add a "Task Lifecycle" guide explaining the execution flow
   • Create an "Extension Points" section in docs
   • Document the store-based state management system
   • Provide examples of common customization patterns

3. Developer Experience

   • Add TypeScript types for all extension points
   • Create a debugging guide for task execution
   • Add logging/tracing options for task lifecycle
   • Provide example implementations of common patterns

Questions to Consider

1. What are the most common extension points users need?
2. How can we make the architecture more discoverable?
3. What patterns from other frameworks should we support?
4. How can we better communicate the framework's mental model?