Add a simple plan system to the react module

[silvestrid]

Summary

Plan System for ReAct Agent

The ReAct agent now maintains an explicit plan across iterations ‚Äî a list of PlanItem entries with task, status ("todo"/"done"), and done_at_step. Each iteration the LLM outputs plan_updates alongside its usual thought/tool selection:

• {"add": "task description"} ‚Äî add a new todo item
• {"done": <index>} ‚Äî mark an existing item as completed

On the first turn the agent builds its plan; on subsequent turns it marks items done as tools succeed and adds new ones if the task evolves. When all items are done, the agent is force-stopped to call finish, preventing unnecessary extra iterations.

The system prompt was rewritten to reinforce this workflow: reason about what the trajectory and plan show is already done, never repeat successful tool calls, and retry failures only once before reporting.

Also included:

• ask_to_user tool ‚Äî opt-in via enable_ask_to_user=True. The agent can request user clarification mid-execution by raising ConfirmationRequired; the user's response feeds back as an observation via aresume().
• aresume() implementation ‚Äî fully implemented for both ask_to_user and tool-confirmation flows, completing the pending episode and continuing the loop.
• Improved error formatting ‚Äî format_tool_exception() now shows the error message first followed by frames with max_length truncation; new format_validation_error() includes the expected schema so the LLM can self-correct.

Cancellation & Cleanup Fixes

• CancelledError in callbacks ‚Äî with_callbacks async wrapper now catches asyncio.CancelledError (a BaseException in Python 3.9+) so end-callbacks still fire on cancellation.
• Streaming task cleanup ‚Äî Module.astream() now explicitly cancels the background task in its finally block instead of leaving it dangling.
• Loop-closed warnings ‚Äî run_async_with_context() replaced bare asyncio.run with a manual event loop that installs a custom exception handler suppressing harmless "Event loop is closed" errors from httpx/AsyncOpenAI client GC cleanup. Includes proper task cancellation and shutdown sequence.

Documentation Alignment

Comprehensive audit and fix of all documentation to match the actual codebase:

• Architecture docs ‚Äî ADRs, overview, modules (base, predict, react), callbacks, streaming, LM
• Example docs ‚Äî streaming, basic_usage, advanced, context_settings, confirmation, react, dynamic_tools
• README & CLAUDE.md ‚Äî ConfirmationRequired naming, dependency count (5 not 2), project structure
• CHANGELOG ‚Äî backfilled entries for versions 0.1.1 through 0.1.8

Other Changes

• Type checker migration ‚Äî mypy ‚Üí ty across CI, justfile, and pyproject.toml
• Type safety improvements ‚Äî getattr guards, __name__ fallbacks, signature type fixes
• Test updates ‚Äî new test_cancellation.py, updated react and callback tests for plan system

Test plan

• Verify ReAct agent builds a plan on first turn and tracks completion across iterations
• Verify agent force-stops when all plan items are marked done
• Test enable_ask_to_user=True raises ConfirmationRequired and aresume() continues correctly
• Test streaming cancellation doesn't leave dangling tasks or produce warnings
• Run just test ‚Äî all tests pass
• Run just lint ‚Äî no lint errors
• Run just typecheck ‚Äî ty passes

[Copilot]

Pull request overview

This pull request adds a comprehensive plan system to the ReAct agent module, along with improved error handling, cancellation support, and extensive documentation updates.

Changes:

• Introduces a plan system for ReAct agents with PlanItem tracking, plan_updates field, and automatic force-stop when all plan items are complete
• Adds optional ask_to_user tool for agent-initiated clarification requests with full aresume() implementation
• Improves error formatting with format_validation_error() and enhanced format_tool_exception() with consecutive failure detection
• Fixes asyncio cancellation handling in callbacks, streaming task cleanup, and event loop shutdown warnings
• Migrates from mypy to ty for type checking across all CI workflows and configuration files
• Comprehensive documentation alignment across architecture docs, examples, and API references

Reviewed changes

Copilot reviewed 41 out of 43 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/udspy/module/react.py	Core plan system implementation with PlanItem TypedDict, plan_updates handling, ask_to_user tool, and complete aresume() method
src/udspy/utils/formatting.py	Enhanced error formatting with max_length truncation and format_validation_error() helper
src/udspy/utils/async_support.py	Improved run_async_with_context with proper task cancellation and event loop cleanup
src/udspy/module/base.py	Added explicit task cancellation in astream() finally block
src/udspy/callback.py	CancelledError handling in async callback wrapper
src/udspy/settings.py	Fixed typo in UDSPY_LM_MODEL environment variable name and added auto-initialization in configure()
tests/test_react.py	Updated test mocks to include plan_updates field and added test for force-stop behavior
tests/test_module_callbacks.py	Updated all ReAct test mocks with empty plan_updates arrays
tests/test_edge_cases.py	Updated malformed JSON test mocks with plan_updates
tests/test_cancellation.py	New comprehensive cancellation tests for astream, aforward, and callbacks
pyproject.toml	Replaced mypy with ty type checker, removed mypy config, added ty config, updated author info
justfile	Changed typecheck command from mypy to ty
.github/workflows/*.yml	Updated CI workflows to use ty instead of mypy
docs/**/*.md	Extensive documentation updates to align with actual implementation
CHANGELOG.md	Backfilled entries for versions 0.1.1 through 0.1.8
README.md, CLAUDE.md	Updated dependency count and ConfirmationRequired naming

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The lm property creates a new LM instance from the environment variable every time it's accessed if UDSPY_LM_MODEL is set, even if self._lm is already set. This should check if self._lm is None before creating a new instance, similar to the configure() method. Change this to: if self._lm is None and (model := os.getenv("UDSPY_LM_MODEL")): self._lm = LM(model)