06中间件：给 Agent 叠能力

// TypedChatModelAgentMiddleware defines the interface for customizing TypedChatModelAgent behavior.
//
// IMPORTANT: This interface is specifically designed for TypedChatModelAgent and agents built
// on top of it (e.g., DeepAgent).
//
// Why TypedChatModelAgentMiddleware instead of AgentMiddleware?
//
// AgentMiddleware is a struct type, which has inherent limitations:
//   - Struct types are closed: users cannot add new methods to extend functionality
//   - The framework only recognizes AgentMiddleware's fixed fields, so even if users
//     embed AgentMiddleware in a custom struct and add methods, the framework cannot
//     call those methods (config.Middlewares is []AgentMiddleware, not a user type)
//   - Callbacks in AgentMiddleware only return error, cannot return modified context
//
// TypedChatModelAgentMiddleware is an interface type, which is open for extension:
//   - Users can implement custom handlers with arbitrary internal state and methods
//   - Hook methods return (context.Context, ..., error) for direct context propagation
//   - Wrapper methods (WrapToolCall, WrapModel) enable context propagation through the
//     wrapped endpoint chain: wrappers can pass modified context to the next wrapper
//   - Configuration is centralized in struct fields rather than scattered in closures
//
// TypedChatModelAgentMiddleware vs AgentMiddleware:
//   - Use AgentMiddleware for simple, static additions (extra instruction/tools)
//   - Use TypedChatModelAgentMiddleware for dynamic behavior, context modification, or call wrapping
//   - AgentMiddleware is kept for backward compatibility with existing users
//   - Both can be used together; see AgentMiddleware documentation for execution order
//
// Use *TypedBaseChatModelAgentMiddleware as an embedded struct to provide default no-op
// implementations for all methods.
type TypedChatModelAgentMiddleware[M MessageType] interface {
  // BeforeAgent is called before each agent run, allowing modification of
  // the agent's instruction and tools configuration.
  BeforeAgent(ctx context.Context, runCtx *ChatModelAgentContext) (context.Context, *ChatModelAgentContext, error)

  // AfterAgent is called after the agent run reaches a successful terminal state.
  // Successful terminal states are: final answer (model response with no tool calls),
  // and return-directly tool result.
  //
  // AfterAgent is NOT called when the agent terminates with an error (e.g.,
  // ErrExceedMaxIterations, context cancellation, model errors).
  //
  // The state parameter contains the final conversation state, including all messages
  // from the completed run.
  //
  // AfterAgent handlers are called in the same order as BeforeAgent handlers
  // (first registered = first called). Consistent with all other middleware hooks,
  // if any handler returns an error, subsequent handlers are NOT called (fail-fast)
  // and the error is sent to the event stream.
// … 省略 98 行；完整声明 L110–255，点击上方「浏览完整文件」

// ChatModelAgentMiddleware is the default middleware type using *schema.Message.
// See TypedChatModelAgentMiddleware for full documentation.
type ChatModelAgentMiddleware = TypedChatModelAgentMiddleware[*schema.Message]

type TypedBaseChatModelAgentMiddleware[M MessageType] struct{}

// SetRunLocalValue sets a key-value pair that persists for the duration of the current agent Run() invocation.
// The value is scoped to this specific execution and is not shared across different Run() calls or agent instances.
//
// Values stored here are compatible with interrupt/resume cycles - they will be serialized and restored
// when the agent is resumed. For custom types, you must register them using schema.RegisterName[T]()
// in an init() function to ensure proper serialization.
//
// This function can only be called from within a ChatModelAgentMiddleware during agent execution.
// Returns an error if called outside of an agent execution context.
func SetRunLocalValue(ctx context.Context, key string, value any) error {
  if err := checkGobEncodability(key, value); err != nil {
    return err
  }

  err := processTypedState(ctx, func(extra map[string]any) map[string]any {
    if extra == nil {
      extra = make(map[string]any)
    }
    extra[key] = value
    return extra
  })
  if err != nil {
    return fmt.Errorf("SetRunLocalValue failed: must be called within a ChatModelAgent Run() or Resume() execution context: %w", err)
  }

  return nil
}

// GetRunLocalValue retrieves a value that was set during the current agent Run() invocation.
// The value is scoped to this specific execution and is not shared across different Run() calls or agent instances.
//
// Values stored via SetRunLocalValue are compatible with interrupt/resume cycles - they will be serialized
// and restored when the agent is resumed. For custom types, you must register them using schema.RegisterName[T]()
// in an init() function to ensure proper serialization.
//
// This function can only be called from within a ChatModelAgentMiddleware during agent execution.
// Returns the value and true if found, or nil and false if not found or if called outside of an agent execution context.
func GetRunLocalValue(ctx context.Context, key string) (any, bool, error) {
  var val any
  var found bool
  err := processTypedState(ctx, func(extra map[string]any) map[string]any {
    if extra != nil {
      val, found = extra[key]
    }
    return extra
  })
  if err != nil {
    return nil, false, fmt.Errorf("GetRunLocalValue failed: must be called within a ChatModelAgent Run() or Resume() execution context: %w", err)
  }
  return val, found, nil
}

// New constructs and returns the filesystem middleware as a ChatModelAgentMiddleware.
//
// This is the recommended constructor for new code. It returns a ChatModelAgentMiddleware which provides:
//   - Better context propagation through WrapInvokableToolCall and WrapStreamableToolCall methods
//   - BeforeAgent hook for modifying agent instruction and tools at runtime
//   - More flexible extension points compared to the struct-based AgentMiddleware
//
// The middleware provides filesystem tools (ls, read_file, write_file, edit_file, glob, grep)
// and optionally an execute tool if the Backend implements ShellBackend or StreamingShellBackend.
//
// Example usage:
//
//  middleware, err := filesystem.New(ctx, &filesystem.Config{
//      Backend: myBackend,
//  })
//  agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
//      // ...
//      Handlers: []adk.ChatModelAgentMiddleware{middleware},
//  })
func New(ctx context.Context, config *MiddlewareConfig) (adk.ChatModelAgentMiddleware, error) {
  return NewTyped[*schema.Message](ctx, config)
}