feature

Feature Implementation

Implement the following feature: $ARGUMENTS

Live Project State

• Version: !grep -m1 __version__ src/selectools/__init__.py
• Tests: !pytest tests/ --collect-only -q 2>/dev/null | tail -1
• Last example: !ls examples/*.py | tail -1
• Next example number: use the next zero-padded number after the last one above
• StepTypes: !python3 -c "from selectools.trace import StepType; print(len(StepType))" 2>/dev/null
• Observer events: !python3 -c "from selectools.observer import AgentObserver; import inspect; print(len([m for m in dir(AgentObserver) if m.startswith('on_')]))" 2>/dev/null

1. Cross-Feature Impact Analysis

Before writing code, determine:

• Does this touch agent/core.py? If so, follow the execution flow: _prepare_run → cancellation check → budget check → model selection → on_iteration_start → provider call → _process_response → guardrails → parser → policy → coherence → tool execution → post-tool cancellation check → on_iteration_end
• Does AgentConfig in agent/config.py need new fields?
• Does __init__.py need new public exports?
• Does trace.py need new StepType values? (currently 16)
• Does observer.py need new events? If so, add to ALL FOUR classes:
  • AgentObserver (no-op default)
  • AsyncAgentObserver (async no-op)
  • LoggingObserver (JSON emission via _emit())
  • SimpleStepObserver (delegate to self._cb())
• Does AgentResult need new fields?
• Update tests/test_phase1_design_patterns.py StepType count if adding new types

2. Write Source Code

New module pattern:

"""Module docstring — one line."""

from __future__ import annotations

from dataclasses import dataclass
from typing import Any, Dict, List, Optional

# Lazy imports for optional deps
try:
    import some_lib
except ImportError:
    some_lib = None  # type: ignore[assignment]

For agent loop changes — add to the shared helpers (_check_budget, _build_cancelled_result, etc.) rather than duplicating in run()/arun()/astream(). Use _RunContext to carry per-run state.