feat: add ScaffoldController middleware for configurable ReAct scaffolding

[Alwin4Zhang]

Motivation

This provides a path to optimize the fixed ReActAgent pattern with task-specific scaffold policies, while preserving AgentScope's existing abstractions and keeping scaffold behavior opt-in.

Summary

This PR adds a low-intrusion ScaffoldController layer for AgentScope agents.

The scaffold flow is:

Task -> ScaffoldController -> ScaffoldSpec -> ScaffoldCompiler -> ScaffoldPolicy -> Agent middleware hooks

It keeps the existing Agent/ReAct rollout unchanged and applies scaffold behavior through the current middleware system.

Changes

• Add ScaffoldSpec to describe scaffold runtime policy:

  • system prompt guidance
  • tool subset
  • memory policy
  • retry policy
  • step budget
  • verify policy
  • reward policy

• Add controller/compiler abstractions:

  • ScaffoldControllerBase
  • StaticScaffoldController
  • ModelScaffoldController
  • ScaffoldCompiler

• Add ScaffoldMiddleware integration:

  • on_system_prompt: inject scaffold prompt
  • on_model_call: filter model-visible tools
  • on_reasoning: apply step budget and tool choice policy
  • on_reply: collect lightweight trace summary for later evaluation/store use

• Export scaffold APIs from agentscope.middleware.

• Add tests for:

  • default ornith-1.0 scaffold prompt
  • disabled scaffold behavior
  • custom scaffold config
  • compiler output
  • model-backed scaffold generation
  • tool subset filtering
  • step budget enforcement

Design Notes

The implementation is intentionally non-invasive. It does not modify the core Agent loop, toolkit registration, state model, or ReAct execution logic. Runtime behavior is applied through existing middleware hooks, so users can enable scaffold behavior by configuration or constructor arguments.

ModelScaffoldController allows a stronger model to generate ScaffoldSpec via structured output, while falling back to a static scaffold if generation fails.

Validation

PYTHONPATH=src:tests PYTHONPYCACHEPREFIX=/tmp/agentscope_pycache \
/Users/alwin/miniforge3/envs/agentscope/bin/python -m unittest tests.middleware_test

[github-actions]

This PR is marked as stale because there has been no activity for 60 days. Remove stale label or add new comments or this PR will be closed in 30 days.